strahl

strahl

ALL module-attribute

ALL: TagSet = frozenset({'*'})

NONE module-attribute

NONE: TagSet = frozenset()

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'

lock instance-attribute

lock: Lock = threading.Lock()

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

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.

Label dataclass

Label(source: TagSetExpr, visibility: TagSetExpr)

source instance-attribute

source: TagSetExpr

visibility instance-attribute

visibility: TagSetExpr

__post_init__

__post_init__()

resolvable_from_params

resolvable_from_params(params: Container[str]) -> bool

resolvable_at_creation_time

resolvable_at_creation_time() -> bool

resolve

resolve(kwargs: dict | None = None) -> Label

StrahlAPIError

Raised when the Strahl API returns a response the SDK cannot interpret.

StrahlDenied

StrahlDenied(
    result: AnalysisResult | ToolCallAnalysisResult,
    message: str | None = None,
)

Raised when a Strahl analysis denies one or more tool calls.

result instance-attribute

result: AnalysisResult | ToolCallAnalysisResult = result

analysis instance-attribute

analysis: AnalysisResult | None

tool_call instance-attribute

tool_call: ToolCallAnalysisResult | None

denied_tool_calls instance-attribute

denied_tool_calls: tuple[ToolCallAnalysisResult, ...]

StrahlError

Base class for Strahl SDK errors.

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.

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.