> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# harnest.tokens

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## 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`](#tokenbudgetexceeded) | Class |
| [`TokenCount`](#tokencount) | Class |
| [`TokenPolicy`](#tokenpolicy) | Class |
| [`TokenPolicyError`](#tokenpolicyerror) | Class |
| [`TokenReport`](#tokenreport) | Class |
| [`TokenRequest`](#tokenrequest) | Class |
| [`token_policy_scope`](#token_policy_scope) | Function |

## TokenBudgetExceeded

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

```python theme={null}
TokenBudgetExceeded(budget: str, limit: int, observed: int) -> None
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.tokens import TokenBudgetExceeded
>
> try:
>     ...
> except TokenBudgetExceeded as error:
>     ...
> ```

## TokenCount

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

```python theme={null}
TokenCount(tokens: int, estimated: bool = True) -> None
```

Fields (`—` means no declared default):

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

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `tokens` | `int` | Required |
> | `estimated` | `bool` | `True` |
>
> ```python theme={null}
> 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.

```python theme={null}
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` |

> [accordion] 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` |
>
> ```python theme={null}
> from harnest.tokens import TokenPolicy
>
> policy = TokenPolicy()
> ```

## TokenPolicyError

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

> [accordion] Example
>
> ```python theme={null}
> from harnest.tokens import TokenPolicyError
>
> try:
>     ...
> except TokenPolicyError as error:
>     ...
> ```

## TokenReport

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

```python theme={null}
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` |

> [accordion] 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` |
>
> ```python theme={null}
> 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.

```python theme={null}
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()` |

> [accordion] 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]` | `...` |
>
> ```python theme={null}
> 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.

```python theme={null}
token_policy_scope(policy: TokenPolicy | None, *, agent_name: str | None = None) -> Iterator[None]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `policy` | `TokenPolicy \| None` | Required |
> | `agent_name` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.tokens import token_policy_scope
>
> with token_policy_scope(policy=...):
>     ...
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.