API reference¶

The reference below is generated from the public Python signatures and docstrings. Import both objects directly from typesafe_decisions.

DecisionClient¶

typesafe_decisions.DecisionClient ¶

DecisionClient(*, api_key_env: str | None = None, model: str | None = None, retry: RetryPolicy | None = None, timeout: float | Timeout | None = None, headers: Mapping[str, str] | None = None, transport: BaseTransport | None = None, http_client: Client | None = None, base_url: str | None = None)

Make semantic decisions with TypeSafe System One.

Parameters:

api_key_env (str | None, default: None ) –

Name of the environment variable containing the TypeSafe API key. Defaults to TYPESAFE_API_KEY. This is a variable name, not the API key itself.
model (str | None, default: None ) –

Default TypeSafe model passed to the underlying client.
retry (RetryPolicy | None, default: None ) –

Default retry policy passed to the underlying client.
timeout (float | Timeout | None, default: None ) –

Default request timeout passed to the underlying client.
headers (Mapping[str, str] | None, default: None ) –

Default HTTP headers passed to the underlying client.
transport (BaseTransport | None, default: None ) –

Optional HTTP transport used by the underlying client.
http_client (Client | None, default: None ) –

Optional preconfigured HTTP client.
base_url (str | None, default: None ) –

Optional TypeSafe API base URL.

Raises:

RuntimeError –

If the selected API-key environment variable is missing or empty.

Notes

Use the client as a context manager so its HTTP resources are closed after use.

feels ¶

feels(state: JSONContent, question: str, *, model: str | None = None, retry: RetryPolicy | None = None, timeout: float | Timeout | None = None, extra_headers: Mapping[str, str] | None = None, extra_body: Mapping[str, JSONValue | None] | None = None) -> float

Measure how strongly a state satisfies a semantic question.

Parameters:

state (JSONContent) –

Text or JSON-compatible data to evaluate.
question (str) –

The property to measure, for example whether the state needs an urgent reply.
model (str | None, default: None ) –

Model override for this request.
retry (RetryPolicy | None, default: None ) –

Retry-policy override for this request.
timeout (float | Timeout | None, default: None ) –

Timeout override for this request.
extra_headers (Mapping[str, str] | None, default: None ) –

Additional HTTP headers for this request.
extra_body (Mapping[str, JSONValue | None] | None, default: None ) –

Additional JSON fields for this request.

Returns:

float –

The score returned for the question by TypeSafe System One.

Raises:

TypeSafeAPIError –

If the TypeSafe request fails. The exception is re-raised unchanged after its status and request ID are printed.

match ¶

match(state: JSONContent, question: JSONContent, criteria: Mapping[str, JSONContent | None], *, model: str | None = None, retry: RetryPolicy | None = None, timeout: float | Timeout | None = None, extra_headers: Mapping[str, str] | None = None, extra_body: Mapping[str, JSONValue | None] | None = None, response_model: None = None) -> str

match(state: JSONContent, question: JSONContent, criteria: Mapping[str, JSONContent | None], *, model: str | None = None, retry: RetryPolicy | None = None, timeout: float | Timeout | None = None, extra_headers: Mapping[str, str] | None = None, extra_body: Mapping[str, JSONValue | None] | None = None, response_model: type[ResponseT]) -> ResponseT

match(state: JSONContent, question: JSONContent, criteria: Mapping[str, JSONContent | None], *, model: str | None = None, retry: RetryPolicy | None = None, timeout: float | Timeout | None = None, extra_headers: Mapping[str, str] | None = None, extra_body: Mapping[str, JSONValue | None] | None = None, response_model: type[ResponseT] | None = None) -> str | ResponseT

Select the criterion that best matches state.

Parameters:

state (JSONContent) –

Text or JSON-compatible data to classify.
question (JSONContent) –

The decision instruction sent to TypeSafe.
criteria (Mapping[str, JSONContent | None]) –

Mapping of returned labels to their semantic definitions. A definition may be None when the label is self-explanatory.
model (str | None, default: None ) –

Model override for this request.
retry (RetryPolicy | None, default: None ) –

Retry-policy override for this request.
timeout (float | Timeout | None, default: None ) –

Timeout override for this request.
extra_headers (Mapping[str, str] | None, default: None ) –

Additional HTTP headers for this request.
extra_body (Mapping[str, JSONValue | None] | None, default: None ) –

Additional JSON fields for this request.
response_model (type[ResponseT] | None, default: None ) –

Optional Pydantic model describing the System One response body.

Returns:

str | ResponseT –

The selected criterion label. If response_model is provided,
str | ResponseT –

the parsed model instance returned by the SDK is returned unchanged.

Raises:

TypeSafeAPIError –

If the TypeSafe request fails. The exception is re-raised unchanged after its status and request ID are printed.

llm¶

typesafe_decisions.llm ¶

llm(instruction: str, using: JSONValue | None = None, *, account_id: str | None = None, api_token: str | None = None, gateway_id: str | None = None, model: str | None = None, max_tokens: int = 300, temperature: float = 0.9, timeout: float | Timeout = 25.0) -> str

Generate text through Cloudflare AI Gateway.

Parameters:

instruction (str) –

The writing instruction sent to the text model.
using (JSONValue | None, default: None ) –

Optional explicit context for the instruction. No application state is added implicitly.
account_id (str | None, default: None ) –

Cloudflare account ID. Defaults to CF_ACCOUNT_ID.
api_token (str | None, default: None ) –

Cloudflare API token. Defaults to CF_API_TOKEN.
gateway_id (str | None, default: None ) –

AI Gateway ID. Defaults to GATEWAY_ID and then "default".
model (str | None, default: None ) –

Workers AI model identifier. Defaults to TEXT_MODEL and then the package's default text model.
max_tokens (int, default: 300 ) –

Maximum number of generated tokens requested from the model.
temperature (float, default: 0.9 ) –

Sampling temperature passed to the model.
timeout (float | Timeout, default: 25.0 ) –

HTTP request timeout.

Returns:

str –

Generated text with leading and trailing whitespace removed.

Raises:

RuntimeError –

If required configuration is missing, Cloudflare rejects the request, or the response does not contain valid generated text.