harnest.model

All Python modules · Import and compatibility guidance

Exports

Name	Kind
`LiteLLMContext`	Class
`LiteLLMLifecycle`	Class
`LiteLLMModel`	Class
`ModelCallRequest`	Class
`ModelCallResponse`	Class
`ModelConnector`	Class
`ModelLifecycleContext`	Class
`ModelLifecycleError`	Class
`ModelMessage`	Class
`resolve_model`	Function
`resolve_model_for`	Function

LiteLLMContext

Stable call context provided to every LiteLLM lifecycle hook.

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`

Parameters and example

Parameter	Type	Default
`model`	`str`	Required
`framework`	`Literal['adk', 'langgraph']`	Required
`transport`	`Any \| None`	`None`

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.

LiteLLMLifecycle()

Example

from harnest.model import LiteLLMLifecycle

lifecycle = LiteLLMLifecycle()

LiteLLMLifecycle.create_transport

LiteLLMLifecycle.create_transport(context: LiteLLMContext) -> LifecycleValue

Return a provider client accepted by LiteLLM’s client option.

Parameters and example

Parameter	Type	Default
`context`	`LiteLLMContext`	Required

from harnest.model import LiteLLMLifecycle

lifecycle: LiteLLMLifecycle
result = lifecycle.create_transport(context=...)

LiteLLMLifecycle.before_request

LiteLLMLifecycle.before_request(request: dict[str, Any], context: LiteLLMContext) -> LifecycleValue

Mutate request or return its replacement before LiteLLM runs.

Parameters and example

Parameter	Type	Default
`request`	`dict[str, Any]`	Required
`context`	`LiteLLMContext`	Required

from harnest.model import LiteLLMLifecycle

lifecycle: LiteLLMLifecycle
result = lifecycle.before_request(request=..., context=...)

LiteLLMLifecycle.after_response

LiteLLMLifecycle.after_response(response: Any, context: LiteLLMContext) -> LifecycleValue

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

Parameters and example

Parameter	Type	Default
`response`	`Any`	Required
`context`	`LiteLLMContext`	Required

from harnest.model import LiteLLMLifecycle

lifecycle: LiteLLMLifecycle
result = lifecycle.after_response(response=..., context=...)

LiteLLMLifecycle.on_error

LiteLLMLifecycle.on_error(error: BaseException, context: LiteLLMContext) -> LifecycleValue

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

Parameters and example

Parameter	Type	Default
`error`	`BaseException`	Required
`context`	`LiteLLMContext`	Required

from harnest.model import LiteLLMLifecycle

lifecycle: LiteLLMLifecycle
result = lifecycle.on_error(error=..., context=...)

LiteLLMLifecycle.close

LiteLLMLifecycle.close(context: LiteLLMContext) -> LifecycleValue

Release resources created for this model instance.

Parameters and example

Parameter	Type	Default
`context`	`LiteLLMContext`	Required

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.

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`

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`.

from harnest.model import LiteLLMModel

model = LiteLLMModel("openai/your-model", api_base="https://models.example.invalid/v1")

LiteLLMModel.build

LiteLLMModel.build() -> Any

Build ADK’s LiteLlm without contacting the provider.

Example

from harnest.model import LiteLLMModel

model: LiteLLMModel
result = model.build()

LiteLLMModel.build_for

LiteLLMModel.build_for(framework: str) -> Any

Build the connector for a supported Harnest framework.

Parameters and example

Parameter	Type	Default	Description
`framework`	`str`	Required	`"adk"` or `"langgraph"`.

from harnest.model import LiteLLMModel

model: LiteLLMModel
result = model.build_for(framework=...)

LiteLLMModel.build_langgraph

LiteLLMModel.build_langgraph() -> Any

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

Example

from harnest.model import LiteLLMModel

model: LiteLLMModel
result = model.build_langgraph()

LiteLLMModel.from_openai_environment

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.

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.

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.

ModelCallRequest(model: str | None, messages: tuple[ModelMessage, ...]) -> None

Fields (— means no declared default):

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

Parameters and example

Parameter	Type	Default
`model`	`str \| None`	Required
`messages`	`tuple[ModelMessage, ...]`	Required

from harnest.model import ModelCallRequest

request = ModelCallRequest(model=..., messages=...)

ModelCallResponse

Portable visible model output.

ModelCallResponse(text: str) -> None

Fields (— means no declared default):

Field	Type	Default
`text`	`str`	`—`

Parameters and example

Parameter	Type	Default
`text`	`str`	Required

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.

ModelConnector()

Example

from harnest.model import ModelConnector

class MyModelConnector(ModelConnector):
    ...

ModelConnector.build

ModelConnector.build() -> Any

Build the model object accepted by ADK’s LlmAgent.

Example

from harnest.model import ModelConnector

connector: ModelConnector
result = connector.build()

ModelConnector.build_for

ModelConnector.build_for(framework: str) -> Any

Build the connector for a supported Harnest framework.

Parameters and example

Parameter	Type	Default
`framework`	`str`	Required

from harnest.model import ModelConnector

connector: ModelConnector
result = connector.build_for(framework=...)

ModelConnector.build_langgraph

ModelConnector.build_langgraph() -> Any

Build a LangChain chat model for LangGraph.

Example

from harnest.model import ModelConnector

connector: ModelConnector
result = connector.build_langgraph()

ModelLifecycleContext

Stable provider-neutral facts associated with one model call.

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`

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`

from harnest.model import ModelLifecycleContext

context = ModelLifecycleContext(framework=...)

ModelLifecycleContext.next

ModelLifecycleContext.next(replacement: Any = UNCHANGED) -> Next[Any]

Continue normally or pass a replacement to the next interceptor.

Parameters and example

Parameter	Type	Default
`replacement`	`Any`	`UNCHANGED`

from harnest.model import ModelLifecycleContext

context: ModelLifecycleContext
result = context.next()

ModelLifecycleContext.finish

ModelLifecycleContext.finish(result: ResultT) -> Finish[ResultT]

Return a final value without advancing to later execution.

Parameters and example

Parameter	Type	Default
`result`	`ResultT`	Required

from harnest.model import ModelLifecycleContext

context: ModelLifecycleContext
result = context.finish(result=...)

ModelLifecycleError

A portable model listener returned an invalid transformation.

Example

from harnest.model import ModelLifecycleError

try:
    ...
except ModelLifecycleError as error:
    ...

ModelMessage

One provider-independent text message in a model call.

ModelMessage(role: str, text: str) -> None

Fields (— means no declared default):

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

Parameters and example

Parameter	Type	Default
`role`	`str`	Required
`text`	`str`	Required

from harnest.model import ModelMessage

message = ModelMessage(role=..., text=...)

resolve_model

Resolve a Harnest connector while preserving strings and ADK models.

resolve_model(model: ModelInput) -> Any

Parameters and example

Parameter	Type	Default
`model`	`ModelInput`	Required

from harnest.model import resolve_model

result = resolve_model(model=...)

resolve_model_for

Resolve a connector for one compiler backend.

resolve_model_for(model: ModelInput, framework: str) -> Any

Parameters and example

Parameter	Type	Default
`model`	`ModelInput`	Required
`framework`	`str`	Required

from harnest.model import resolve_model_for

result = resolve_model_for(model=..., framework=...)

Overview

Get started

Harnest Studio

Guides

API reference

harnest.model

Exports

LiteLLMContext

LiteLLMLifecycle

LiteLLMLifecycle.create_transport

LiteLLMLifecycle.before_request

LiteLLMLifecycle.after_response

LiteLLMLifecycle.on_error

LiteLLMLifecycle.close

LiteLLMModel

LiteLLMModel.build

LiteLLMModel.build_for

LiteLLMModel.build_langgraph

LiteLLMModel.from_openai_environment

ModelCallRequest

ModelCallResponse

ModelConnector

ModelConnector.build

ModelConnector.build_for

ModelConnector.build_langgraph

ModelLifecycleContext

ModelLifecycleContext.next

ModelLifecycleContext.finish

ModelLifecycleError

ModelMessage

resolve_model

resolve_model_for

​Exports

​LiteLLMContext

​LiteLLMLifecycle

​LiteLLMLifecycle.create_transport

​LiteLLMLifecycle.before_request

​LiteLLMLifecycle.after_response

​LiteLLMLifecycle.on_error

​LiteLLMLifecycle.close

​LiteLLMModel

​LiteLLMModel.build

​LiteLLMModel.build_for

​LiteLLMModel.build_langgraph

​LiteLLMModel.from_openai_environment

​ModelCallRequest

​ModelCallResponse

​ModelConnector

​ModelConnector.build

​ModelConnector.build_for

​ModelConnector.build_langgraph

​ModelLifecycleContext

​ModelLifecycleContext.next

​ModelLifecycleContext.finish

​ModelLifecycleError

​ModelMessage

​resolve_model

​resolve_model_for

Exports

LiteLLMContext

LiteLLMLifecycle

LiteLLMLifecycle.create_transport

LiteLLMLifecycle.before_request

LiteLLMLifecycle.after_response

LiteLLMLifecycle.on_error

LiteLLMLifecycle.close

LiteLLMModel

LiteLLMModel.build

LiteLLMModel.build_for

LiteLLMModel.build_langgraph

LiteLLMModel.from_openai_environment

ModelCallRequest

ModelCallResponse

ModelConnector

ModelConnector.build

ModelConnector.build_for

ModelConnector.build_langgraph

ModelLifecycleContext

ModelLifecycleContext.next

ModelLifecycleContext.finish

ModelLifecycleError

ModelMessage

resolve_model

resolve_model_for