Errors and utilities
Types and constants
Every object a call returns directly also has request_id and raw_http_response, as in Read the response. Items inside a page don't carry them (reading one raises NaceError), so read the page's own; UploadedFile and JobEvent have neither. DocumentJob, UploadedFile, UploadSession, UploadSessionStatus, JobEvent and JobRequest keep any other field the document service sends as an attribute and in model_extra, such as job.progress.
DocumentJob
| Member | Type | Description |
|---|---|---|
job_id | str | The job's id, which every jobs method takes. |
kind | str | The operation: parse, split, classify, extract or ground. |
status | str | queued, running, succeeded, failed or cancelled. |
result | Any | The result, usually once status is succeeded, else None. Classify may include a partial result while still running, with reason_status (pending, complete, failed or not_requested); a result without reason_status is complete. Its shape is on each tool's page. A succeeded job's result is None again once retention drops it; job.result_state (in model_extra) is then expired or not_retained. See Jobs and results. |
error | Any | The document service's error, usually {"code", "message"}, when the job failed. |
credits | int | None | Credits the job used; final once usage_final is True. Drex charges credits times the operation's price, once. A failed or cancelled job is not charged unless results were already delivered before the cancel or failure. |
usage_final | bool | None | Whether credits is final. |
created_at | str | None | When the job was created, ISO 8601. |
is_terminal | bool | True for succeeded, failed and cancelled. |
error_message | str | None | error["message"], or error itself when it is a string. |
error_code | str | None | error["code"]. |
DocumentJobList has items: tuple[DocumentJob, ...] and next_cursor: str | None, None on the last page.
Upload types
| Type | Fields |
|---|---|
UploadedFile | workspace_id: str, file_id: str, path: str | None, plus the document service's other file fields. as_source() returns a WorkspaceFileSource. |
UploadGrant | workspace_id, upload_url (a document-service URL, not Drex's), token (send as X-Upload-Token), expires_at, max_bytes: int | None. |
UploadSession | workspace_id, session_id, session_token, chunk_size: int, total_parts: int, expires_at, upload_session_url. |
UploadSessionStatus | session_id, status (open, completing, completed or aborted), chunk_size, total_parts, parts (the landed parts, unordered, as {"part_number", "size_bytes"}), received_bytes, declared_size_bytes, expires_at. |
FileDeletion | object (always file_deletion), workspace_id, file_id, status (deleted or deleting). |
Job file types
| Type | Fields |
|---|---|
JobEvent | sequence: int | None (the SSE id), at: str | None (ISO 8601), status: str | None, progress: dict | None (such as units_done, units_total, stage), message: str | None. |
JobRequest | request_type: str; the rest of the request in model_extra. |
FileLink | url: str (fetch it without your API key), expires_at: int (Unix seconds). |
RowsPage | path: str, start_row: int (row number of rows[0]), limit: int, total_rows: int, columns: tuple[RowsColumn, ...], rows: tuple[dict[str, str], ...] (cells keyed by column name). |
RowsColumn | name: str, data_type: str. |
Schema types
| Type | Fields |
|---|---|
ExtractionSchema | schema_id (sch_...), name, description: str | None, version: int, owner ("account", or "platform" for one Nace provides), created_at, updated_at, schema_: dict | None (the JSON Schema; None on a list item). |
ExtractionSchemaList | items: tuple[ExtractionSchema, ...], next_cursor: str | None, total_count: int | None. |
Constants
Client constants
nace_sdk.constants holds the environment variable names and defaults the client uses:
| Name | Value |
|---|---|
API_KEY_ENV | "NACE_API_KEY" |
BASE_URL_ENV | "NACE_BASE_URL" |
DEFAULT_MODEL_ENV | "NACE_DEFAULT_DECISION_MODEL" |
LOG_LEVEL_ENV | "NACE_LOG_LEVEL" |
CONFIG_PATH_ENV | "NACE_CONFIG_PATH", the saved-credentials file's location. |
LEGACY_ENV | {"NACE_API_KEY": "DREX_API_KEY", "NACE_BASE_URL": "DREX_BASE_URL", "NACE_DEFAULT_DECISION_MODEL": "DREX_DEFAULT_MODEL", "NACE_LOG_LEVEL": "DREX_LOG_LEVEL", "NACE_CONFIG_PATH": "DREX_CONFIG_PATH"} |
DEFAULT_BASE_URL | "https://console.nace.ai" |
DEFAULT_MODEL | "drex-latest" |
DEFAULT_TIMEOUT | 60.0 seconds per HTTP attempt |
LEGACY_ENV maps each variable to its name before the packages were renamed from drex-*. read_env(name) returns the stripped value of name, else of its LEGACY_ENV name, and None when both are unset or blank; the SDK, CLI and MCP server read every variable through it.
Document constants
nace_sdk exports the document constants and literal types itself:
| Name | Value |
|---|---|
DOCUMENT_OPERATIONS | ("parse", "split", "classify", "extract", "ground") |
JOB_STATUSES | ("queued", "running", "succeeded", "failed", "cancelled") |
TERMINAL_STATUSES | frozenset({"succeeded", "failed", "cancelled"}) |
MAX_WAIT_SECONDS | 60: the longest wait_seconds. |
MAX_ROWS_PAGE_SIZE | 100: the largest rows limit. |
UPLOAD_SESSION_THRESHOLD_BYTES | 33554432 (32 MiB): upload sends files this size or larger in parts. |
DocumentOperation | Literal["parse", "split", "classify", "extract", "ground"] |
JobStatus | Literal["queued", "running", "succeeded", "failed", "cancelled"] |
OnConflict | Literal["reject", "new_version"] |
nace_sdk.__version__ is the installed version, as a string.