strahl.client

client

Client helpers for registering tools and analyzing OpenAI tool-call transcripts.

The module-level functions are backed by a process-global default client. Use the :class:Strahl class directly when you need isolated state, such as one client per tenant, agent, or test case.

Strahl

Strahl(
    *,
    api_key: str | None = None,
    base_url: str = "https://api.strahl.io",
)

An isolated Strahl client holding tool registrations and role labels.

Each instance has its own HTTP client and registration state. The instance methods mirror the module-level helpers, so code can move between the default client and a dedicated client with only the receiver changed.

Create a client with empty registration state.

Parameters:

Name	Type	Description	Default
api_key	str | None	Optional Strahl API key. This is equivalent to calling :meth:set_api_key immediately after construction.	None
base_url	str	Base URL for the Strahl API.	'https://api.strahl.io'

state instance-attribute

state: StrahlState = StrahlState(tools={}, role_labels={})

api_key instance-attribute

api_key: str | None = api_key

base_url instance-attribute

base_url: str = base_url

lock instance-attribute

lock: Lock = threading.Lock()

http instance-attribute

http: Client = httpx.Client(base_url=base_url)

from_default classmethod

from_default(
    *,
    api_key: str | None = None,
    base_url: str | None = None,
) -> Self

Create a new client from the module-level default client's state.

Tools and role labels are copied by value into a fresh client. Later mutations on either client are independent.

copy

copy(
    *,
    api_key: str | None = None,
    base_url: str | None = None,
) -> Self

Return an independent snapshot of this client.

tool

tool(
    name: str | None = None,
    *,
    requires: Label,
    produces: Label,
    params: Mapping[str, Label] | None = None,
) -> Callable[[F], F]

Register the decorated Python callable as a Strahl tool.

Parameters:

Name	Type	Description	Default
name	str | None	Optional registered tool name. Defaults to the callable's __name__.	None
requires	Label	Label assigned to the tool call and, by default, each tool-call argument.	required
produces	Label	Label assigned to the tool result.	required
params	Mapping[str, Label] | None	Optional per-parameter requirement labels.	None

add_tool

add_tool(
    *,
    fn: dict | Callable,
    requires: Label,
    produces: Label,
    params: Mapping[str, Label] | None = None,
    name: str | None = None,
)

Register a Python callable or OpenAI function tool schema.

requires labels the pending tool call and is also the default label for each argument. produces labels the tool result for later turns. Use params when individual arguments need labels that differ from the tool-level requires label.

Raises:

Type	Description
TypeError	If fn is neither a callable nor a tool schema dict.
ValueError	If the tool name is already registered, if name is provided for a schema dict, or if labels cannot be resolved from the tool's declared parameters.

set_api_key

set_api_key(api_key: str)

Set the API key used for Strahl API requests.

set_role_labels

set_role_labels(labels: Mapping[str, Label])

Set static labels for transcript message roles.

Supported roles are "system", "developer", "user", and "assistant". Role labels must be static because they apply to a message role rather than a particular tool-call argument.

analyze

analyze(messages: list[MessageLike]) -> AnalysisResult

Analyze an OpenAI-style transcript ending in pending tool calls.

Call this after an assistant response requests tool calls and before executing those tools. HTTP failures are propagated as :class:httpx.HTTPStatusError.

set_api_key

set_api_key(api_key: str)

Set the API key on the default client.

set_role_labels

set_role_labels(labels: Mapping[str, Label])

Set role labels on the default client.

tool

tool(
    name: str | None = None,
    *,
    requires: Label,
    produces: Label,
    params: Mapping[str, Label] | None = None,
)

Register a tool on the default client via decorator.

add_tool

add_tool(
    *,
    fn: dict | Callable,
    requires: Label,
    produces: Label,
    params: Mapping[str, Label] | None = None,
    name: str | None = None,
)

Register a Python callable or OpenAI function tool schema on the default client.

analyze

analyze(messages: list[MessageLike]) -> AnalysisResult

Analyze an OpenAI-style transcript with the default client.