yera 0.5.0

yera.models.context.llm

Module containing the LLM context infrastructure.

Consists of

  • the context var that contains the current llm context.
  • the llm context class itself.
  • the llm_context function gets the active llm context.

Symbols

class EmptyResponse — A stream produced no response tokens.
class EmptyStructResponse — A struct stream produced no response tokens.
def has_active_llm — Check whether there is an active llm.
def llm_context — Get the current active LLM context.
class LLMContext — Manages the currently-active LLM instance and its execution context.

EmptyResponse

Inherits: RuntimeError
Subclasses: EmptyStructResponse

A stream produced no response tokens.

EmptyStructResponse

Inherits: EmptyResponse

A struct stream produced no response tokens.

has_active_llm

has_active_llm() → bool

Check whether there is an active llm.

Returns

type: bool

true if there's an llm false if not

llm_context

llm_context() → LLMContext

Get the current active LLM context.

Returns

type: LLMContext

the active context.

LLMContext

Inherits: BaseModelContext

Manages the currently-active LLM instance and its execution context.

An LLM context encapsulates the interface to an LLM provider and provides access to the app workspace where message history and variables are stored. It acts as a context manager for proper initialization and cleanup of the LLM interface during execution.

Attributes: interface: The LLM provider interface for sending prompts and receiving responses. app_meta: Metadata about the app context this LLM is executing within.

Methods

add_sys_line — Add a system message to the workspace and emit an event.
add_user_line — Add a user message to the workspace and emit an event.
add_assistant_line — Add an assistant message to the workspace.
add_tool_call_line — Record a tool call message in the workspace.
add_tool_result_line — Record a tool result message in the workspace.
insert — Insert string content as a user message.
gen — Generate an LLM prose response (not structured gen).
struct_gen — Send a prompt to the LLM and return a structured response.
insert_result — Insert a tool result into the active conversation.
__enter__ — Enter the context manager and initialize the LLM interface.
__exit__ — Exit the context manager and clean up the LLM interface.

LLMContext.add_sys_line

add_sys_line(
    content: str,
) → None

Add a system message to the workspace and emit an event.

Parameters

content
type: str

The system message content.

LLMContext.add_user_line

add_user_line(
    content: str,
) → None

Add a user message to the workspace and emit an event.

Parameters

content
type: str

The user message content.

LLMContext.add_assistant_line

add_assistant_line(
    content: str,
    thinking: str | None = None,
    on_wire: bool = True,
    provider_data: list[dict[str, object]] | None = None,
) → None

Add an assistant message to the workspace.

Parameters

content
type: str

The assistant message content.

thinking
type: str | None = None

The assistant's thinking trace content (optional).

on_wire
type: bool = True

whether the assistant line should be included in the model context.

provider_data
type: list[dict[str, object]] | None = None

Opaque provider state required for later requests.

LLMContext.add_tool_call_line

add_tool_call_line(
    content: str,
    tool_id: str,
    call_id: str,
    tool_schema: dict,
    provider_data: list[dict[str, object]] | None = None,
) → None

Record a tool call message in the workspace.

Parameters

content
type: str

JSON string containing the tool arguments.

tool_id
type: str

Name of the invoked tool.

call_id
type: str

Unique identifier for this invocation.

tool_schema
type: dict

JSON schema describing the tool input.

provider_data
type: list[dict[str, object]] | None = None

Opaque provider state required for later requests.

LLMContext.add_tool_result_line

add_tool_result_line(
    content: str,
    tool_id: str,
    call_id: str,
    tool_schema: dict,
) → None

Record a tool result message in the workspace.

Parameters

content
type: str

JSON string of the tool's result/output.

tool_id
type: str

Name of the invoked tool (model class name).

call_id
type: str

Unique ID matching the original tool call.

tool_schema
type: dict

Full JSON schema used for validation (same as in add_tool_call_line).

LLMContext.insert

insert(
    content: str,
) → None

Insert string content as a user message.

LLMContext.gen

gen(
    instruction: str | None = None,
    on_wire: bool = True,
    **kwargs,
) → str

Generate an LLM prose response (not structured gen).

Parameters

instruction
type: str | None = None

additional instruction to condition the LLM's generation.

on_wire
type: bool = True

whether the generated response is to be kept in the model context.

**kwargs
type: str | int | float | bool

keyword args to be passed down to the LLM invocation.

Returns

type: str

the generated LLM response.

LLMContext.struct_gen

struct_gen(
    instruction: str | None = None,
    on_wire: bool = False,
    **kwargs,
) → TStruct

Send a prompt to the LLM and return a structured response.

Adds the user prompt to the workspace, requests a structured response from the LLM interface, parses the JSON response, and records it in the workspace.

Parameters

cls
type: type[TStruct]

The Pydantic model class to parse the structured response into.

instruction
type: str | None = None

additional instruction to condition the LLM's generation.

on_wire
type: bool = False

whether the generated response is to be kept in the model context.

**kwargs
type: str | float | int

Additional arguments to pass to the LLM interface.

Returns

type: TStruct

An instance of cls populated with the LLM response data.

LLMContext.insert_result

insert_result(
    result: object,
) → None

Insert a tool result into the active conversation.

Structured values are converted to transport-safe JSON using Yera's serialization infrastructure. String results remain plain text so they can be inserted without JSON quoting.

Parameters

result
type: object

Tool result to add to the model context.

Raises

TypeError

If the result contains a value unsupported by Yera's typing infrastructure.

ValueError

If a supported value cannot be serialized.

LLMContext.__enter__

__enter__()

Enter the context manager and initialize the LLM interface.

Captures the current app metadata, sets up the workspace, and initializes the LLM interface.

Returns

This context instance.

LLMContext.__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
)

Exit the context manager and clean up the LLM interface.

Parameters

exc_type
type: type[BaseException] | None

The exception type if an error occurred, else None.

exc_val
type: BaseException | None

The exception value if an error occurred, else None.

exc_tb
type: TracebackType | None

The exception traceback if an error occurred, else None.

Submodules

markdown
spinner
struct
system_prompt
thinking