> ## 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.model

> 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)

## Exports

| Name | Kind |
| - | - |
| [`LiteLLMContext`](#litellmcontext) | Class |
| [`LiteLLMLifecycle`](#litellmlifecycle) | Class |
| [`LiteLLMModel`](#litellmmodel) | Class |
| [`ModelCallRequest`](#modelcallrequest) | Class |
| [`ModelCallResponse`](#modelcallresponse) | Class |
| [`ModelConnector`](#modelconnector) | Class |
| [`ModelLifecycleContext`](#modellifecyclecontext) | Class |
| [`ModelLifecycleError`](#modellifecycleerror) | Class |
| [`ModelMessage`](#modelmessage) | Class |
| [`resolve_model`](#resolve_model) | Function |
| [`resolve_model_for`](#resolve_model_for) | Function |

## LiteLLMContext

Stable call context provided to every LiteLLM lifecycle hook.

```python theme={null}
LiteLLMContext(model: str, framework: Literal['adk', 'langgraph'], transport: Any | None = None) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `model` | `str` | `—` |
| `framework` | `Literal['adk', 'langgraph']` | `—` |
| `transport` | `Any \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `model` | `str` | Required |
> | `framework` | `Literal['adk', 'langgraph']` | Required |
> | `transport` | `Any \| None` | `None` |
>
> ```python theme={null}
> from harnest.model import LiteLLMContext
>
> context = LiteLLMContext(model=..., framework=...)
> ```

## LiteLLMLifecycle

Customize one LiteLLM model's transport and call lifecycle.

Override hooks with either ordinary or `async` methods. Async hooks require
the framework's async invocation path; Harnest never runs a private event
loop to make them appear synchronous.

```python theme={null}
LiteLLMLifecycle()
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.model import LiteLLMLifecycle
>
> lifecycle = LiteLLMLifecycle()
> ```

### LiteLLMLifecycle.create\_transport

```python theme={null}
LiteLLMLifecycle.create_transport(context: LiteLLMContext) -> LifecycleValue
```

Return a provider client accepted by LiteLLM's `client` option.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `LiteLLMContext` | Required |
>
> ```python theme={null}
> from harnest.model import LiteLLMLifecycle
>
> lifecycle: LiteLLMLifecycle
> result = lifecycle.create_transport(context=...)
> ```

### LiteLLMLifecycle.before\_request

```python theme={null}
LiteLLMLifecycle.before_request(request: dict[str, Any], context: LiteLLMContext) -> LifecycleValue
```

Mutate `request` or return its replacement before LiteLLM runs.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `request` | `dict[str, Any]` | Required |
> | `context` | `LiteLLMContext` | Required |
>
> ```python theme={null}
> from harnest.model import LiteLLMLifecycle
>
> lifecycle: LiteLLMLifecycle
> result = lifecycle.before_request(request=..., context=...)
> ```

### LiteLLMLifecycle.after\_response

```python theme={null}
LiteLLMLifecycle.after_response(response: Any, context: LiteLLMContext) -> LifecycleValue
```

Return a non-stream response replacement or observe stream exhaustion.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `response` | `Any` | Required |
> | `context` | `LiteLLMContext` | Required |
>
> ```python theme={null}
> from harnest.model import LiteLLMLifecycle
>
> lifecycle: LiteLLMLifecycle
> result = lifecycle.after_response(response=..., context=...)
> ```

### LiteLLMLifecycle.on\_error

```python theme={null}
LiteLLMLifecycle.on_error(error: BaseException, context: LiteLLMContext) -> LifecycleValue
```

Observe a lifecycle or LiteLLM failure before it is re-raised.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `error` | `BaseException` | Required |
> | `context` | `LiteLLMContext` | Required |
>
> ```python theme={null}
> from harnest.model import LiteLLMLifecycle
>
> lifecycle: LiteLLMLifecycle
> result = lifecycle.on_error(error=..., context=...)
> ```

### LiteLLMLifecycle.close

```python theme={null}
LiteLLMLifecycle.close(context: LiteLLMContext) -> LifecycleValue
```

Release resources created for this model instance.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `LiteLLMContext` | Required |
>
> ```python theme={null}
> from harnest.model import LiteLLMLifecycle
>
> lifecycle: LiteLLMLifecycle
> result = lifecycle.close(context=...)
> ```

## LiteLLMModel

A provider-neutral model routed through a framework LiteLLM adapter.

`model` must use LiteLLM's explicit `provider/model` form. All keyword
arguments reach the underlying LiteLLM completion call, including provider
settings such as `api_base`, `api_key`, and generation options.
`thinking` selects a portable on/off mode; omit it to use the provider
default or pass `reasoning_effort` directly for provider-specific levels.
`prompt_cache` enables provider prompt-cache breakpoints where the
provider requires them; it defaults to `True` and never changes OpenAI or
Gemini requests.

```python theme={null}
LiteLLMModel(
    model: str,
    *,
    thinking: bool | None = None,
    lifecycle: LiteLLMLifecycle | None = None,
    prompt_cache: bool = True,
    **completion_args: Any,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `model` | `str` | `—` |
| `completion_args` | `Mapping[str, Any]` | `—` |
| `lifecycle` | `LiteLLMLifecycle \| None` | `None` |
| `prompt_cache` | `bool` | `True` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `model` | `str` | Required | LiteLLM model ID in `provider/model` form. |
> | `thinking` | `bool \| None` | `None` | Turn reasoning on or off. Omit for the provider default. |
> | `lifecycle` | `LiteLLMLifecycle \| None` | `None` | Optional `LiteLLMLifecycle` that owns the transport. |
> | `prompt_cache` | `bool` | `True` | Add provider prompt-cache breakpoints where needed. |
> | `**completion_args` | `Any` | Optional | Extra LiteLLM arguments, such as `api_base`, `api_key`, or `temperature`. |
>
> ```python theme={null}
> from harnest.model import LiteLLMModel
>
> model = LiteLLMModel("openai/your-model", api_base="https://models.example.invalid/v1")
> ```

### LiteLLMModel.build

```python theme={null}
LiteLLMModel.build() -> Any
```

Build ADK's `LiteLlm` without contacting the provider.

> [accordion] Example
>
> ```python theme={null}
> from harnest.model import LiteLLMModel
>
> model: LiteLLMModel
> result = model.build()
> ```

### LiteLLMModel.build\_for

```python theme={null}
LiteLLMModel.build_for(framework: str) -> Any
```

Build the connector for a supported Harnest framework.

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `framework` | `str` | Required | `"adk"` or `"langgraph"`. |
>
> ```python theme={null}
> from harnest.model import LiteLLMModel
>
> model: LiteLLMModel
> result = model.build_for(framework=...)
> ```

### LiteLLMModel.build\_langgraph

```python theme={null}
LiteLLMModel.build_langgraph() -> Any
```

Build LangChain's LiteLLM chat model without contacting the provider.

> [accordion] Example
>
> ```python theme={null}
> from harnest.model import LiteLLMModel
>
> model: LiteLLMModel
> result = model.build_langgraph()
> ```

### LiteLLMModel.from\_openai\_environment

```python theme={null}
LiteLLMModel.from_openai_environment(
    *,
    default_model: str | None = None,
    thinking: bool | None = None,
    lifecycle: LiteLLMLifecycle | None = None,
    prompt_cache: bool = True,
    **completion_args: Any,
) -> 'LiteLLMModel'
```

Use an explicitly configured OpenAI-compatible API, not a default vendor.

OPENAI\_MODEL and OPENAI\_BASE\_URL are required; OPENAI\_API\_KEY is optional.
This reads the process environment without loading dotenv. Explicit
completion arguments override environment values. Model IDs may contain
slashes; the optional `openai/` prefix selects the wire protocol only.

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `default_model` | `str \| None` | `None` | Model ID used when `OPENAI_MODEL` is not set. |
> | `thinking` | `bool \| None` | `None` | Same as the `LiteLLMModel` option. |
> | `lifecycle` | `LiteLLMLifecycle \| None` | `None` | Same as the `LiteLLMModel` option. |
> | `prompt_cache` | `bool` | `True` | Same as the `LiteLLMModel` option. |
> | `**completion_args` | `Any` | Optional | Extra arguments that override environment values. |
>
> ```python theme={null}
> from harnest.model import LiteLLMModel
>
> model = LiteLLMModel.from_openai_environment()  # reads OPENAI_MODEL and OPENAI_BASE_URL
> ```

## ModelCallRequest

Portable model input that a listener may replace or short-circuit.

```python theme={null}
ModelCallRequest(model: str | None, messages: tuple[ModelMessage, ...]) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `model` | `str \| None` | `—` |
| `messages` | `tuple[ModelMessage, ...]` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `model` | `str \| None` | Required |
> | `messages` | `tuple[ModelMessage, ...]` | Required |
>
> ```python theme={null}
> from harnest.model import ModelCallRequest
>
> request = ModelCallRequest(model=..., messages=...)
> ```

## ModelCallResponse

Portable visible model output.

```python theme={null}
ModelCallResponse(text: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `text` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `text` | `str` | Required |
>
> ```python theme={null}
> from harnest.model import ModelCallResponse
>
> response = ModelCallResponse(text=...)
> ```

## ModelConnector

A lazily constructed model with ADK and LangGraph adapters.

Connectors keep optional model-provider imports out of config discovery and
agent validation. Plain model strings and already-built ADK `BaseLlm`
objects do not need a connector.

```python theme={null}
ModelConnector()
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.model import ModelConnector
>
> class MyModelConnector(ModelConnector):
>     ...
> ```

### ModelConnector.build

```python theme={null}
ModelConnector.build() -> Any
```

Build the model object accepted by ADK's `LlmAgent`.

> [accordion] Example
>
> ```python theme={null}
> from harnest.model import ModelConnector
>
> connector: ModelConnector
> result = connector.build()
> ```

### ModelConnector.build\_for

```python theme={null}
ModelConnector.build_for(framework: str) -> Any
```

Build the connector for a supported Harnest framework.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `str` | Required |
>
> ```python theme={null}
> from harnest.model import ModelConnector
>
> connector: ModelConnector
> result = connector.build_for(framework=...)
> ```

### ModelConnector.build\_langgraph

```python theme={null}
ModelConnector.build_langgraph() -> Any
```

Build a LangChain chat model for LangGraph.

> [accordion] Example
>
> ```python theme={null}
> from harnest.model import ModelConnector
>
> connector: ModelConnector
> result = connector.build_langgraph()
> ```

## ModelLifecycleContext

Stable provider-neutral facts associated with one model call.

```python theme={null}
ModelLifecycleContext(
    framework: str,
    agent_name: str | None = None,
    invocation_id: str | None = None,
    user_id: str | None = None,
    session_id: str | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `framework` | `str` | `—` |
| `agent_name` | `str \| None` | `None` |
| `invocation_id` | `str \| None` | `None` |
| `user_id` | `str \| None` | `None` |
| `session_id` | `str \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `str` | Required |
> | `agent_name` | `str \| None` | `None` |
> | `invocation_id` | `str \| None` | `None` |
> | `user_id` | `str \| None` | `None` |
> | `session_id` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.model import ModelLifecycleContext
>
> context = ModelLifecycleContext(framework=...)
> ```

### ModelLifecycleContext.next

```python theme={null}
ModelLifecycleContext.next(replacement: Any = UNCHANGED) -> Next[Any]
```

Continue normally or pass a replacement to the next interceptor.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `replacement` | `Any` | `UNCHANGED` |
>
> ```python theme={null}
> from harnest.model import ModelLifecycleContext
>
> context: ModelLifecycleContext
> result = context.next()
> ```

### ModelLifecycleContext.finish

```python theme={null}
ModelLifecycleContext.finish(result: ResultT) -> Finish[ResultT]
```

Return a final value without advancing to later execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `result` | `ResultT` | Required |
>
> ```python theme={null}
> from harnest.model import ModelLifecycleContext
>
> context: ModelLifecycleContext
> result = context.finish(result=...)
> ```

## ModelLifecycleError

A portable model listener returned an invalid transformation.

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

## ModelMessage

One provider-independent text message in a model call.

```python theme={null}
ModelMessage(role: str, text: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `role` | `str` | `—` |
| `text` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `role` | `str` | Required |
> | `text` | `str` | Required |
>
> ```python theme={null}
> from harnest.model import ModelMessage
>
> message = ModelMessage(role=..., text=...)
> ```

## resolve\_model

Resolve a Harnest connector while preserving strings and ADK models.

```python theme={null}
resolve_model(model: ModelInput) -> Any
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `model` | `ModelInput` | Required |
>
> ```python theme={null}
> from harnest.model import resolve_model
>
> result = resolve_model(model=...)
> ```

## resolve\_model\_for

Resolve a connector for one compiler backend.

```python theme={null}
resolve_model_for(model: ModelInput, framework: str) -> Any
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `model` | `ModelInput` | Required |
> | `framework` | `str` | Required |
>
> ```python theme={null}
> from harnest.model import resolve_model_for
>
> result = resolve_model_for(model=..., framework=...)
> ```


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