Python SDK reference - LightOn Developers

Generated from lighton-sdk 1.2.0. Install it and see runnable examples in the quick start.

Client

LightOn

`LightOn.ask()`

ask(
    query: str,
    *,
    workspaces: list[Workspace | int] | None = None,
    tags: list[Tag | int | str] | None = None,
    files: list[File | int] | None = None,
    content_type: list[ContentType | str] | None = None,
    attribute: list[str] | None = None,
    max_results: int | None = None,
    relevance_scoring: RelevanceScoring | None = None,
    model: str | None = None,
    schema: type[BaseModel] | dict[str, Any] | None = None,
    stream: bool = False,
) -> AskResponse | Generator[AskEvent, None, None]

POST /api/v3/ask, ask a grounded question over indexed documents. Arguments

Name	Type	Description
`query`	`str`	Natural-language question (max 1500 chars).
`workspaces`	`list[Workspace \| int] \| None`	Restrict to these workspaces (Workspace objects or ids). Excludes files.
`tags`	`list[Tag \| int \| str] \| None`	Restrict to documents carrying any of these tags, Tag objects, ids, or names (OR-matched). Names are resolved via Tag.list() and must exist. Excludes files.
`files`	`list[File \| int] \| None`	Restrict to these files (File objects or ids). Excludes workspaces and tags.
`content_type`	`list[ContentType \| str] \| None`	Restrict to these content-type paths, ContentType objects or path strings (OR-matched, exact-or-subtree, e.g. “legal” also matches “legal:contract”; wildcards `legal:contract`, `nda*`).
`attribute`	`list[str] \| None`	Restrict by attribute value, e.g. `["fiscal_year:2024\|2025", "status:active"]`. Entries are ANDed, `\|` ORs within one entry. Also `name` (has any value), `name:>value`, `name:prefix`, `name:text*`.
`max_results`	`int \| None`	Chunks to retrieve for context (1–50; server default 10).
`relevance_scoring`	`RelevanceScoring \| None`	RelevanceScoring, .scoring_and_filtering (default), .scoring_only, or .none.
`model`	`str \| None`	LLM for answer generation; platform default if omitted.
`schema`	`type[BaseModel] \| dict[str, Any] \| None`	Constrain the answer to structured output, a pydantic model class or a JSON-Schema dict (same inputs as `extract`, sent as the API’s `response_format`; must describe an object). The answer then comes back as JSON text in `.answer`, parse it with `YourModel.model_validate_json(resp.answer)`.
`stream`	`bool`	Return an iterator of Server-Sent Events instead of the whole answer, for showing it as it generates. Composes with `schema`: the tokens then spell out the JSON, so concatenate them and parse at the end.

Returns

Type	Description
`AskResponse \| Generator[AskEvent, None, None]`	`AskResponse` normally. When `stream=True`, an iterator of `SourcesEvent` (once, before generation), `TokenEvent` (repeatedly) and `DoneEvent` (last). Being a generator, nothing is sent until you start iterating, so request errors surface on the first step, not here. Iterate it fully or close it, so the connection is released.

Raises

Exception	When
`StreamError`	If the server reports a failure mid-stream; the answer is incomplete at that point.

`LightOn.close()`

close() -> None

`LightOn.extract()`

extract(
    schema: type[BaseModel] | dict[str, Any],
    *,
    path: str | Path | None = None,
    url: str | None = None,
    file: File | int | None = None,
    options: dict[str, Any] | None = None,
    mode: ExecMode = ExecMode.SYNC,
    wait: bool = False,
    timeout: float = 300.0,
) -> ExtractJobResponse | ExtractJob

POST /api/v3/extract, extract structured data from a document. Pass exactly one of: path: A local file to upload (multipart). url: A publicly accessible URL to fetch. file: An already-ingested file (File object or id), no re-upload, the server reads the document it already has. Arguments

Name	Type	Description
`schema`	`type[BaseModel] \| dict[str, Any]`	The guided-generation schema driving extraction, either a pydantic model class (converted to a vLLM `response_format` JSON Schema) or a dict already holding a valid such schema.
`options`	`dict[str, Any] \| None`	Free-form request options; currently `{"async": bool}`.
`mode`	`ExecMode`	ExecMode.SYNC (default) runs inline and returns the extracted data. ExecMode.ASYNC queues the job and returns an `ExtractJob` handle, call `.poll()` until `.succeeded`.
`wait`	`bool`	Async only. Block until the job is terminal, so the returned `ExtractJob` already carries its `result`.
`timeout`	`float`	Seconds to wait when wait=True before raising TimeoutError.

Returns

Type	Description
`ExtractJobResponse \| ExtractJob`	`ExtractJobResponse` (with data) when sync; an `ExtractJob` when async, pollable (wait=False) or already finished (wait=True).

Raises

Exception	When
`ValueError`	If not exactly one of path/url/file is given, or wait=True without ExecMode.ASYNC (sync already blocks).
`TimeoutError`	If wait=True and `timeout` elapses first.
`LightOnError`	If wait=True and the job ends in failure.

`LightOn.parse()`

parse(
    *,
    path: str | Path | None = None,
    url: str | None = None,
    mode: ExecMode = ExecMode.SYNC,
    wait: bool = False,
    timeout: float = 300.0,
) -> ParseResponse | ParseJob

POST /api/v3/parse, parse a document into per-page text. Pass exactly one of: path: A local file to upload (multipart). url: A publicly accessible URL to fetch. Arguments

Name	Type	Description
`mode`	`ExecMode`	ExecMode.SYNC (default) runs inline and returns the full `ParseResponse`. ExecMode.ASYNC queues the job and returns a `ParseJob` handle, call `.poll()` until `.succeeded`.
`wait`	`bool`	Async only. Block until the job is terminal, so the returned `ParseJob` already carries its `result`.
`timeout`	`float`	Seconds to wait when wait=True before raising TimeoutError.

Returns

Type	Description
`ParseResponse \| ParseJob`	`ParseResponse` when sync; a `ParseJob` when async, pollable (wait=False) or already finished (wait=True).

Raises

Exception	When
`ValueError`	If not exactly one of path/url is given, or wait=True without ExecMode.ASYNC (sync already blocks).
`TimeoutError`	If wait=True and `timeout` elapses first.
`LightOnError`	If wait=True and the job ends in failure.

`LightOn.search()`

search(
    query: str,
    *,
    workspaces: list[Workspace | int] | None = None,
    tags: list[Tag | int | str] | None = None,
    files: list[File | int] | None = None,
    content_type: list[ContentType | str] | None = None,
    attribute: list[str] | None = None,
    max_results: int | None = None,
    mode: SearchMode | None = None,
    relevance_scoring: RelevanceScoring | None = None,
    include_image: bool | None = None,
    include_bboxes: bool | None = None,
) -> SearchResponse

POST /api/v3/search, retrieve relevant passages (no generation). Arguments

Name	Type	Description
`query`	`str`	Natural-language search query (max 4000 chars).
`workspaces`	`list[Workspace \| int] \| None`	Restrict to these workspaces (Workspace objects or ids). Excludes files.
`tags`	`list[Tag \| int \| str] \| None`	Restrict to documents carrying any of these tags, Tag objects, ids, or names (OR-matched). Names are resolved via Tag.list() and must exist. Excludes files.
`files`	`list[File \| int] \| None`	Restrict to these files (File objects or ids). Excludes workspaces and tags.
`content_type`	`list[ContentType \| str] \| None`	Restrict to these content-type paths, ContentType objects or path strings (OR-matched, exact-or-subtree, e.g. “legal” also matches “legal:contract”; wildcards `legal:contract`, `nda*`).
`attribute`	`list[str] \| None`	Restrict by attribute value, e.g. `["fiscal_year:2024\|2025", "status:active"]`. Entries are ANDed, `\|` ORs within one entry. Also `name` (has any value), `name:>value`, `name:prefix`, `name:text*`.
`max_results`	`int \| None`	Chunks to return after reranking (1–100; server default 10).
`mode`	`SearchMode \| None`	SearchMode.text (hybrid keyword+vector) or .vision (page-image).
`relevance_scoring`	`RelevanceScoring \| None`	RelevanceScoring, .scoring_and_filtering (default), .scoring_only, or .none.
`include_image`	`bool \| None`	Attach a base64 page image to each result.
`include_bboxes`	`bool \| None`	Attach chunk bounding boxes (PDF text-mode only).

Returns

Type	Description
`SearchResponse`	The ranked search results.

LightOnConfiguration

Non-essential client knobs. api_key stays a direct LightOn() argument.

Field	Type	Default	Description
`base_url`	`str`	`'https://api.lighton.ai'`
`timeout`	`Timeout`	`Timeout(connect=5.0, read=120.0, write=120.0, pool=120.0)`
`retries`	`int`	`3`	Connection-level retries (httpx transport).
`transport`	`httpx.BaseTransport \| None`	`None`
`max_requests_per_minute`	`int \| None`	`1000`	Pace ALL requests to stay under this per-minute cap (min-interval gate in _request). Defaults to 1000, the API’s limit for most endpoints; override if your account differs. Set None to disable pacing entirely.
`rate_limit_retries`	`int`	`3`	On HTTP 429, retry this many times, waiting the Retry-After header when present (else exponential backoff). 0 disables.

Workspaces & files

Workspace

Field	Type	Default	Description
`id`	`int \| None`	`None`	Server-assigned id; None until created/retrieved.
`name`	`str`	required	Workspace display name.
`description`	`str`	`''`	Free-text workspace description.
`workspace_type`	`str \| None`	`None`	Workspace type (read-only).
`document_upload_method`	`str \| None`	`None`	How documents are uploaded to this workspace (read-only).
`files_count`	`int \| None`	`None`	Number of files in the workspace (read-only).
`used_storage`	`float \| None`	`None`	Bytes of storage used (read-only).
`created_at`	`datetime.datetime \| None`	`None`	Creation timestamp (read-only).
`updated_at`	`datetime.datetime \| None`	`None`	Last-update timestamp (read-only).
`user_role`	`enums.Role \| None`	`None`	Your role on this workspace, owner/editor/viewer (read-only).
`taxonomy`	`types.workspace.WorkspaceTaxonomy \| None`	`None`	Classification coverage and per-root document counts (read-only). Only `list()` returns it; the detail endpoint omits the key, so `get()`/`refresh()` leave an already-loaded value in place.
`sync`	`types.workspace.WorkspaceSync \| None`	`None`	External datasource this workspace imports from (read-only); None when documents are uploaded directly.

`Workspace.create()`

create(client: LightOn) -> Workspace

Create this workspace and bind the client for later lifecycle calls. Arguments

Name	Type	Description
`client`	`LightOn`	The client to create the workspace with and bind to `self`.

Returns

Type	Description
`Workspace`	`self`, updated with the server-assigned id and read-only fields.

`Workspace.delete()`

delete() -> None

Delete this resource and clear its local id.

`Workspace.get()`

Classmethod.

get(client: LightOn, id: int | str) -> Self

Fetch a single resource by id. Arguments

Name	Type	Description
`client`	`LightOn`	The client used to make the request and bind to the result.
`id`	`int \| str`	The resource id to retrieve.

Returns

Type	Description
`Self`	The resource, bound to `client`.

`Workspace.ingest()`

ingest(
    file: File,
    *,
    wait: bool = False,
    timeout: float = 300.0,
    tags: list[int] | None = None,
) -> File

Upload a File into this workspace, uploading is the ingestion. Non-blocking by default: the returned File is ‘pending’, poll it via refresh()/wait(). Pass wait=True to block until ingestion is terminal. Arguments

Name	Type	Description
`file`	`File`	The File to upload; its workspace_id is set to this workspace.
`wait`	`bool`	If True, block until ingestion reaches a terminal status.
`timeout`	`float`	Seconds to wait when wait=True before raising TimeoutError.
`tags`	`list[int] \| None`	Optional tag ids to assign to the document on upload.

Returns

Type	Description
`File`	The created File, bound to this workspace’s client.

Raises

Exception	When
`ValueError`	If this workspace has not been created/retrieved yet.

`Workspace.ingest_many()`

ingest_many(
    files: list[File | str | Path],
    *,
    mode: ExecMode = ExecMode.SYNC,
    ignore_errors: bool = False,
    wait: bool = False,
    timeout: float = 300.0,
    max_workers: int = 8,
    tags: list[int] | None = None,
) -> BatchIngest | BatchIngestJob

Upload many files into this workspace, concurrently. Every local path is validated to exist before any upload starts (fail fast). Staying under the API rate limit and the 429 cooldown are handled by the client (see LightOnConfiguration.max_requests_per_minute / rate_limit_retries), so they apply across uploads and status polls alike. Arguments

Name	Type	Description
`files`	`list[File \| str \| Path]`	Items to ingest, File objects, path strings, or Paths (mixed). A string with glob characters (`?[`) is expanded (recursive `*` supported) to its matching files; duplicates are ignored.
`mode`	`ExecMode`	ExecMode.SYNC blocks and returns a BatchIngest; ExecMode.ASYNC returns a BatchIngestJob you poll for progress/failures.
`ignore_errors`	`bool`	If False (default), the first failure raises (sync) or surfaces on job.wait() (async). If True, failures are collected and the batch continues.
`wait`	`bool`	If True, wait for each upload’s ingestion to reach a terminal status (embedded); if False, return once uploads are accepted.
`timeout`	`float`	Per-file seconds to wait for ingestion when wait=True.
`max_workers`	`int`	Concurrent upload/poll threads.
`tags`	`list[int] \| None`	Optional tag ids assigned to every uploaded document.

Returns

Type	Description
`BatchIngest \| BatchIngestJob`	A BatchIngest (SYNC) or a BatchIngestJob (ASYNC).

Raises

Exception	When
`ValueError`	If this workspace has no id, or an item is a File with no path.
`FileNotFoundError`	If any path is missing and ignore_errors is False.

`Workspace.list()`

Classmethod.

list(client: LightOn, **params: object) -> list[Self]

List every resource, following pagination to the end. Arguments

Name	Type	Description
`client`	`LightOn`	The client used to make the request and bind to each result.
`**params`	`object`	Optional query filters (e.g. workspace_id) sent on the first page.

Returns

Type	Description
`list[Self]`	All matching resources, each bound to `client`.

`Workspace.refresh()`

refresh() -> Self

Re-fetch this resource from the API (GET). Returns

Type	Description
`Self`	`self`, updated with the latest field values.

`Workspace.save()`

save() -> Workspace

Persist local edits to name/description (PATCH). Returns

Type	Description
`Workspace`	`self`, refreshed with the server’s response.

WorkspaceTaxonomy

How much of a workspace is classified, and under which roots. The cheapest way to see classification coverage without listing files. Only the list endpoint returns it (Workspace.list()); the detail endpoint omits the key entirely, so get()/refresh() leave whatever was already there rather than clearing it.

Field	Type	Default	Description
`classified_files_rate`	`float`	required	Fraction of the workspace’s files that carry a content type, 0 to 1.
`root_content_types`	`list`	`[]`	Per-root document counts, one entry per root content type.

RootContentType

How many of a workspace’s documents sit under one root content type.

Field	Type	Default	Description
`path`	`str`	required	Root content-type path, e.g. legal.
`label`	`str`	required	Human-readable label for that root.
`count`	`int`	required	Documents classified under it, including children.

WorkspaceSync

The external datasource a workspace imports from, when one is connected. None on a workspace whose documents were uploaded directly.

Field	Type	Default	Description
`name`	`str \| None`	`None`	Sync configuration name.
`datasource_type`	`str \| None`	`None`	Kind of connected datasource (read-only).
`source_name`	`str \| None`	`None`	Name of the remote source.
`last_status`	`str \| None`	`None`	Outcome of the last import run.
`updated_at`	`datetime.datetime \| None`	`None`	When the sync last ran; None if it never has.
`next_import_date`	`datetime.datetime \| None`	`None`	When the next import is due; None if none is scheduled.
`failed_files_count`	`int \| None`	`None`	Files the last run could not import.
`editable`	`bool \| None`	`None`	Whether the caller may change this configuration.
`instance_url`	`str \| None`	`None`	Remote instance URL, if any.
`tenant_id`	`str \| None`	`None`	Remote tenant identifier, if any.
`site_name`	`str \| None`	`None`	Remote site name, if any.
`client_id`	`str \| None`	`None`	Remote client identifier, if any.
`filter_criteria`	`Any`	`None`	Datasource-specific import filter, passed through as-is.

File

Field	Type	Default	Description
`id`	`int \| None`	`None`	Server-assigned id; None until created/retrieved.
`path`	`pathlib.Path \| None`	`None`	Local source file to upload; set before create(), never in a response.
`workspace_id`	`int \| None`	`None`	Target workspace for upload; required to create (Workspace.ingest fills it).
`filename`	`str \| None`	`None`	Document filename; defaults to path.name on upload.
`title`	`str \| None`	`None`	Document title; defaults to the filename server-side.
`external_metadata`	`types.file.ExternalMetadata \| None`	`None`	Origin of the document in a third-party system. Settable on create() and save(); the response returns the same shape, so it round-trips.
`status`	`enums.FileStatus \| None`	`None`	Ingestion pipeline status (read-only).
`status_detail`	`str \| None`	`None`	Free-text error detail, present only on failure (read-only).
`pending_reprocess`	`enums.ReprocessLevel \| None`	`None`	Reprocessing queued but not started (read-only). While non-null, `status` and the file-derived fields still describe the previous run; it clears the moment processing starts. `update` means a file replacement.
`extension`	`str \| None`	`None`	File extension of the document (read-only).
`total_pages`	`int \| None`	`None`	Total page count of the document (read-only).
`size`	`int \| None`	`None`	File size in bytes (read-only).
`thumbnail`	`types.file.Thumbnail \| None`	`None`	Thumbnail status and URL (read-only). Check `status` is READY before calling download_thumbnail(), which 404s otherwise.
`created_at`	`datetime.datetime \| None`	`None`	Creation timestamp (read-only).
`updated_at`	`datetime.datetime \| None`	`None`	Last-update timestamp (read-only).

`File.classify()`

classify(content_type: ContentType | str) -> File

Assign a content type to this file (ContentType object or path string). Arguments

Name	Type	Description
`content_type`	`ContentType \| str`	The content type to assign, e.g. “legal:contract:nda”.

Returns

Type	Description
`File`	`self`.

Raises

Exception	When
`ValueError`	If this file has not been created/retrieved yet.

`File.clear_attribute()`

clear_attribute(content_type: ContentType | str, name: str) -> File

Clear an attribute value under an assigned content type. Arguments

Name	Type	Description
`content_type`	`ContentType \| str`	The assigned content type (object or path string).
`name`	`str`	Attribute identifier to clear.

Returns

Type	Description
`File`	`self`.

`File.create()`

create(
    client: LightOn,
    *,
    tags: list[int] | None = None,
    external_metadata: ExternalMetadata | None = None,
) -> File

Upload the file (multipart), this starts ingestion. Arguments

Name	Type	Description
`client`	`LightOn`	The client to upload with and bind to `self`.
`tags`	`list[int] \| None`	Optional tag ids to assign to the document on upload.
`external_metadata`	`ExternalMetadata \| None`	Where this document came from in a third-party system. Overrides the `external_metadata` field if both are set.

Returns

Type	Description
`File`	`self`, updated with the server-assigned id and initial status.

Raises

Exception	When
`ValueError`	If `path` or `workspace_id` is not set.

`File.delete()`

delete() -> None

Delete this resource and clear its local id.

`File.delete_many()`

Classmethod.

delete_many(client: LightOn, files: Sequence[File | int]) -> None

Delete many files in one request (POST /files/bulk-delete). All-or-nothing: if any id is unknown (or not yours), the API rejects the whole call with 404 and deletes nothing, which this surfaces as a NotFoundError. There is no partial-success result to report, so a failure raises rather than returning a per-file report: nothing was deleted, and retrying with the ids you can account for is the fix. Arguments

Name	Type	Description
`client`	`LightOn`	The client to delete with.
`files`	`Sequence[File \| int]`	The files to delete, File objects or bare ids (mix freely). Any sequence, so `File.list(...)` passes straight in. Empty is a no-op (the endpoint rejects an empty list).

Returns

Type	Description
`None`	None. Any File objects passed in have their `id` cleared, as delete() does.

Raises

Exception	When
`NotFoundError`	If any id is unknown; no file is deleted in that case.

`File.download()`

download(purpose: DownloadPurpose | str = DownloadPurpose.original) -> bytes

Download this document’s stored bytes (GET /files/<id>/download). Arguments

Name	Type	Description
`purpose`	`DownloadPurpose \| str`	Which stored version to fetch, `original` (default), the `rendered_pdf`, or the `transcript`. The server falls back to `original` when the requested purpose has no associated file, so this never 404s just because a rendition is missing.

Returns

Type	Description
`bytes`	The file content, as bytes. Write it yourself: `Path("out.pdf").write_bytes(doc.download())`.

Raises

Exception	When
`ValueError`	If this file has not been created/retrieved yet.

`File.download_thumbnail()`

download_thumbnail() -> bytes

Download this document’s 256x256 WebP thumbnail. Generated asynchronously and independently of ingestion, so an embedded file may still have none. Check the thumbnail field first, a fetch before it is READY raises NotFoundError: doc.refresh() if doc.thumbnail and doc.thumbnail.status is ThumbnailStatus.READY: image = doc.download_thumbnail() Returns

Type	Description
`bytes`	The WebP image, as bytes.

Raises

Exception	When
`ValueError`	If this file has not been created/retrieved yet.
`NotFoundError`	If no thumbnail exists (status is not READY).

facets() -> list[Facet]

List this file’s assigned content types and their attribute values. Returns

Type	Description
`list[Facet]`	One Facet per assigned content type (with its attribute values).

Raises

Exception	When
`ValueError`	If this file has not been created/retrieved yet.

`File.get()`

Classmethod.

get(client: LightOn, id: int | str) -> Self

Fetch a single resource by id. Arguments

Name	Type	Description
`client`	`LightOn`	The client used to make the request and bind to the result.
`id`	`int \| str`	The resource id to retrieve.

Returns

Type	Description
`Self`	The resource, bound to `client`.

`File.get_by_name()`

Classmethod.

get_by_name(client: LightOn, name: str, *, workspace: Workspace | int) -> list[File]

Fetch every file with this user-facing name in a workspace. Matches title, not filename: the server uniquifies filenames on upload (“report.pdf” is stored as something like “report_20260728_c9be.pdf”), so the name you uploaded never matches the stored one. A title defaults to the uploaded filename without its extension, so “report.pdf” and “report” both find that upload. Titles are not unique the way stored filenames are, uploading the same document twice gives both copies the same title, so this returns every match rather than picking one. Check the length if you need exactly one. The API’s title filter is a case-insensitive partial match, so the candidates it returns are narrowed to an exact title match here. Arguments

Name	Type	Description
`client`	`LightOn`	The client to query with and bind to the results.
`name`	`str`	The file’s title, with or without an extension (e.g. “report.pdf”).
`workspace`	`Workspace \| int`	The workspace to search in (Workspace object or id).

Returns

Type	Description
`list[File]`	Every File with that title, each bound to `client`; empty if none match.

Raises

Exception	When
`ValueError`	If the workspace has not been created/retrieved (has no id).

`File.list()`

Classmethod.

list(client: LightOn, **params: object) -> list[Self]

List every resource, following pagination to the end. Arguments

Name	Type	Description
`client`	`LightOn`	The client used to make the request and bind to each result.
`**params`	`object`	Optional query filters (e.g. workspace_id) sent on the first page.

Returns

Type	Description
`list[Self]`	All matching resources, each bound to `client`.

`File.pages()`

pages() -> list[Page]

Fetch the parsed text of this document, one entry per page. The platform stores what it parsed at ingestion, so this reads it back instead of re-uploading and re-parsing a document it already has. The result is the same {index, markdown} shape parse returns (literally the same Page model), so code can move between parsing a local file and reading an ingested one without reshaping anything. Costs a request with include_content=true and is not part of refresh(), because the text can be large and most callers don’t want it. Returns

Type	Description
`list[Page]`	One Page per page, `index` and `markdown`. Empty if the document has no stored text. A document ingested before per-page text was stored comes back as a single page (index 1).

Raises

Exception	When
`ValueError`	If this file has not been created/retrieved yet.

`File.refresh()`

refresh() -> Self

Re-fetch this resource from the API (GET). Returns

Type	Description
`Self`	`self`, updated with the latest field values.

`File.replace()`

replace(path: str | Path, *, wait: bool = False, timeout: float = 300.0) -> File

Replace this document’s content in place (PATCH, multipart file part). The document keeps its id, title, tags, and content-type classifications, and is re-ingested from the new content, so every reference to the id survives what used to need a delete plus a re-upload. The new file may be of a different type. filename follows the new file, but title (the user-facing name, what get_by_name matches) is preserved, so a replaced document is still found under the name it was uploaded with. Addressed by id, never by name: titles and filenames aren’t unique, so resolve to the one document you mean first (File.get(client, id), or check the length of File.get_by_name(...)) before replacing. Arguments

Name	Type	Description
`path`	`str \| Path`	Local file whose content replaces the current one.
`wait`	`bool`	If True, block until the re-ingestion reaches a terminal status.
`timeout`	`float`	Seconds to wait when wait=True before raising TimeoutError.

Returns

Type	Description
`File`	`self`. Note the fields absorbed from the response still describe the previous content (see below); refresh() once re-ingestion has run.

Raises

Exception	When
`ValueError`	If this file has not been created/retrieved yet.
`TimeoutError`	If wait=True and `timeout` elapses.
`LightOnError`	If wait=True and the re-ingestion fails.

`File.save()`

save(
    *,
    tags: list[Tag | int | str] | None = None,
    external_metadata: ExternalMetadata | None = None,
) -> File

Persist local edits to title, plus whatever you pass explicitly. filename is immutable server-side. title is a plain model field: set it and save. tags and external_metadata are arguments, not fields, because neither is a plain set server-side, and a keyword at the call site says which one you’re doing:

tags replaces every tag on the document, auto-assigned included. Pass [] to remove them all; tag()/untag() stay the additive path. (It also can’t be a field: the response returns tag objects, not the list[int] the request takes, which would clash on absorb.)
external_metadata merges into what’s stored, including inside additional_metadata, so a partial update leaves the other keys alone. The field of the same name stays readable and round-trips; it just isn’t what gets sent, so assigning it can’t read as a whole-value set.

Omitting either leaves that part of the document untouched, so a plain save() only ever writes the title. Clearing metadata is partial, and the shape is the API’s, verified live: doc_type="" blanks it, and a null inside additional_metadata ({"version": None}) nulls that key. external_id can be neither blanked (422 blank) nor nulled (422 null), and the whole record can’t be dropped: the schema offers a null external_metadata, but the endpoint takes only form/multipart, where a bare null is rejected as “must be a JSON object”, and application/json is 415. So the null branch is unreachable. ponytail: exclude_none=True is load-bearing, not tidiness. It keeps an unset field out of the payload (a None doc_type would 422), while an empty string still goes through, which is what makes the blank-clear work. Arguments

Name	Type	Description
`tags`	`list[Tag \| int \| str] \| None`	Replacement tags, Tag objects, ids, or names (mix freely). None (the default) leaves the document’s tags untouched; `[]` clears them.
`external_metadata`	`ExternalMetadata \| None`	Origin fields to merge in. None (the default) leaves the stored metadata untouched.

Returns

Type	Description
`File`	`self`, refreshed with the server’s response (so `external_metadata` shows the merged result, not the partial value you sent).

Raises

Exception	When
`ValueError`	If this file isn’t persisted, or a name/Tag can’t resolve.

`File.set_attribute()`

set_attribute(content_type: ContentType | str, name: str, value: object) -> File

Set an attribute value under an assigned content type. Arguments

Name	Type	Description
`content_type`	`ContentType \| str`	The assigned content type (object or path string).
`name`	`str`	Attribute identifier (snake_case).
`value`	`object`	The value; shape depends on the attribute type (string, number, date “YYYY-MM-DD”, bool, or list[str] for multi-select).

Returns

Type	Description
`File`	`self`.

`File.tag()`

tag(tags: list[Tag | int | str]) -> File

Assign tags to this file (POST /files/<id>/tags). Arguments

Name	Type	Description
`tags`	`list[Tag \| int \| str]`	Tags to add, Tag objects, ids, or names (mix freely). Names are resolved via Tag.list() and must exist. Empty is a no-op.

Returns

Type	Description
`File`	`self`, refreshed from the response.

Raises

Exception	When
`ValueError`	If this file isn’t persisted, or a name/Tag can’t resolve.

`File.unclassify()`

unclassify(content_type: ContentType | str) -> File

Remove a content-type assignment from this file. Arguments

Name	Type	Description
`content_type`	`ContentType \| str`	The content type to unassign (object or path string).

Returns

Type	Description
`File`	`self`.

`File.untag()`

untag(tags: list[Tag | int | str]) -> File

Remove tags from this file (DELETE /files/<id>/tags/<tag_id>, one each). Arguments

Name	Type	Description
`tags`	`list[Tag \| int \| str]`	Tags to remove, Tag objects, ids, or names (mix freely). Names are resolved via Tag.list() and must exist. Empty is a no-op.

Returns

Type	Description
`File`	`self`.

Raises

Exception	When
`ValueError`	If this file isn’t persisted, or a name/Tag can’t resolve.

`File.wait()`

wait(timeout: float = 300.0, poll: float = 2.0) -> File

Block (polling) until ingestion reaches a terminal state. ponytail: dumb poll loop, the API offers no webhook. Run in a thread (or use wait_all) for concurrency; the SDK stays sync. Arguments

Name	Type	Description
`timeout`	`float`	Max seconds to wait before raising TimeoutError.
`poll`	`float`	Seconds to sleep between status checks. A pending reprocess counts as not terminal: while `pending_reprocess` is set the queued work has not started and `status` still reports the previous run, so trusting it would call a replace() done before it began.

Returns

Type	Description
`File`	`self`, once `status` is a terminal-success state (embedded/parsed) and no reprocess is queued.

Raises

Exception	When
`TimeoutError`	If `timeout` elapses before a terminal status.
`LightOnError`	If ingestion ends in a terminal-failure state.

ExternalMetadata

Where a document came from in a third-party system. How a synced document keeps its origin id: set it on upload (or with save()) and it survives on the File, so a later sync can match the platform document back to the record it was ingested from. Updates merge server-side, including into additional_metadata: patching one key leaves the others in place, there is no way to drop a key this way.

Field	Type	Default	Description
`external_id`	`str \| None`	`None`	Document id in the source system; required the first time.
`doc_type`	`str \| None`	`None`	Document type in the source system, e.g. ‘incident’.
`additional_metadata`	`Any`	`None`	Arbitrary JSON (url, version, timestamps…), passed through as-is.

Thumbnail

Whether a file’s 256x256 WebP thumbnail exists yet, and where it lives. Generation is asynchronous and independent of ingestion, so check status before fetching: File.download_thumbnail() 404s while it isn’t READY.

Field	Type	Default	Description
`status`	`enums.ThumbnailStatus \| None`	`None`	MISSING, PROCESSING, or READY (read-only).
`url`	`str \| None`	`None`	Relative URL to the image; None unless status is READY.

wait_all

wait_all(files: list[File], timeout: float = 300.0) -> list[File]

Wait for many ingestions concurrently (threads, not async, sync SDK). Arguments

Name	Type	Description
`files`	`list[File]`	The files to wait on; each is polled via File.wait.
`timeout`	`float`	Max seconds to wait per file before that wait raises TimeoutError.

Returns

Type	Description
`list[File]`	The same files, once each has reached a terminal-success status.

Raises

Exception	When
`TimeoutError`	If any file does not finish within `timeout`.
`LightOnError`	If any file’s ingestion ends in a terminal-failure state.

Tags & content types

Tag

Field	Type	Default	Description
`id`	`int \| None`	`None`	Server-assigned id; None until created/retrieved.
`name`	`str`	required	Tag name.
`description`	`str`	`''`	Free-text description (max 500 chars).
`auto_assign`	`bool`	`True`	If True the system may auto-assign this tag; else user-only.
`document_count`	`int \| None`	`None`	Number of documents carrying this tag (read-only).
`created_at`	`datetime.datetime \| None`	`None`	Creation timestamp (read-only).
`updated_at`	`datetime.datetime \| None`	`None`	Last-update timestamp (read-only).

`Tag.create()`

create(client: LightOn) -> Tag

Create this tag and bind the client for later lifecycle calls. Arguments

Name	Type	Description
`client`	`LightOn`	The client to create the tag with and bind to `self`.

Returns

Type	Description
`Tag`	`self`, updated with the server-assigned id and read-only fields.

`Tag.delete()`

delete() -> None

Delete this resource and clear its local id.

`Tag.get()`

Classmethod.

get(client: LightOn, id: int | str) -> NoReturn

Raises

Exception	When
`NotImplementedError`	the tags API has no single-tag GET; use Tag.list(client)

Classmethod.

list(client: LightOn, **params: object) -> list[Self]

List every resource, following pagination to the end. Arguments

Name	Type	Description
`client`	`LightOn`	The client used to make the request and bind to each result.
`**params`	`object`	Optional query filters (e.g. workspace_id) sent on the first page.

Returns

Type	Description
`list[Self]`	All matching resources, each bound to `client`.

`Tag.refresh()`

refresh() -> NoReturn

Raises

Exception	When
`NotImplementedError`	the tags API has no single-tag GET; use Tag.list(client)

ContentType

A node in the content-type taxonomy.

Field	Type	Default	Description
`path`	`str`	required	Full taxonomy path, e.g. legal:contract:nda.
`code`	`str`	required	This node’s own code segment.
`label`	`str`	required	Human-readable label.
`description`	`str`	`''`	Free-text description.
`source`	`str \| None`	`None`	Where the type is defined (read-only).
`attributes`	`list`	`[]`	Attribute definitions (present when include_attributes=True).
`children`	`list`	`[]`	Child content types.

`ContentType.adopt()`

Classmethod.

adopt(client: LightOn, paths: list[str]) -> list[ContentType]

Import starter trees from the template catalog into your taxonomy. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`paths`	`list[str]`	Template root paths to import, e.g. `["legal", "finance"]` (see `templates()`).

Returns

Type	Description
`list[ContentType]`	The imported top-level nodes.

`ContentType.batch()`

Classmethod.

batch(client: LightOn, actions: list[dict[str, Any]]) -> list[dict[str, Any]]

Apply several taxonomy actions in one request (POST /content-types/batch). Each entry is the body a single-action method would send, so a tree and its attributes land together instead of one round trip each: ContentType.batch(client, [ {“action”: “adopt”, “content_types”: [“legal”]}, {“action”: “define_attribute”, “content_type_path”: “legal”, “name”: “jurisdiction”, “attribute_type”: “select”, “choices”: [“FR”, “US”]}, ]) Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`actions`	`list[dict[str, Any]]`	The action bodies, in order.

Returns

Type	Description
`list[dict[str, Any]]`	One `{"status": ..., "data": ...}` entry per action, in the same order. `data` is a node for the content-type actions and an attribute for the attribute ones, so it’s left as raw dicts rather than guessed into one model.

`ContentType.define()`

Classmethod.

define(
    client: LightOn,
    code: str,
    label: str,
    *,
    parent: ContentType | str | None = None,
    description: str | None = None,
    inherit_attributes: bool | None = None,
) -> ContentType

Create or update one node (POST /content-types, define_content_type). Idempotent: defining an existing code again updates it, so this is also how you rename a node. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`code`	`str`	This node’s own segment, lowercase alphanumeric with hyphens (e.g. “employment-contract”); the server rejects anything else.
`label`	`str`	Human-readable label.
`parent`	`ContentType \| str \| None`	Parent node or path; omit for a root node.
`description`	`str \| None`	Optional free-text description.
`inherit_attributes`	`bool \| None`	Whether children inherit this node’s attributes (server default True).

Returns

Type	Description
`ContentType`	The created (or updated) node.

`ContentType.define_attribute()`

Classmethod.

define_attribute(
    client: LightOn,
    content_type: ContentType | str,
    name: str,
    attribute_type: AttributeType | str,
    *,
    choices: list[str] | None = None,
    label: str | None = None,
    description: str | None = None,
    required: bool | None = None,
) -> Attribute

Create or update an attribute column on a node. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`content_type`	`ContentType \| str`	The node to define it on (object or path string).
`name`	`str`	Attribute identifier in snake_case.
`attribute_type`	`AttributeType \| str`	AttributeType, or the equivalent string.
`choices`	`list[str] \| None`	Allowed values; required for select and multi-select, and rejected by the server for every other type.
`label`	`str \| None`	Human-readable label (defaults to a title-cased `name`).
`description`	`str \| None`	Optional description.
`required`	`bool \| None`	Whether the schema requires a value (server default False).

Returns

Type	Description
`Attribute`	The created (or updated) attribute definition.

Raises

Exception	When
`ValueError`	If a select/multi-select is missing `choices`, which the API rejects with a 422 anyway, caught here to save the round trip.

`ContentType.list()`

Classmethod.

list(
    client: LightOn,
    *,
    path: str | None = None,
    depth: int | None = None,
    include_attributes: bool = False,
    query: str | None = None,
) -> list[ContentType]

List the content-type taxonomy (top-level nodes, each with children). Arguments

Name	Type	Description
`client`	`LightOn`	The client to query with.
`path`	`str \| None`	Restrict to the subtree rooted at this path.
`depth`	`int \| None`	How many levels of children to return.
`include_attributes`	`bool`	Populate each node’s `attributes` definitions.
`query`	`str \| None`	Free-text filter over labels/paths.

Returns

Type	Description
`list[ContentType]`	The top-level content-type nodes.

`ContentType.templates()`

Classmethod.

templates(client: LightOn) -> list[Template]

List the starter taxonomies you can adopt() (GET /content-types/templates). Arguments

Name	Type	Description
`client`	`LightOn`	The client to query with.

Returns

Type	Description
`list[Template]`	The template root nodes, each with its `children` and an `attributes` map covering the whole subtree.

`ContentType.undefine()`

Classmethod.

undefine(client: LightOn, content_type: ContentType | str) -> None

Delete a node and cascade its whole subtree. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`content_type`	`ContentType \| str`	The node to delete (object or path string).

Returns

Type	Description
`None`	None.

`ContentType.undefine_attribute()`

Classmethod.

undefine_attribute(client: LightOn, content_type: ContentType | str, name: str) -> None

Remove an attribute column from a node. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`content_type`	`ContentType \| str`	The node it’s defined on (object or path string).
`name`	`str`	Attribute identifier to remove.

Returns

Type	Description
`None`	None.

Template

A starter taxonomy from the catalog, what adopt() imports. Same tree as a ContentType except for attributes: on a template it’s a map from node path to that node’s attribute definitions (the whole tree’s attributes hang off the root), not this node’s own list.

Field	Type	Default	Description
`path`	`str`	required	Full taxonomy path, e.g. legal:contract:nda.
`code`	`str`	required	This node’s own code segment.
`label`	`str`	required	Human-readable label.
`description`	`str`	`''`	Free-text description.
`source`	`str \| None`	`None`	Where the type is defined (read-only).
`attributes`	`dict`	`{}`	Attribute definitions per node path, for the whole subtree.
`children`	`list`	`[]`	Child content types.

`Template.adopt()`

Classmethod.

adopt(client: LightOn, paths: list[str]) -> list[ContentType]

Import starter trees from the template catalog into your taxonomy. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`paths`	`list[str]`	Template root paths to import, e.g. `["legal", "finance"]` (see `templates()`).

Returns

Type	Description
`list[ContentType]`	The imported top-level nodes.

`Template.batch()`

Classmethod.

batch(client: LightOn, actions: list[dict[str, Any]]) -> list[dict[str, Any]]

Name	Type	Description
`client`	`LightOn`	The client to write with.
`actions`	`list[dict[str, Any]]`	The action bodies, in order.

Returns

Type	Description
`list[dict[str, Any]]`	One `{"status": ..., "data": ...}` entry per action, in the same order. `data` is a node for the content-type actions and an attribute for the attribute ones, so it’s left as raw dicts rather than guessed into one model.

`Template.define()`

Classmethod.

define(
    client: LightOn,
    code: str,
    label: str,
    *,
    parent: ContentType | str | None = None,
    description: str | None = None,
    inherit_attributes: bool | None = None,
) -> ContentType

Create or update one node (POST /content-types, define_content_type). Idempotent: defining an existing code again updates it, so this is also how you rename a node. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`code`	`str`	This node’s own segment, lowercase alphanumeric with hyphens (e.g. “employment-contract”); the server rejects anything else.
`label`	`str`	Human-readable label.
`parent`	`ContentType \| str \| None`	Parent node or path; omit for a root node.
`description`	`str \| None`	Optional free-text description.
`inherit_attributes`	`bool \| None`	Whether children inherit this node’s attributes (server default True).

Returns

Type	Description
`ContentType`	The created (or updated) node.

`Template.define_attribute()`

Classmethod.

define_attribute(
    client: LightOn,
    content_type: ContentType | str,
    name: str,
    attribute_type: AttributeType | str,
    *,
    choices: list[str] | None = None,
    label: str | None = None,
    description: str | None = None,
    required: bool | None = None,
) -> Attribute

Create or update an attribute column on a node. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`content_type`	`ContentType \| str`	The node to define it on (object or path string).
`name`	`str`	Attribute identifier in snake_case.
`attribute_type`	`AttributeType \| str`	AttributeType, or the equivalent string.
`choices`	`list[str] \| None`	Allowed values; required for select and multi-select, and rejected by the server for every other type.
`label`	`str \| None`	Human-readable label (defaults to a title-cased `name`).
`description`	`str \| None`	Optional description.
`required`	`bool \| None`	Whether the schema requires a value (server default False).

Returns

Type	Description
`Attribute`	The created (or updated) attribute definition.

Raises

Exception	When
`ValueError`	If a select/multi-select is missing `choices`, which the API rejects with a 422 anyway, caught here to save the round trip.

`Template.list()`

Classmethod.

list(
    client: LightOn,
    *,
    path: str | None = None,
    depth: int | None = None,
    include_attributes: bool = False,
    query: str | None = None,
) -> list[ContentType]

List the content-type taxonomy (top-level nodes, each with children). Arguments

Name	Type	Description
`client`	`LightOn`	The client to query with.
`path`	`str \| None`	Restrict to the subtree rooted at this path.
`depth`	`int \| None`	How many levels of children to return.
`include_attributes`	`bool`	Populate each node’s `attributes` definitions.
`query`	`str \| None`	Free-text filter over labels/paths.

Returns

Type	Description
`list[ContentType]`	The top-level content-type nodes.

`Template.templates()`

Classmethod.

templates(client: LightOn) -> list[Template]

List the starter taxonomies you can adopt() (GET /content-types/templates). Arguments

Name	Type	Description
`client`	`LightOn`	The client to query with.

Returns

Type	Description
`list[Template]`	The template root nodes, each with its `children` and an `attributes` map covering the whole subtree.

`Template.undefine()`

Classmethod.

undefine(client: LightOn, content_type: ContentType | str) -> None

Delete a node and cascade its whole subtree. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`content_type`	`ContentType \| str`	The node to delete (object or path string).

Returns

Type	Description
`None`	None.

`Template.undefine_attribute()`

Classmethod.

undefine_attribute(client: LightOn, content_type: ContentType | str, name: str) -> None

Remove an attribute column from a node. Arguments

Name	Type	Description
`client`	`LightOn`	The client to write with.
`content_type`	`ContentType \| str`	The node it’s defined on (object or path string).
`name`	`str`	Attribute identifier to remove.

Returns

Type	Description
`None`	None.

Attribute

One attribute of a content type, a definition, or a value set on a file. Carries both the schema (type/required/choices) and, when read from a file’s facets, the current value. value is None for bare definitions / when unset.

Field	Type	Default	Description
`name`	`str`	required	Attribute identifier in snake_case.
`label`	`str`	`''`	Human-readable label.
`type`	`str`	`''`	text, number, date, boolean, select, or multi-select.
`value`	`Any`	`None`	Current value on the file; None for a definition/unset.
`required`	`bool`	`False`	Whether the schema requires it.
`choices`	`list`	`[]`	Allowed values for select/multi-select.
`description`	`str`	`''`	Optional attribute description.

A content type assigned to a file, with the file’s attribute values on it.

Field	Type	Default	Description
`path`	`str`	required	Assigned content-type path on the file.
`label`	`str`	required	Human-readable content-type label.
`attributes`	`list`	`[]`	Attribute values set on the file.

API keys

ApiKey

Field	Type	Default	Description
`id`	`str \| None`	`None`	Server-assigned id; None until created/retrieved.
`name`	`str`	required	API key display name.
`expires_at`	`datetime.datetime \| None`	`None`	Expiry timestamp; None for no expiry.
`scopes`	`list`	`[]`	Per-workspace access scopes; empty for an unscoped key.
`prefix`	`str \| None`	`None`	Non-secret key prefix for identification (read-only).
`created_at`	`datetime.datetime \| None`	`None`	Creation timestamp (read-only).
`key`	`pydantic.types.SecretStr \| None`	`None`	Plaintext secret, returned ONLY by create(), once. Use .get_secret_value().

`ApiKey.create()`

create(client: LightOn) -> ApiKey

Create this API key and bind the client for later lifecycle calls. Arguments

Name	Type	Description
`client`	`LightOn`	The client to create the key with and bind to `self`.

Returns

Type	Description
`ApiKey`	`self`, updated with the id and the one-time plaintext `key`.

`ApiKey.delete()`

delete() -> None

Delete this resource and clear its local id.

`ApiKey.get()`

Classmethod.

get(client: LightOn, id: int | str) -> Self

Fetch a single resource by id. Arguments

Name	Type	Description
`client`	`LightOn`	The client used to make the request and bind to the result.
`id`	`int \| str`	The resource id to retrieve.

Returns

Type	Description
`Self`	The resource, bound to `client`.

`ApiKey.list()`

Classmethod.

list(client: LightOn, **params: object) -> list[Self]

List every resource, following pagination to the end. Arguments

Name	Type	Description
`client`	`LightOn`	The client used to make the request and bind to each result.
`**params`	`object`	Optional query filters (e.g. workspace_id) sent on the first page.

Returns

Type	Description
`list[Self]`	All matching resources, each bound to `client`.

`ApiKey.refresh()`

refresh() -> Self

Re-fetch this resource from the API (GET). Returns

Type	Description
`Self`	`self`, updated with the latest field values.

`ApiKey.save()`

save() -> ApiKey

Persist local edits to name/scopes (PATCH). Returns

Type	Description
`ApiKey`	`self`, refreshed with the server’s response (never re-includes `key`).

ApiKeyScope

Field	Type	Default	Description
`workspace_id`	`int`	required	Workspace this scope grants access to.
`role`	`Role`	required	Access role granted on the workspace.

Jobs & batches

ParseJob

Field	Type	Default	Description
`id`	`str`	required	Async job id; poll its endpoint for status.
`status`	`str`	required	Current status; compare against JobStatus (see .succeeded).
`created_at`	`pydantic.types.AwareDatetime \| None`	`None`	When the job was accepted.
`completed_at`	`pydantic.types.AwareDatetime \| None`	`None`	Set once the job is terminal (success or failure).
`processing_time_ms`	`int \| None`	`None`	Wall-clock processing time, populated once terminal.
`progress`	`types.api.JobProgress \| None`	`None`	Live progress (percentage, pages) while in flight.
`document`	`types.api.ParseDocument \| None`	`None`	Parsed-document metadata, once completed.
`result`	`types.api.ParseResult \| None`	`None`	Per-page text, populated once completed.
`usage`	`types.api.ParseUsage \| None`	`None`	Pages processed, populated once completed.
`error`	`types.api.ParseError \| None`	`None`	Failure detail on a terminal-failed job, else null.

`ParseJob.poll()`

poll(*, page: int | None = None) -> Self

Re-fetch this job’s status from the API, updating this object in place. Arguments

Name	Type	Description
`page`	`int \| None`	Page of `result.data` to fetch (extract only, results paginate).

Returns

Type	Description
`Self`	`self`, refreshed with the latest status/result.

Raises

Exception	When
`ValueError`	If the job isn’t bound to a client (built by hand, not returned from parse/extract).

`ParseJob.wait()`

wait(timeout: float = 300.0, poll: float = 2.0) -> Self

Block (polling) until the job is terminal, mirrors File.wait. ponytail: dumb poll loop, the API offers no webhook. Arguments

Name	Type	Description
`timeout`	`float`	Max seconds to wait before raising TimeoutError.
`poll`	`float`	Seconds to sleep between status checks.

Returns

Type	Description
`Self`	`self`, once the job has completed successfully.

Raises

Exception	When
`TimeoutError`	If `timeout` elapses before the job is terminal.
`LightOnError`	If the job ends in a terminal-failure state.

ExtractJob

Field	Type	Default	Description
`id`	`str`	required	Async job id; poll its endpoint for status.
`status`	`str`	required	Current status; compare against JobStatus (see .succeeded).
`created_at`	`pydantic.types.AwareDatetime \| None`	`None`	When the job was accepted.
`completed_at`	`pydantic.types.AwareDatetime \| None`	`None`	Set once the job is terminal (success or failure).
`processing_time_ms`	`int \| None`	`None`	Wall-clock processing time, populated once terminal.
`progress`	`types.api.JobProgress \| None`	`None`	Live progress (percentage, pages) while in flight.
`document`	`types.api.ExtractDocument \| None`	`None`	Source-document metadata, once completed.
`result`	`types.api.ExtractResult \| None`	`None`	Extracted data, populated once completed.
`usage`	`types.api.ExtractUsage \| None`	`None`	Pages processed, populated once completed.

`ExtractJob.poll()`

poll(*, page: int | None = None) -> Self

Re-fetch this job’s status from the API, updating this object in place. Arguments

Name	Type	Description
`page`	`int \| None`	Page of `result.data` to fetch (extract only, results paginate).

Returns

Type	Description
`Self`	`self`, refreshed with the latest status/result.

Raises

Exception	When
`ValueError`	If the job isn’t bound to a client (built by hand, not returned from parse/extract).

`ExtractJob.wait()`

wait(timeout: float = 300.0, poll: float = 2.0) -> Self

Block (polling) until the job is terminal, mirrors File.wait. ponytail: dumb poll loop, the API offers no webhook. Arguments

Name	Type	Description
`timeout`	`float`	Max seconds to wait before raising TimeoutError.
`poll`	`float`	Seconds to sleep between status checks.

Returns

Type	Description
`Self`	`self`, once the job has completed successfully.

Raises

Exception	When
`TimeoutError`	If `timeout` elapses before the job is terminal.
`LightOnError`	If the job ends in a terminal-failure state.

BatchIngestJob

A running (or finished) batch ingestion. Returned by Workspace.ingest_many(mode=ExecMode.ASYNC). Uploads (and, when wait=True, ingestion polls) run in a background thread; read progress, succeeded, and failed at any time, or block with wait().

`BatchIngestJob.poll()`

poll() -> BatchProgress

Return the current progress. Mirror of the parse/extract job’s poll(); state updates itself in the background thread, so this just snapshots it.

`BatchIngestJob.wait()`

wait(timeout: float | None = None) -> BatchIngest

Block until the batch finishes, then return its result. Arguments

Name	Type	Description
`timeout`	`float \| None`	Max seconds to wait for the whole batch; None waits forever.

Returns

Type	Description
`BatchIngest`	The terminal `BatchIngest`.

Raises

Exception	When
`TimeoutError`	If the batch doesn’t finish within `timeout`.
`Exception`	The first upload/ingestion error, re-raised, when the batch ran with `ignore_errors=False`.
`_error`

BatchIngest

Terminal result of a batch: the Files that succeeded and what failed.

Field	Type	Default	Description
`succeeded`	`list`	`[]`	Files that succeeded.
`failed`	`list`	`[]`	Failures, each with its cause.

BatchProgress

Live snapshot of a running batch (see BatchIngestJob.progress).

Field	Type	Default	Description
`total`	`int`	required	Total items requested.
`uploaded`	`int`	required	Uploads accepted so far.
`ingested`	`int`	required	Files that reached a terminal-OK status (only advances when wait=True).
`failed`	`int`	required	Failures so far.
`done`	`bool`	required	True once the batch is terminal.

FailedIngest

One file that didn’t make it.

Field	Type	Default	Description
`source`	`Path`	required	The local path that failed.
`error`	`Exception`	required	The exception that caused the failure.
`file`	`file.File \| None`	`None`	The uploaded File when the failure was at ingestion (not the upload itself); None if the upload failed or the path was missing.

Streaming events

AskEvent

AskEvent(...)

Represent a PEP 604 union type E.g. for int | str

SourcesEvent

The retrieved chunks, sent once before generation starts.

Field	Type	Default	Description
`type`	`Literal`	`'sources'`	Event discriminator.
`results`	`list`	`[]`	Retrieved chunks used as context, the same items `ask` returns.

TokenEvent

One chunk of the answer as it generates.

Field	Type	Default	Description
`type`	`Literal`	`'token'`	Event discriminator.
`text`	`str`	`''`	Answer text to append; may be several tokens.

DoneEvent

Generation finished; no further events follow.

Field	Type	Default	Description
`type`	`Literal`	`'done'`	Event discriminator.

Enums

AttributeType

Type of a content-type attribute column. select/multi_select require choices; the API also accepts the aliases multiselect and richtext for the hyphenated values used here.

Member	Value
`text`	`text`
`number`	`number`
`date`	`date`
`boolean`	`boolean`
`select`	`select`
`multi_select`	`multi-select`
`rich_text`	`rich-text`

DownloadPurpose

Which stored version of a file to download. The server falls back to original when the requested purpose has no associated file.

Member	Value
`original`	`original`
`rendered_pdf`	`rendered_pdf`
`transcript`	`transcript`

ExecMode

Execution mode for parse/extract: run inline or queue as an async job. Uppercase members (unlike the other enums here) so the async member can be ASYNC, lowercase async is a Python keyword and can’t be a member name.

Member	Value
`SYNC`	`sync`
`ASYNC`	`async`

FileStatus

Ingestion pipeline status for a File.

Member	Value
`pending`	`pending`
`pending_conversion`	`pending_conversion`
`converting`	`converting`
`parsing`	`parsing`
`parsing_failed`	`parsing_failed`
`embedding`	`embedding`
`embedding_failed`	`embedding_failed`
`embedded`	`embedded`
`parsed`	`parsed`
`fail`	`fail`
`updating`	`updating`

JobStatus

Status of an async parse/extract job. Only pending (initial) and completed (success) are documented by the API, the schema types status as a bare string with no enum and doesn’t publish the failure vocabulary. This enum is for call-site comparisons (StrEnum members equal their string values), NOT to validate the response field, so an unrecognized server value compares unequal rather than erroring. Detect terminal-failure via completed_at being set without completed (or, for parse, the error block) rather than a status string.

Member	Value
`pending`	`pending`
`completed`	`completed`

RelevanceScoring

Cross-encoder relevance scoring step for search.

Member	Value
`none`	`none`
`scoring_only`	`scoring_only`
`scoring_and_filtering`	`scoring_and_filtering`

ReprocessLevel

Reprocessing level queued on a File (pending_reprocess), update = replacement.

Member	Value
`reparse`	`reparse`
`rechunk`	`rechunk`
`reembed`	`reembed`
`reembed_vision`	`reembed_vision`
`update`	`update`

Role

Access role granted by an API-key scope on a workspace.

Member	Value
`viewer`	`viewer`
`editor`	`editor`
`owner`	`owner`

SearchMode

Retrieval mode for search/ask.

Member	Value
`text`	`text`
`vision`	`vision`

ThumbnailStatus

Whether a file’s thumbnail has been generated (uppercase, as the API sends).

Member	Value
`MISSING`	`MISSING`
`PROCESSING`	`PROCESSING`
`READY`	`READY`

Exceptions

Importable from lighton.exceptions. Every method that performs a request can raise these, so they are listed once here rather than repeated on each method. A method’s own Raises block covers only what it raises directly.

Exception	Inherits	Raised when
`LightOnError`	`Exception`	Base class for every error raised by this SDK.
`LightOnAPIError`	`LightOnError`	The API returned a non-2xx response.
`LightOnConnectionError`	`LightOnError`	Transport failure before any response was received (DNS, timeout, reset).
`MalformedResponseError`	`LightOnError`	A 2xx response body was not valid JSON.
`StreamError`	`LightOnError`	The server sent an `error` event partway through a stream. Not a `LightOnAPIError`: the HTTP response was a perfectly good 200 and the failure happened during generation, so there is no status code to carry. The answer is incomplete, which is why this raises instead of arriving as one more event a caller could mistake for a finished answer. `body` holds the payload.
`AuthenticationError`	`LightOnAPIError`	401, bad or missing API key (the request is not authenticated).
`NotFoundError`	`LightOnAPIError`	404, the resource does not exist.
`PermissionDeniedError`	`LightOnAPIError`	403, authenticated, but the key lacks permission for this operation. Distinct from `AuthenticationError`: the credentials are valid, but the caller isn’t allowed (e.g. an endpoint that requires the CompanyAdmin role).
`RateLimitError`	`LightOnAPIError`	429, too many requests. `retry_after` is the seconds to wait before retrying, from the `Retry-After` response header when the server sends it (else None).
`ServerError`	`LightOnAPIError`	5xx, the API failed to handle the request.
`MaintenanceError`	`ServerError`	503 during a planned maintenance window, not a crash. A `ServerError` subclass, so existing `except ServerError` handlers keep working; catch this specifically to tell “come back later” apart from “this broke”, since only one of the two is worth retrying. `mode` is `full_shutdown` or `warning_banner` (both block the request), `reason` is operator-supplied text, `started_at` is when the window opened, and `endpoint_categories` names the affected categories, empty meaning every endpoint. The untouched payload is always on `.body`.

Client

LightOn

LightOn.ask()

LightOn.close()

LightOn.extract()

LightOn.parse()

LightOn.search()

LightOnConfiguration

Workspaces & files

Workspace

Workspace.create()

Workspace.delete()

Workspace.get()

Workspace.ingest()

Workspace.ingest_many()

Workspace.list()

Workspace.refresh()

Workspace.save()

WorkspaceTaxonomy

RootContentType

WorkspaceSync

File

File.classify()

File.clear_attribute()

File.create()

File.delete()

File.delete_many()

File.download()

File.download_thumbnail()

File.facets()

File.get()

File.get_by_name()

File.list()

File.pages()

File.refresh()

File.replace()

File.save()

File.set_attribute()

File.tag()

File.unclassify()

File.untag()

File.wait()

ExternalMetadata

Thumbnail

wait_all

Tags & content types

Tag

Tag.create()

Tag.delete()

Tag.get()

Tag.list()

Tag.refresh()

ContentType

ContentType.adopt()

ContentType.batch()

ContentType.define()

ContentType.define_attribute()

ContentType.list()

ContentType.templates()

ContentType.undefine()

ContentType.undefine_attribute()

Template

Template.adopt()

Template.batch()

Template.define()

Template.define_attribute()

Template.list()

Template.templates()

Template.undefine()

Template.undefine_attribute()

Attribute

Facet

API keys

ApiKey

ApiKey.create()

ApiKey.delete()

ApiKey.get()

ApiKey.list()

ApiKey.refresh()

ApiKey.save()

`LightOn.ask()`

`LightOn.close()`

`LightOn.extract()`

`LightOn.parse()`

`LightOn.search()`

`Workspace.create()`

`Workspace.delete()`

`Workspace.get()`

`Workspace.ingest()`

`Workspace.ingest_many()`

`Workspace.list()`

`Workspace.refresh()`

`Workspace.save()`

`File.classify()`

`File.clear_attribute()`

`File.create()`

`File.delete()`

`File.delete_many()`

`File.download()`

`File.download_thumbnail()`

`File.facets()`

`File.get()`

`File.get_by_name()`

`File.list()`

`File.pages()`

`File.refresh()`

`File.replace()`

`File.save()`

`File.set_attribute()`

`File.tag()`

`File.unclassify()`

`File.untag()`

`File.wait()`

`Tag.create()`

`Tag.delete()`

`Tag.get()`

`Tag.list()`

`Tag.refresh()`

`ContentType.adopt()`

`ContentType.batch()`

`ContentType.define()`

`ContentType.define_attribute()`

`ContentType.list()`

`ContentType.templates()`

`ContentType.undefine()`

`ContentType.undefine_attribute()`

`Template.adopt()`

`Template.batch()`

`Template.define()`

`Template.define_attribute()`

`Template.list()`

`Template.templates()`

`Template.undefine()`

`Template.undefine_attribute()`

`ApiKey.create()`

`ApiKey.delete()`

`ApiKey.get()`

`ApiKey.list()`

`ApiKey.refresh()`

`ApiKey.save()`

`ParseJob.poll()`

`ParseJob.wait()`

`ExtractJob.poll()`

`ExtractJob.wait()`

`BatchIngestJob.poll()`

`BatchIngestJob.wait()`