> ## Documentation Index > Fetch the complete documentation index at: https://docs.sphinx.ai/llms.txt > Use this file to discover all available pages before exploring further. # .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`](#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](#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: ```text theme={null} ! - _ . * ' ( ) / ``` 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.