harnest.tokens

All Python modules · Import and compatibility guidance

Policy settings

Setting	Default	Behaviour
`enabled`	`True`	`False` bypasses counting, observers, reductions, and enforcement.
`observe`	`True`	Emit reports to `observer`, or the `harnest.tokens` logger.
`enforce`	`False`	Stop calls that exceed configured budgets and apply the output ceiling.
`max_input_tokens`	`None`	Maximum counted input after reductions, including system instructions and tool descriptors.
`context_window`	`None`	Maximum counted input plus reserved output capacity.
`reserve_output_tokens`	`0`	Capacity reserved for the response; Harnest reserves the larger of this value and `max_output_tokens`.
`max_output_tokens`	`None`	Provider output ceiling; preserves a stricter existing native limit.
`output_token_parameter`	`None`	LangGraph override for `max_tokens`, `max_completion_tokens`, or `max_output_tokens`. By default Harnest uses an existing request parameter, then `max_tokens`. ADK always uses its native `max_output_tokens` field.
`max_model_calls`	`None`	Maximum admitted model attempts per agent per runtime invocation, including failed attempts.
`keep_recent_turns`	`None`	Keep this many recent human turns and their model/tool exchanges; pin system/developer instructions.
`max_tool_result_chars`	`None`	Cap each tool-response text string, with a truncation marker. This is a per-string character ceiling, not a total JSON or token ceiling.

Strategy callbacks

Callback	Input	Return
`count_tokens`	Detached `TokenRequest`	`TokenCount(tokens=..., estimated=...)`
`request_transform`	Detached `TokenRequest`	A `TokenRequest`, for example using `dataclasses.replace`.
`tool_selector`	Detached `TokenRequest` after transformation	A list or tuple of existing tool names to expose on this call.
`observer`	Content-free `TokenReport`	No return value required.

Exports

Name	Kind
`TokenBudgetExceeded`	Class
`TokenCount`	Class
`TokenPolicy`	Class
`TokenPolicyError`	Class
`TokenReport`	Class
`TokenRequest`	Class
`token_policy_scope`	Function

TokenBudgetExceeded

A model call was stopped before dispatch by an enabled budget.

TokenBudgetExceeded(budget: str, limit: int, observed: int) -> None

Example

from harnest.tokens import TokenBudgetExceeded

try:
    ...
except TokenBudgetExceeded as error:
    ...

TokenCount

A count with explicit provenance; estimates are never provider usage.

TokenCount(tokens: int, estimated: bool = True) -> None

Fields (— means no declared default):

Field	Type	Default
`tokens`	`int`	`—`
`estimated`	`bool`	`True`

Parameters and example

Parameter	Type	Default
`tokens`	`int`	Required
`estimated`	`bool`	`True`

from harnest.tokens import TokenCount

count = TokenCount(tokens=...)

TokenPolicy

Independently enable observation, enforcement, and authored reductions. Merely constructing a policy observes; limits require enforce=True. Reductions run only when explicitly configured. Callbacks may be sync or async, but synchronous model execution requires synchronous callbacks.

TokenPolicy(
    enabled: bool = True,
    observe: bool = True,
    enforce: bool = False,
    max_input_tokens: int | None = None,
    max_output_tokens: int | None = None,
    output_token_parameter: str | None = None,
    max_model_calls: int | None = None,
    context_window: int | None = None,
    reserve_output_tokens: int = 0,
    keep_recent_turns: int | None = None,
    max_tool_result_chars: int | None = None,
    request_transform: Callable[[TokenRequest], Any] | None = None,
    tool_selector: Callable[[TokenRequest], Any] | None = None,
    count_tokens: Callable[[TokenRequest], Any] | None = None,
    observer: Callable[[TokenReport], Any] | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`enabled`	`bool`	`True`
`observe`	`bool`	`True`
`enforce`	`bool`	`False`
`max_input_tokens`	`int \| None`	`None`
`max_output_tokens`	`int \| None`	`None`
`output_token_parameter`	`str \| None`	`None`
`max_model_calls`	`int \| None`	`None`
`context_window`	`int \| None`	`None`
`reserve_output_tokens`	`int`	`0`
`keep_recent_turns`	`int \| None`	`None`
`max_tool_result_chars`	`int \| None`	`None`
`request_transform`	`Callable[[TokenRequest], Any] \| None`	`None`
`tool_selector`	`Callable[[TokenRequest], Any] \| None`	`None`
`count_tokens`	`Callable[[TokenRequest], Any] \| None`	`None`
`observer`	`Callable[[TokenReport], Any] \| None`	`None`

Parameters and example

Parameter	Type	Default
`enabled`	`bool`	`True`
`observe`	`bool`	`True`
`enforce`	`bool`	`False`
`max_input_tokens`	`int \| None`	`None`
`max_output_tokens`	`int \| None`	`None`
`output_token_parameter`	`str \| None`	`None`
`max_model_calls`	`int \| None`	`None`
`context_window`	`int \| None`	`None`
`reserve_output_tokens`	`int`	`0`
`keep_recent_turns`	`int \| None`	`None`
`max_tool_result_chars`	`int \| None`	`None`
`request_transform`	`Callable[[TokenRequest], Any] \| None`	`None`
`tool_selector`	`Callable[[TokenRequest], Any] \| None`	`None`
`count_tokens`	`Callable[[TokenRequest], Any] \| None`	`None`
`observer`	`Callable[[TokenReport], Any] \| None`	`None`

from harnest.tokens import TokenPolicy

policy = TokenPolicy()

TokenPolicyError

A configured token strategy cannot be applied to a model request.

Example

from harnest.tokens import TokenPolicyError

try:
    ...
except TokenPolicyError as error:
    ...

TokenReport

Content-free observations for one model call or rejected attempt.

TokenReport(
    agent_name: str,
    phase: str,
    model_calls: int,
    input_before: TokenCount | None = None,
    input_after: TokenCount | None = None,
    exceeded: tuple[str, ...] = (),
    messages_removed: int = 0,
    tools_removed: int = 0,
    input_tokens: int | None = None,
    output_tokens: int | None = None,
    total_tokens: int | None = None,
    cached_input_tokens: int | None = None,
    reasoning_tokens: int | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`agent_name`	`str`	`—`
`phase`	`str`	`—`
`model_calls`	`int`	`—`
`input_before`	`TokenCount \| None`	`None`
`input_after`	`TokenCount \| None`	`None`
`exceeded`	`tuple[str, ...]`	`()`
`messages_removed`	`int`	`0`
`tools_removed`	`int`	`0`
`input_tokens`	`int \| None`	`None`
`output_tokens`	`int \| None`	`None`
`total_tokens`	`int \| None`	`None`
`cached_input_tokens`	`int \| None`	`None`
`reasoning_tokens`	`int \| None`	`None`

Parameters and example

Parameter	Type	Default
`agent_name`	`str`	Required
`phase`	`str`	Required
`model_calls`	`int`	Required
`input_before`	`TokenCount \| None`	`None`
`input_after`	`TokenCount \| None`	`None`
`exceeded`	`tuple[str, ...]`	`()`
`messages_removed`	`int`	`0`
`tools_removed`	`int`	`0`
`input_tokens`	`int \| None`	`None`
`output_tokens`	`int \| None`	`None`
`total_tokens`	`int \| None`	`None`
`cached_input_tokens`	`int \| None`	`None`
`reasoning_tokens`	`int \| None`	`None`

from harnest.tokens import TokenReport

report = TokenReport(agent_name=..., phase=..., model_calls=...)

TokenRequest

Detached model input for strategies; message shapes follow framework. ADK messages are Content dictionaries; LangGraph messages use LangChain’s messages_to_dict representation. Settings are native generation options. Tool descriptors are informational; select existing tools by name instead of manufacturing new callable capabilities.

TokenRequest(
    framework: str,
    model: str,
    messages: tuple[dict[str, Any], ...],
    system: Any = None,
    tools: tuple[dict[str, Any], ...] = (),
    settings: dict[str, Any] = ...,
    context_metadata: dict[str, Any] = ...,
) -> None

Fields (— means no declared default):

Field	Type	Default
`framework`	`str`	`—`
`model`	`str`	`—`
`messages`	`tuple[dict[str, Any], ...]`	`—`
`system`	`Any`	`None`
`tools`	`tuple[dict[str, Any], ...]`	`()`
`settings`	`dict[str, Any]`	`dict()`
`context_metadata`	`dict[str, Any]`	`dict()`

Parameters and example

Parameter	Type	Default
`framework`	`str`	Required
`model`	`str`	Required
`messages`	`tuple[dict[str, Any], ...]`	Required
`system`	`Any`	`None`
`tools`	`tuple[dict[str, Any], ...]`	`()`
`settings`	`dict[str, Any]`	`...`
`context_metadata`	`dict[str, Any]`	`...`

from harnest.tokens import TokenRequest

request = TokenRequest(framework=..., model=..., messages=...)

token_policy_scope

Replace or disable policy for trusted code in this scope and child tasks. None disables policy. An agent-specific override takes precedence over a scope-wide override. HTTP metadata never activates this trusted control. Native agents need a configured adapter (TokenPolicy(enabled=False) is sufficient) before a scope can enable policy for them.

token_policy_scope(policy: TokenPolicy | None, *, agent_name: str | None = None) -> Iterator[None]

Parameters and example

Parameter	Type	Default
`policy`	`TokenPolicy \| None`	Required
`agent_name`	`str \| None`	`None`

from harnest.tokens import token_policy_scope

with token_policy_scope(policy=...):
    ...

Overview

Get started

Harnest Studio

Guides

API reference

harnest.tokens

Policy settings

Strategy callbacks

Exports

TokenBudgetExceeded

TokenCount

TokenPolicy

TokenPolicyError

TokenReport

TokenRequest

token_policy_scope

​Policy settings

​Strategy callbacks

​Exports

​TokenBudgetExceeded

​TokenCount

​TokenPolicy

​TokenPolicyError

​TokenReport

​TokenRequest

​token_policy_scope

Policy settings

Strategy callbacks

Exports

TokenBudgetExceeded

TokenCount

TokenPolicy

TokenPolicyError

TokenReport

TokenRequest

token_policy_scope