.fit Reference

Requirements

Python 3.13 or later.
An existing Sphinx project.
An API key provided to you by Sphinx.

The package name is sphinx_learn. The Python import name is sphinx_ai.

createKnowledgeBaseClient

createKnowledgeBaseClient(api_key: str, project_id: str) -> KnowledgeBaseClient

Parameter	Description
`api_key`	The API key provided to you by Sphinx.
`project_id`	The existing project that receives the ingest job.

Document

A document is an input to an ingest job. Currently, the supported document type is:

File: A document supplied as bytes with a source filename or path.

File

File(path: str, content: bytes) File is immutable. Its constructor validates the path and content immediately, raising TypeError for incorrect types or ValueError for invalid values. Create a new File to change its path or content.

Field	Description
`path`	Source filename or relative path, including the extension when applicable. This is an identifier, not a URL to fetch or a local path the SDK opens.
`content`	The document as bytes. For text, make sure it is UTF-8 encoded.

KnowledgeBaseClient.fit

knowledge_base.fit(prompt: str, docs: list[Document]) -> Ingestion

Parameter	Description
`prompt`	Instructions for ingesting the documents.
`docs`	A Python list of documents to ingest in one job. See Document for supported types.

The method validates the prompt, document types, document count, and total content size before uploading, uploads documents sequentially, and then submits one agentic_ingest job. Leading and trailing whitespace is removed from the prompt when the job is submitted.

Input constraints

These limits are enforced locally before any upload. Per-file constraints are checked when you construct each File; prompt and batch constraints are checked by .fit. Size and count limits are inclusive.

Input	Constraint
`prompt`	Must be a string containing non-whitespace text, with at most 10,000 characters before trimming.
`docs`	Must be a Python `list` containing 1–20,000 `File` objects. Tuples, generators, dictionaries, and filenames alone are not accepted.
`File.path`	Must be a string of 1–512 characters using only the characters and path segments described below.
`File.content`	Must be `bytes`, not a string, file handle, or `bytearray`.
Total content size	At most 2.5 GiB (2,684,354,560 bytes) across all documents in one call, measured from the raw content.
Supported binary file size	At most 100 MiB (104,857,600 bytes) per file with a supported binary extension.
Text file size	At most 4 MiB (4,194,304 bytes) per text file.
Text token estimate	At most 250,000 estimated tokens per text file, calculated as the decoded character count divided by four, rounded up.
Content format	Must have a supported binary extension or contain valid UTF-8 text without null bytes.
Structured text	`.json`, `.jsonl`, `.ndjson`, and `.ipynb` must also satisfy the format checks below.

Text files must satisfy both the byte-size and estimated-token limits. The token estimate allows at most 1,000,000 decoded characters per file; it is not a model-specific tokenizer count. An optional UTF-8 byte-order mark counts toward the byte size but is excluded from the decoded character count. The text limits apply to files without a supported binary extension, regardless of their filename.

Source paths

Allowed characters are ASCII letters (A–Z, a–z), digits (0–9), and:

! - _ . * ' ( ) /

Use / to separate path segments. Empty segments and segments equal to . or .. are rejected. Consequently, paths cannot start or end with / or contain //. Spaces, backslashes, colons, and non-ASCII characters are also rejected.

Valid	Invalid	Reason
`handbook.pdf`	`company handbook.pdf`	Space in the filename.
`policies/leave.md`	`/policies/leave.md`	Leading slash creates an empty segment.
`reports/2026/revenue.csv`	`reports/../revenue.csv`	`..` segment.
`notes/team-a.txt`	`notes//team-a.txt`	Empty segment between slashes.

Supported formats

Format	Extensions or requirements
PDF	`.pdf`
Word	`.doc`, `.docx`
PowerPoint	`.ppt`, `.pptx`
Images	`.png`, `.jpg`, `.jpeg`
Spreadsheets	`.xlsx`, `.ods`
Text	Valid UTF-8, optionally with a UTF-8 byte-order mark, and no null bytes. Examples include `.txt`, `.md`, `.csv`, `.json`, and source code.
JSON	`.json` must parse as JSON.
JSON Lines	`.jsonl` and `.ndjson`: each nonblank line must parse as JSON. Blank lines are ignored.
Jupyter notebooks	`.ipynb` must parse as a JSON object containing a `cells` list. Every cell must be an object.

Extension checks are case-insensitive. Any extension outside the binary list, or no extension, takes the text-validation path. For example, a binary .xls or ZIP archive will fail text validation; .xlsx and .ods are the supported binary spreadsheet formats. A filename consisting only of an extension, such as .pdf, is treated as having no extension. For the listed binary extensions, the client does not inspect whether the bytes form a valid document. A corrupt or mislabeled file can pass local validation and fail during ingestion. Renaming an unsupported binary file does not convert it to a supported format. MIME types are inferred from the filename, with application/octet-stream as the fallback.

Failure handling

Error or symptom	What to check
`TypeError`	Check the parameter types, especially `docs` as a list, each item as a `File`, and `content` as bytes.
`ValueError`	Read the validation message for the invalid prompt, path, document count, total size, per-file size, text token estimate, text encoding, JSON, or notebook structure. Fix it before retrying.
`RuntimeError` beginning with `Failed to upload`	An upload returned a non-2xx HTTP status. The message identifies the file and HTTP response. No ingest job has been submitted by this call.
API or network exception	Check connectivity, API key validity, and the project ID. These errors propagate from the underlying clients.
Job URL returned, but ingestion fails later	Open the job URL to inspect the job. Returning a URL confirms submission, not successful processing.

Ingestion.job_url

ingestion.job_url() -> str Returns the job’s Sphinx UI URL.

Home

Setup

Python SDK

Knowledge base

Requirements

createKnowledgeBaseClient

Document

File

KnowledgeBaseClient.fit

Input constraints

Source paths

Supported formats

Failure handling

Ingestion.job_url

​Requirements

​createKnowledgeBaseClient

​Document

​File

​KnowledgeBaseClient.fit

​Input constraints

​Source paths

​Supported formats

​Failure handling

​Ingestion.job_url

Requirements

createKnowledgeBaseClient

Document

File

KnowledgeBaseClient.fit

Input constraints

Source paths

Supported formats

Failure handling

Ingestion.job_url