SDK reference¶

Auto-generated from the incheck Python package.

Clients¶

incheck.Client ¶

Client(
    api_key: str | None = None,
    *,
    environment: Environment | None = None,
    base_url: str | None = None,
    timeout: float = 120.0,
    http_client: Client | None = None,
)

Synchronous InCheck API client.

Example

from incheck import Client

with Client() as client: # INCHECK_API_KEY from env for org in client.documents.list_orgs().org_ids: print(org)

Point at the staging (acceptance) environment:¶

with Client(environment="staging") as client: ...

incheck.AsyncClient ¶

AsyncClient(
    api_key: str | None = None,
    *,
    environment: Environment | None = None,
    base_url: str | None = None,
    timeout: float = 120.0,
    http_client: AsyncClient | None = None,
)

Asynchronous InCheck API client.

Example

import asyncio from incheck import AsyncClient

async def main(): async with AsyncClient(environment="staging") as client: orgs = await client.documents.list_orgs() print(orgs.org_ids)

asyncio.run(main())

Documents resource¶

incheck.resources.documents.DocumentsResource ¶

DocumentsResource(client: 'Client')

list_orgs ¶

list_orgs() -> OrgListResponse

Every org_id under your namespace.

list ¶

list(org_id: str) -> DocumentListResponse

All documents in an org_id's current version (with presigned GETs).

wait_for_job ¶

wait_for_job(
    job_id: str,
    *,
    timeout: float = 600.0,
    poll_interval: float = 10.0,
) -> JobStatus

Block until the job reaches a terminal state or timeout elapses.

Raises :class:~incheck.exceptions.JobFailedError on failed and :class:~incheck.exceptions.JobTimeoutError if the deadline is hit.

upload ¶

upload(
    org_id: str,
    files: Iterable[FileSpec],
    *,
    batch_size: int = 6,
    wait: bool = True,
    timeout: float = 600.0,
    poll_interval: float = 10.0,
) -> JobStatus | UploadCompleted

Initiate → PUT to S3 → complete → (optionally) poll until done.

Parameters:

Name	Type	Description	Default
`org_id`	`str`	Hierarchical org_id (must start with your namespace).	required
`files`	`Iterable[FileSpec]`	Local paths or `(filename, file_like)` tuples.	required
`batch_size`	`int`	Document-chunking batch size (1-20).	`6`
`wait`	`bool`	When True (default), block until the processing job reaches a terminal state and return the final :class:`JobStatus`. When False, return the :class:`UploadCompleted` from `complete-upload` and let the caller poll.	`True`
`timeout`	`float`	Max seconds to wait when `wait=True`.	`600.0`
`poll_interval`	`float`	Seconds between status polls.	`10.0`

incheck.resources.documents.AsyncDocumentsResource ¶

AsyncDocumentsResource(client: 'AsyncClient')

Chat resource¶

incheck.resources.chat.ChatResource ¶

ChatResource(client: 'Client')

send ¶

send(
    content: str,
    *,
    org_id: OrgIdOrList | None = None,
    user_id: str = "sdk",
    conversation_id: str | None = None,
    scope: str = "ALS",
    state: str = "Massachusetts",
    messages: Sequence[MessageInput] | None = None,
    conversation_hx: str | None = None,
) -> ChatResponse

Send a chat message and return the aggregated reply.

Parameters:

Name	Type	Description	Default
`content`	`str`	The current user message.	required
`org_id`	`OrgIdOrList \| None`	Optional. Pass your Pod's hierarchical org_id to run in unified mode (retrieval-aware against the documents onboarded into that Pod via the Documents API). Pass a list of org_ids to fan retrieval across several Pods in one request. Omit it to run in EMS mode (general EMS knowledge, no retrieval). Every id's first segment must equal your namespace.	`None`
`user_id`	`str`	An identifier for the end-user. Audit trail only.	`'sdk'`
`conversation_id`	`str \| None`	Optional — a UUID is generated if omitted.	`None`
`scope`	`str`	EMS scope (`"ALS"`, `"BLS"`, …).	`'ALS'`
`state`	`str`	US state for state-specific protocols.	`'Massachusetts'`
`messages`	`Sequence[MessageInput] \| None`	Optional prior turns as `ChatMessage` instances or plain `{"role", "content"}` dicts. Must alternate `user` / `assistant` starting with `user` and ending with `assistant` — the current user turn stays in `content` and is appended by the gateway. Works in both EMS and unified mode.	`None`
`conversation_hx`	`str \| None`	Deprecated. Prefer `messages`. The legacy single-string history field, still accepted by the gateway in EMS mode for back-compat. Mutually exclusive with `messages` — the gateway returns 422 if both are set.	`None`

Returns:

Name	Type	Description
`A`	`ChatResponse`	class:`~incheck.models.ChatResponse` with `content`
	`ChatResponse`	joined and the raw chunks available on `raw`.

Example

EMS mode — no Pod needed¶

client.chat.send("Adult atropine dose for bradycardia?")

Unified mode — answer from your onboarded Pod¶

client.chat.send( ... "Per our SOP, what's the hazmat escalation path?", ... org_id="acme_dispatch", ... )

Multi-Pod fan-out — retrieve from both Pods in one call¶

client.chat.send( ... "Compare hazmat escalation between dispatch and wilderness ops.", ... org_id=["acme_dispatch", "acme_wilderness"], ... )

Multi-turn — pass prior turns as messages¶

from incheck import ChatMessage client.chat.send( ... "And for a 6-year-old?", ... messages=[ ... ChatMessage(role="user", content="Adult atropine dose?"), ... ChatMessage(role="assistant", content="1 mg IV/IO q3-5min, max 3 mg."), ... ], ... )

stream ¶

stream(
    content: str,
    *,
    org_id: OrgIdOrList | None = None,
    user_id: str = "sdk",
    conversation_id: str | None = None,
    scope: str = "ALS",
    state: str = "Massachusetts",
    messages: Sequence[MessageInput] | None = None,
    conversation_hx: str | None = None,
) -> Iterator[ChatChunk]

Stream chat chunks as they arrive (SSE).

Identical contract to :meth:send, but yields each :class:~incheck.models.ChatChunk as it lands. Terminates on the type='complete' marker.

Example

for chunk in client.chat.stream( ... "Summarize the dispatch SOP.", ... org_id="acme_dispatch", ... ): ... if chunk.content: ... print(chunk.content, end="", flush=True)

incheck.resources.chat.AsyncChatResource ¶

AsyncChatResource(client: 'AsyncClient')

send `async` ¶

send(
    content: str,
    *,
    org_id: OrgIdOrList | None = None,
    user_id: str = "sdk",
    conversation_id: str | None = None,
    scope: str = "ALS",
    state: str = "Massachusetts",
    messages: Sequence[MessageInput] | None = None,
    conversation_hx: str | None = None,
) -> ChatResponse

Async counterpart of :meth:ChatResource.send.

stream `async` ¶

stream(
    content: str,
    *,
    org_id: OrgIdOrList | None = None,
    user_id: str = "sdk",
    conversation_id: str | None = None,
    scope: str = "ALS",
    state: str = "Massachusetts",
    messages: Sequence[MessageInput] | None = None,
    conversation_hx: str | None = None,
) -> AsyncIterator[ChatChunk]

Async counterpart of :meth:ChatResource.stream.

Metadata resource¶

incheck.resources.metadata.MetadataResource ¶

MetadataResource(client: 'Client')

states_and_scopes ¶

states_and_scopes() -> StatesAndScopesResponse

Fetch the canonical state / scope reference data.

Returns a :class:~incheck.models.StatesAndScopesResponse with the default state and scope, the full enumerations, and a scopes_by_state map. Only the value field on each entry is accepted by /chat — label is for human display.

Example

meta = client.metadata.states_and_scopes() reply = client.chat.send( ... "Adult atropine dose for bradycardia?", ... scope=meta.default_scope, ... state=meta.default_state, ... )

incheck.resources.metadata.AsyncMetadataResource ¶

AsyncMetadataResource(client: 'AsyncClient')

states_and_scopes `async` ¶

states_and_scopes() -> StatesAndScopesResponse

Async counterpart of :meth:MetadataResource.states_and_scopes.

Models¶

incheck.models.UploadInitiated ¶

Bases: _IncheckModel

Result of a successful documents.initiate_upload call.

incheck.models.PresignedUpload ¶

Bases: _IncheckModel

One file's presigned-POST credentials, returned by initiate-upload.

Pass upload_fields verbatim as multipart form fields, then attach the file under the file field, and POST to upload_url. S3 will respond with 204 No Content on success.

incheck.models.UploadCompleted ¶

Bases: _IncheckModel

Result of documents.complete_upload — processing has been triggered.

incheck.models.UpdateInitiated ¶

Bases: _IncheckModel

Result of documents.initiate_update for an existing org_id.

incheck.models.OrgListResponse ¶

Bases: _IncheckModel

Result of documents.list_orgs() — always filtered to your namespace.

incheck.models.OrgInfo ¶

Bases: _IncheckModel

A single org_id discovered under your namespace.

incheck.models.DocumentListResponse ¶

Bases: _IncheckModel

incheck.models.DocumentInfo ¶

DocumentInfo(**data: Any)

Bases: _IncheckModel

A single document inside an org_id's current version.

download_url exposes the short-lived presigned GET URL (the API field name is presigned_url; the SDK normalises to download_url for symmetry with other SDKs).

incheck.models.VersionInfo ¶

Bases: _IncheckModel

incheck.models.JobStatus ¶

Bases: _IncheckModel

Status of a document-processing job.

status is one of: initiated, pending, processing, completed, failed. Use :meth:is_terminal to check.

incheck.models.JobProgress ¶

Bases: _IncheckModel

incheck.models.DeleteResponse ¶

Bases: _IncheckModel

Result of a successful delete.

The API returns 2xx on a successful delete with a body shaped like {"message": "Deleted permanently"}. success is synthesised from the HTTP status — anything reaching this model is a success.

incheck.models.ChatMessage ¶

Bases: _IncheckModel

One prior turn in a multi-turn chat.

Wire-compatible with the OpenAI / Anthropic Messages API shape. Pass a list of these (or plain dicts of the same shape) as messages= to :meth:incheck.Client.chat.send / stream to give the model the conversation so far. Prior turns must alternate user / assistant starting with user and ending with assistant — the current user turn lives in the positional content argument and is appended by the gateway.

incheck.models.ChatResponse ¶

Bases: _IncheckModel

Aggregated non-streaming chat reply.

incheck.models.ChatChunk ¶

Bases: _IncheckModel

A single Server-Sent-Event payload from streaming /chat.

Streamed chunks carry content deltas. The final event has type='complete' and no content.

incheck.models.StateOrScope ¶

Bases: _IncheckModel

A single state or scope entry returned by metadata.

Only value is part of the wire contract — that's what you send on /chat. label is for human display (UI dropdowns, picker text) and is never accepted by the API.

incheck.models.StatesAndScopesResponse ¶

Bases: _IncheckModel

The reference data behind /chat's state / scope fields.

Use :attr:default_state and :attr:default_scope as sensible defaults for your UI, and scopes_by_state (falling back to the "_default" key) to constrain a scope picker to the scopes valid for the currently selected state.

Errors¶

incheck.exceptions.IncheckError ¶

IncheckError(
    message: str,
    *,
    status_code: int | None = None,
    response_body: Any = None,
)

Bases: Exception

Base class for all InCheck SDK errors.

incheck.exceptions.AuthenticationError ¶

AuthenticationError(
    message: str,
    *,
    status_code: int | None = None,
    response_body: Any = None,
)

Bases: IncheckError

401 — missing or invalid API key.

incheck.exceptions.PermissionError ¶

PermissionError(
    message: str,
    *,
    status_code: int | None = None,
    response_body: Any = None,
)

Bases: IncheckError

403 — caller is authenticated but not allowed (often a namespace mismatch).

incheck.exceptions.NotFoundError ¶

NotFoundError(
    message: str,
    *,
    status_code: int | None = None,
    response_body: Any = None,
)

Bases: IncheckError

404 — resource (org, job, version) does not exist.

incheck.exceptions.ValidationError ¶

ValidationError(
    message: str,
    *,
    status_code: int | None = None,
    response_body: Any = None,
)

Bases: IncheckError

400 / 422 — request did not pass validation.

incheck.exceptions.RateLimitError ¶

RateLimitError(
    message: str,
    *,
    status_code: int | None = None,
    response_body: Any = None,
    retry_after: float | None = None,
)

Bases: IncheckError

429 — per-key rate limit exceeded.

incheck.exceptions.APIError ¶

APIError(
    message: str,
    *,
    status_code: int | None = None,
    response_body: Any = None,
)

Bases: IncheckError

5xx response from the gateway or an upstream service.

incheck.exceptions.APIConnectionError ¶

APIConnectionError(
    message: str,
    *,
    status_code: int | None = None,
    response_body: Any = None,
)

Bases: IncheckError

Network-level failure reaching the gateway.

incheck.exceptions.JobFailedError ¶

JobFailedError(message: str, *, job_id: str, status: str)

Bases: IncheckError

A document-processing job ended in a failed/error state.

incheck.exceptions.JobTimeoutError ¶

JobTimeoutError(
    message: str, *, job_id: str, last_status: str | None
)

Bases: IncheckError

wait_for_job exceeded its deadline before the job reached a terminal state.

SDK reference¶

Clients¶

incheck.Client ¶

Point at the staging (acceptance) environment:¶

incheck.AsyncClient ¶

Documents resource¶

incheck.resources.documents.DocumentsResource ¶

list_orgs ¶

list ¶

wait_for_job ¶

upload ¶

incheck.resources.documents.AsyncDocumentsResource ¶

Chat resource¶

incheck.resources.chat.ChatResource ¶

send ¶

EMS mode — no Pod needed¶

Unified mode — answer from your onboarded Pod¶

Multi-Pod fan-out — retrieve from both Pods in one call¶

Multi-turn — pass prior turns as messages¶

stream ¶

incheck.resources.chat.AsyncChatResource ¶

send async ¶

stream async ¶

Metadata resource¶

incheck.resources.metadata.MetadataResource ¶

states_and_scopes ¶

incheck.resources.metadata.AsyncMetadataResource ¶

states_and_scopes async ¶

Models¶

incheck.models.UploadInitiated ¶

incheck.models.PresignedUpload ¶

incheck.models.UploadCompleted ¶

incheck.models.UpdateInitiated ¶

incheck.models.OrgListResponse ¶

incheck.models.OrgInfo ¶

incheck.models.DocumentListResponse ¶

incheck.models.DocumentInfo ¶

incheck.models.VersionInfo ¶

incheck.models.JobStatus ¶

incheck.models.JobProgress ¶

incheck.models.DeleteResponse ¶

incheck.models.ChatMessage ¶

incheck.models.ChatResponse ¶

incheck.models.ChatChunk ¶

incheck.models.StateOrScope ¶

incheck.models.StatesAndScopesResponse ¶

Errors¶

incheck.exceptions.IncheckError ¶

incheck.exceptions.AuthenticationError ¶

incheck.exceptions.PermissionError ¶

incheck.exceptions.NotFoundError ¶

incheck.exceptions.ValidationError ¶

incheck.exceptions.RateLimitError ¶

incheck.exceptions.APIError ¶

incheck.exceptions.APIConnectionError ¶

incheck.exceptions.JobFailedError ¶

incheck.exceptions.JobTimeoutError ¶

send `async` ¶

stream `async` ¶

states_and_scopes `async` ¶