Python SDK reference - LightOn Developers

Generated from lighton-sdk 1.0.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,
    max_results: int | None = None,
    relevance_scoring: RelevanceScoring | None = None,
    model: str | None = None,
) -> AskResponse

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.
`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.

Returns

Type	Description
`AskResponse`	The answer plus the ranked results used as context.

`LightOn.close()`

close() -> None

`LightOn.extract()`

extract(
    schema: type[BaseModel] | dict[str, Any],
    *,
    path: str | Path | None = None,
    url: str | None = None,
    options: dict[str, Any] | None = None,
    mode: ExecMode = ExecMode.SYNC,
) -> 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. 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`.

Returns

Type	Description
`ExtractJobResponse \| ExtractJob`	`ExtractJobResponse` (with data) when sync; a pollable `ExtractJob` when async.

Raises

Exception	When
`ValueError`	extract() requires exactly one of ‘path’ or ‘url’

`LightOn.parse()`

parse(
    *,
    path: str | Path | None = None,
    url: str | None = None,
    mode: ExecMode = ExecMode.SYNC,
) -> 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`.

Returns

Type	Description
`ParseResponse \| ParseJob`	`ParseResponse` when sync; a pollable `ParseJob` when async.

Raises

Exception	When
`ValueError`	parse() requires exactly one of ‘path’ or ‘url’

`LightOn.search()`

search(
    query: str,
    *,
    workspaces: list[Workspace | int] | None = None,
    tags: list[Tag | int | str] | None = None,
    files: list[File | int] | 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.
`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).

`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.

File

Field	Type	Default	Description
`id`	`int \| None`	`None`	Server-assigned id; None until created/retrieved.
`path`	`pathlib._local.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.
`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).
`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).
`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) -> 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.

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.

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.refresh()`

refresh() -> Self

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

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

`File.save()`

save() -> File

Persist local edits to title (PATCH). filename is immutable server-side. Returns

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

`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.

Returns

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

Raises

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

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.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.

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).

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).

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.

Enums

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`

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`

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.
`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.

​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()

​File

​File.classify()

​File.clear_attribute()

​File.create()

​File.delete()

​File.facets()

​File.get()

​File.get_by_name()

​File.list()

​File.refresh()

​File.save()

​File.set_attribute()

​File.tag()

​File.unclassify()

​File.untag()

​File.wait()

​wait_all

​Tags & content types

​Tag

​Tag.create()

​Tag.delete()

​Tag.get()

​Tag.list()

​Tag.refresh()

​ContentType

​ContentType.list()

​Attribute

​Facet

​API keys

​ApiKey

​ApiKey.create()

​ApiKey.delete()

​ApiKey.get()

​ApiKey.list()

​ApiKey.refresh()

​ApiKey.save()

​ApiKeyScope

​Jobs & batches

​ParseJob

​ParseJob.poll()

​ExtractJob

​ExtractJob.poll()

​BatchIngestJob

​BatchIngestJob.poll()

​BatchIngestJob.wait()

​BatchIngest

​BatchProgress

​FailedIngest

​Enums

​ExecMode

​FileStatus

​JobStatus

​RelevanceScoring

​Role

​SearchMode

​Exceptions

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()`

File

`File.classify()`

`File.clear_attribute()`

`File.create()`

`File.delete()`

`File.facets()`

`File.get()`

`File.get_by_name()`

`File.list()`

`File.refresh()`

`File.save()`

`File.set_attribute()`

`File.tag()`

`File.unclassify()`

`File.untag()`

`File.wait()`

wait_all

Tags & content types

Tag

`Tag.create()`

`Tag.delete()`

`Tag.get()`

`Tag.list()`

`Tag.refresh()`

ContentType

`ContentType.list()`

Attribute

Facet

API keys

ApiKey

`ApiKey.create()`

`ApiKey.delete()`

`ApiKey.get()`

`ApiKey.list()`

`ApiKey.refresh()`

`ApiKey.save()`

ApiKeyScope

Jobs & batches

ParseJob

`ParseJob.poll()`

ExtractJob

`ExtractJob.poll()`

BatchIngestJob

`BatchIngestJob.poll()`

`BatchIngestJob.wait()`

BatchIngest

BatchProgress

FailedIngest

Enums

ExecMode

FileStatus

JobStatus

RelevanceScoring

Role

SearchMode

Exceptions