Claude Client

llm_annotator.clients.claude_client

Anthropic Claude provider implementation.

DEFAULT_TIMEOUT module-attribute

DEFAULT_TIMEOUT = 600.0

Seconds one request may take, the Anthropic SDK's own default.

DEFAULT_TIMEOUT in anthropic/_constants.py is httpx.Timeout(timeout=10 * 60, connect=5.0).

DEFAULT_MAX_RETRIES module-attribute

DEFAULT_MAX_RETRIES = 2

How often the Anthropic SDK retries a failed request, its own default (DEFAULT_MAX_RETRIES in anthropic/_constants.py).

CONNECT_TIMEOUT module-attribute

CONNECT_TIMEOUT = 5.0

Seconds to wait for the TCP connection of one request.

httpx reads a plain float timeout as all four of its limits, so the connect limit is named separately to keep the SDK's own value (DEFAULT_TIMEOUT.connect in anthropic/_constants.py).

ClaudeRuntimeOptions dataclass

ClaudeRuntimeOptions(
    max_completion_tokens: int | None = None,
    output_schema: dict[str, Any] | None = None,
    effort: Literal["low", "medium", "high", "xhigh", "max"]
    | None = None,
    thinking_type: Literal[
        "enabled", "disabled", "adaptive"
    ]
    | None = None,
    thinking_budget: int | None = None,
    thinking_display: Literal[
        "summarized", "omitted", "full"
    ]
    | None = None,
)

Bases: ProviderRuntimeOptions

Runtime options specific to the Claude provider.

effort class-attribute instance-attribute

effort: (
    Literal["low", "medium", "high", "xhigh", "max"] | None
) = None

Controls the amount of effort Claude puts into generating the response, which can affect quality and latency. Higher effort levels may produce better responses but take more time and compute resources. If not specified, the provider default will be used.

thinking_type class-attribute instance-attribute

thinking_type: (
    Literal["enabled", "disabled", "adaptive"] | None
) = None

When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_completion_tokens limit.

thinking_budget class-attribute instance-attribute

thinking_budget: int | None = None

Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than max_completion_tokens.

thinking_display class-attribute instance-attribute

thinking_display: (
    Literal["summarized", "omitted", "full"] | None
) = None

When thinking is enabled (or adaptive). Controls how thinking content appears in the response. When set to summarized, thinking is returned normally. When set to omitted, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to summarized.

ClaudeClient

ClaudeClient(
    model: str,
    max_workers: int | None = 4,
    api_key: str | None = None,
    timeout: float = DEFAULT_TIMEOUT,
    max_retries: int = DEFAULT_MAX_RETRIES,
    on_error: OnError = "warn",
)

Bases: Client[ClaudeRuntimeOptions]

Client wrapper for Anthropic Claude APIs.

The Messages API has no synchronous batch endpoint, so the inherited batch_generate sends one request per sample over a thread pool of max_workers threads.

Initialize the Claude client.

Parameters:

Name	Type	Description	Default
model	str	Claude model identifier.	required
max_workers	int | None	Maximum number of concurrent worker threads for batch_generate. None, 0 and 1 send the requests of a batch one after another.	4
api_key	str | None	Anthropic API key. If not provided, the client will attempt to read from the environment variable ANTHROPIC_API_KEY.	None
timeout	float	Seconds one request may take. The default is the SDK's own (DEFAULT_TIMEOUT in anthropic/_constants.py).	DEFAULT_TIMEOUT
max_retries	int	How often the SDK retries a request it can retry (connection errors, timeouts, and the status codes 408, 409, 429 and 5xx). The default is the SDK's own (DEFAULT_MAX_RETRIES in anthropic/_constants.py).	DEFAULT_MAX_RETRIES
on_error	OnError	Error behavior when generation fails.	'warn'

View source on GitHub: src/llm_annotator/clients/claude_client.py lines 94–133

generate

generate(
    *,
    messages: list[dict[str, str]],
    options: ClaudeRuntimeOptions | None = None,
    gen_kwargs: dict[str, Any] | None = None,
) -> Response

Generate a response using Claude.

Parameters:

Name	Type	Description	Default
messages	list[dict[str, str]]	List of message dictionaries.	required
options	ClaudeRuntimeOptions | None	Provider-specific generation options.	None
gen_kwargs	dict[str, Any] | None	Additional provider-specific generation kwargs that are not covered by the standard options. Has precedence over options.	None

Returns:

Type	Description
Response	A Response object containing the generated response. A failed
Response	request is an error Response when on_error is "warn" or
Response	"ignore".

Raises:

Type	Description
ProviderError	If the request fails and on_error is "raise".
ValueError	If messages holds more than one system message, if a system message is not the first message, or if a message has a role Claude does not take.

View source on GitHub: src/llm_annotator/clients/claude_client.py lines 177–245