jeevesagent.core.types

Pydantic types for messages, events, tools, memory, and runtime state.

These are the value objects that flow across module boundaries. They are immutable where possible, validated on construction, and free of behavior that requires I/O.

Classes

AuditEntry	An immutable, signed entry in the audit log.
BudgetStatus	Result of a budget check before each step.
CertifiedValue	A value carrying provenance metadata for freshness/lineage checks.
Episode	A single (input, decisions, tool calls, output) tuple from history.
Event	A single observable record from a running session.
EventKind	Enum where members are also (and must be) strings
Fact	A semantic claim extracted from one or more episodes.
MemoryBlock	An in-context memory block, pinned to every prompt.
Message	A single chat message in the model's conversation.
ModelChunk	A single chunk from a streaming model call.
PermissionDecision	Outcome of a permission check or pre-tool hook.
Role	Enum where members are also (and must be) strings
RunResult	Final outcome of an Agent.run call.
Span	A trace span handle. Concrete telemetry adapters return their own
ToolCall	A model-emitted request to invoke a tool.
ToolDef	Schema description of a tool the model can call.
ToolEvent	Tool registry change notification (MCP listChanged etc.).
ToolResult	Outcome of a tool invocation.
Usage	Token and cost accounting for a model call.

Module Contents

class jeevesagent.core.types.AuditEntry(/, **data: Any)

Bases: pydantic.BaseModel

An immutable, signed entry in the audit log.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

action: str

actor: str

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

payload: dict[str, Any]

seq: int

session_id: str

signature: str

timestamp: datetime.datetime

class jeevesagent.core.types.BudgetStatus(/, **data: Any)

Bases: pydantic.BaseModel

Result of a budget check before each step.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod blocked_(reason: str) → BudgetStatus

classmethod ok_() → BudgetStatus

classmethod warn_(reason: str) → BudgetStatus

property blocked: bool

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reason: str | None = None

state: Literal['ok', 'warn', 'blocked']

property warn: bool

class jeevesagent.core.types.CertifiedValue(/, **data: Any)

Bases: pydantic.BaseModel

A value carrying provenance metadata for freshness/lineage checks.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

fetched_at: datetime.datetime

lineage: tuple[str, Ellipsis] = ()

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

schema_version: str = '1'

source: str

valid_until: datetime.datetime | None = None

value: Any

class jeevesagent.core.types.Episode(/, **data: Any)

Bases: pydantic.BaseModel

A single (input, decisions, tool calls, output) tuple from history.

user_id is the framework-managed namespace partition. Episodes persisted with one user_id value are never visible to memory recall queries scoped to a different user_id. None is its own bucket — the “anonymous / single-tenant” namespace — and does not see episodes belonging to a non-None user_id (and vice versa). Set automatically from RunContext by the agent loop; pass explicitly when constructing episodes outside a run.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

format() → str

embedding: list[float] | None = None

id: str = None

input: str

occurred_at: datetime.datetime = None

output: str

session_id: str

tool_calls: list[ToolCall] = None

user_id: str | None = None

class jeevesagent.core.types.Event(/, **data: Any)

Bases: pydantic.BaseModel

A single observable record from a running session.

Carries a discriminator (kind) plus a free-form payload. Construct via the class methods to ensure consistent shapes.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod architecture_event(session_id: str, name: str, **data: Any) → Event

Generic architecture-progress event.

name is a namespaced string identifying the source architecture and the kind of progress (e.g. "self_refine.critique", "reflexion.lesson_persisted", "router.classified"). data is merged into the payload alongside name so consumers can pattern-match on name and read structured fields off the rest.

classmethod budget_exceeded(session_id: str, status: BudgetStatus) → Event

classmethod budget_warning(session_id: str, status: BudgetStatus) → Event

classmethod completed(session_id: str, result: Any) → Event

classmethod error(session_id: str, exc: BaseException) → Event

classmethod model_chunk(session_id: str, chunk: ModelChunk) → Event

classmethod started(session_id: str, prompt: str) → Event

classmethod tool_call(session_id: str, call: ToolCall) → Event

classmethod tool_result(session_id: str, result: ToolResult) → Event

at: datetime.datetime = None

kind: EventKind

payload: dict[str, Any] = None

session_id: str

class jeevesagent.core.types.EventKind

Bases: enum.StrEnum

Enum where members are also (and must be) strings

Initialize self. See help(type(self)) for accurate signature.

ARCHITECTURE_EVENT = 'architecture_event'

Generic architecture-progress event. Carries a namespaced name in the payload (e.g. "self_refine.critique", "reflexion.lesson_persisted", "router.classified") so each architecture can stream its own progress signal without expanding EventKind.

BUDGET_EXCEEDED = 'budget_exceeded'

BUDGET_WARNING = 'budget_warning'

COMPLETED = 'completed'

ERROR = 'error'

MEMORY_RECALL = 'memory_recall'

MEMORY_WRITE = 'memory_write'

MODEL_CHUNK = 'model_chunk'

PERMISSION_ASK = 'permission_ask'

PERMISSION_DECISION = 'permission_decision'

STARTED = 'started'

TOOL_CALL = 'tool_call'

TOOL_RESULT = 'tool_result'

class jeevesagent.core.types.Fact(/, **data: Any)

Bases: pydantic.BaseModel

A semantic claim extracted from one or more episodes.

Bi-temporal: valid_from/valid_until tracks when the fact was true in the world; recorded_at tracks when we learned it.

user_id is the framework-managed namespace partition. Facts persisted with one user_id value are never visible to recall queries scoped to a different user_id. Set automatically from RunContext by the agent loop / consolidator; pass explicitly when constructing facts outside a run.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

format() → str

confidence: float = 1.0

id: str = None

object: str

predicate: str

recorded_at: datetime.datetime = None

sources: list[str] = None

subject: str

user_id: str | None = None

valid_from: datetime.datetime = None

valid_until: datetime.datetime | None = None

class jeevesagent.core.types.MemoryBlock(/, **data: Any)

Bases: pydantic.BaseModel

An in-context memory block, pinned to every prompt.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

format() → str

content: str

name: str

pinned_order: int = 0

updated_at: datetime.datetime = None

class jeevesagent.core.types.Message(/, **data: Any)

Bases: pydantic.BaseModel

A single chat message in the model’s conversation.

tool_calls is populated on assistant messages that emitted tool calls in the previous turn — real provider adapters (Anthropic tool_use blocks, OpenAI tool_calls array) need to reconstruct the right wire format from this.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

content: str

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None = None

role: Role

tool_call_id: str | None = None

tool_calls: tuple[ToolCall, Ellipsis] = ()

class jeevesagent.core.types.ModelChunk(/, **data: Any)

Bases: pydantic.BaseModel

A single chunk from a streaming model call.

Discriminated by kind. Exactly one of the optional fields is set depending on the kind.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

finish_reason: str | None = None

kind: Literal['text', 'tool_call', 'finish']

text: str | None = None

tool_call: ToolCall | None = None

usage: Usage | None = None

class jeevesagent.core.types.PermissionDecision(/, **data: Any)

Bases: pydantic.BaseModel

Outcome of a permission check or pre-tool hook.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod allow_(reason: str | None = None) → PermissionDecision

classmethod ask_(reason: str | None = None) → PermissionDecision

classmethod deny_(reason: str) → PermissionDecision

property allow: bool

property ask: bool

decision: Literal['allow', 'deny', 'ask']

property deny: bool

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reason: str | None = None

class jeevesagent.core.types.Role

Bases: enum.StrEnum

Enum where members are also (and must be) strings

Initialize self. See help(type(self)) for accurate signature.

ASSISTANT = 'assistant'

SYSTEM = 'system'

TOOL = 'tool'

USER = 'user'

class jeevesagent.core.types.RunResult(/, **data: Any)

Bases: pydantic.BaseModel

Final outcome of an Agent.run call.

output is always the raw assistant text (the JSON itself when a structured-output schema was supplied). parsed is the validated Pydantic instance — populated only when the caller passed output_schema= to Agent.run(). Use whichever fits the call site:

# free-form text run
result = await agent.run("summarise this PDF")
print(result.output)

# structured-output run
result = await agent.run(prompt, output_schema=Invoice)
invoice: Invoice = result.parsed   # typed, validated

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

cost_usd: float = 0.0

property duration: datetime.timedelta

Wall-clock latency between started_at and finished_at.

finished_at: datetime.datetime

interrupted: bool = False

interruption_reason: str | None = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output: str

parsed: Any | None = None

The validated Pydantic instance when output_schema= was supplied to Agent.run(); None otherwise. Typed as Any to keep the runtime type free; the call site has the schema and can cast or annotate as needed.

session_id: str

started_at: datetime.datetime

tokens_in: int = 0

tokens_out: int = 0

property total_tokens: int

tokens_in + tokens_out.

Type:

Convenience

turns: int

class jeevesagent.core.types.Span(/, **data: Any)

Bases: pydantic.BaseModel

A trace span handle. Concrete telemetry adapters return their own representation; this is the value-object contract for in-process use.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

attributes: dict[str, Any] = None

name: str

span_id: str

started_at: datetime.datetime = None

trace_id: str

class jeevesagent.core.types.ToolCall(/, **data: Any)

Bases: pydantic.BaseModel

A model-emitted request to invoke a tool.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

idempotency_key() → str

is_destructive() → bool

args: dict[str, Any] = None

destructive: bool = False

id: str = None

tool: str

tool_def: ToolDef | None = None

class jeevesagent.core.types.ToolDef(/, **data: Any)

Bases: pydantic.BaseModel

Schema description of a tool the model can call.

Mirrors the JSON-Schema-flavored shape used across MCP and provider APIs.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

description: str

input_schema: dict[str, Any] = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

server: str | None = None

class jeevesagent.core.types.ToolEvent(/, **data: Any)

Bases: pydantic.BaseModel

Tool registry change notification (MCP listChanged etc.).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

at: datetime.datetime = None

kind: Literal['added', 'removed', 'updated']

server: str | None = None

tool: str

class jeevesagent.core.types.ToolResult(/, **data: Any)

Bases: pydantic.BaseModel

Outcome of a tool invocation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod denied_(call_id: str, reason: str, **kwargs: Any) → ToolResult

classmethod error_(call_id: str, message: str, **kwargs: Any) → ToolResult

classmethod success(call_id: str, output: Any, **kwargs: Any) → ToolResult

call_id: str

denied: bool = False

duration_ms: float | None = None

error: str | None = None

ok: bool

output: Any = None

reason: str | None = None

started_at: datetime.datetime = None

class jeevesagent.core.types.Usage(/, **data: Any)

Bases: pydantic.BaseModel

Token and cost accounting for a model call.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

cost_usd: float = 0.0

input_tokens: int = 0

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_tokens: int = 0