jeevesagent.core.types
======================

.. py:module:: jeevesagent.core.types

.. autoapi-nested-parse::

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

.. autoapisummary::

   jeevesagent.core.types.AuditEntry
   jeevesagent.core.types.BudgetStatus
   jeevesagent.core.types.CertifiedValue
   jeevesagent.core.types.Episode
   jeevesagent.core.types.Event
   jeevesagent.core.types.EventKind
   jeevesagent.core.types.Fact
   jeevesagent.core.types.MemoryBlock
   jeevesagent.core.types.MemoryExport
   jeevesagent.core.types.MemoryProfile
   jeevesagent.core.types.Message
   jeevesagent.core.types.ModelChunk
   jeevesagent.core.types.PermissionDecision
   jeevesagent.core.types.Role
   jeevesagent.core.types.RunResult
   jeevesagent.core.types.Span
   jeevesagent.core.types.ToolCall
   jeevesagent.core.types.ToolDef
   jeevesagent.core.types.ToolEvent
   jeevesagent.core.types.ToolResult
   jeevesagent.core.types.Usage


Module Contents
---------------

.. py:class:: AuditEntry(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   An immutable, signed entry in the audit log.

   ``user_id`` (M9) is a top-level field for multi-tenant audit
   queries — `query(user_id="alice")` returns Alice's entries
   cleanly, no JSON-payload digging. Optional for back-compat
   with single-tenant deployments; populated automatically by the
   agent loop from the live :class:`~jeevesagent.RunContext`.

   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.


   .. py:attribute:: action
      :type:  str


   .. py:attribute:: actor
      :type:  str


   .. py:attribute:: model_config

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


   .. py:attribute:: payload
      :type:  dict[str, Any]


   .. py:attribute:: seq
      :type:  int


   .. py:attribute:: session_id
      :type:  str


   .. py:attribute:: signature
      :type:  str


   .. py:attribute:: timestamp
      :type:  datetime.datetime


   .. py:attribute:: user_id
      :type:  str | None
      :value: None



.. py:class:: BudgetStatus(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:method:: blocked_(reason: str) -> BudgetStatus
      :classmethod:



   .. py:method:: ok_() -> BudgetStatus
      :classmethod:



   .. py:method:: warn_(reason: str) -> BudgetStatus
      :classmethod:



   .. py:property:: blocked
      :type: bool



   .. py:attribute:: model_config

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


   .. py:attribute:: reason
      :type:  str | None
      :value: None



   .. py:attribute:: state
      :type:  Literal['ok', 'warn', 'blocked']


   .. py:property:: warn
      :type: bool



.. py:class:: CertifiedValue(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:attribute:: fetched_at
      :type:  datetime.datetime


   .. py:attribute:: lineage
      :type:  tuple[str, Ellipsis]
      :value: ()



   .. py:attribute:: model_config

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


   .. py:attribute:: schema_version
      :type:  str
      :value: '1'



   .. py:attribute:: source
      :type:  str


   .. py:attribute:: valid_until
      :type:  datetime.datetime | None
      :value: None



   .. py:attribute:: value
      :type:  Any


.. py:class:: Episode(/, **data: Any)

   Bases: :py:obj:`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 :class:`~jeevesagent.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.


   .. py:method:: format() -> str


   .. py:attribute:: embedding
      :type:  list[float] | None
      :value: None



   .. py:attribute:: id
      :type:  str
      :value: None



   .. py:attribute:: input
      :type:  str


   .. py:attribute:: occurred_at
      :type:  datetime.datetime
      :value: None



   .. py:attribute:: output
      :type:  str


   .. py:attribute:: session_id
      :type:  str


   .. py:attribute:: tool_calls
      :type:  list[ToolCall]
      :value: None



   .. py:attribute:: user_id
      :type:  str | None
      :value: None



.. py:class:: Event(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:method:: architecture_event(session_id: str, name: str, **data: Any) -> Event
      :classmethod:


      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.



   .. py:method:: budget_exceeded(session_id: str, status: BudgetStatus) -> Event
      :classmethod:



   .. py:method:: budget_warning(session_id: str, status: BudgetStatus) -> Event
      :classmethod:



   .. py:method:: completed(session_id: str, result: Any) -> Event
      :classmethod:



   .. py:method:: error(session_id: str, exc: BaseException) -> Event
      :classmethod:



   .. py:method:: model_chunk(session_id: str, chunk: ModelChunk) -> Event
      :classmethod:



   .. py:method:: started(session_id: str, prompt: str) -> Event
      :classmethod:



   .. py:method:: tool_call(session_id: str, call: ToolCall) -> Event
      :classmethod:



   .. py:method:: tool_result(session_id: str, result: ToolResult) -> Event
      :classmethod:



   .. py:attribute:: at
      :type:  datetime.datetime
      :value: None



   .. py:attribute:: kind
      :type:  EventKind


   .. py:attribute:: payload
      :type:  dict[str, Any]
      :value: None



   .. py:attribute:: session_id
      :type:  str


.. py:class:: EventKind

   Bases: :py:obj:`enum.StrEnum`


   Enum where members are also (and must be) strings

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


   .. py:attribute:: ARCHITECTURE_EVENT
      :value: '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 :class:`EventKind`.


   .. py:attribute:: BUDGET_EXCEEDED
      :value: 'budget_exceeded'



   .. py:attribute:: BUDGET_WARNING
      :value: 'budget_warning'



   .. py:attribute:: COMPLETED
      :value: 'completed'



   .. py:attribute:: ERROR
      :value: 'error'



   .. py:attribute:: MEMORY_RECALL
      :value: 'memory_recall'



   .. py:attribute:: MEMORY_WRITE
      :value: 'memory_write'



   .. py:attribute:: MODEL_CHUNK
      :value: 'model_chunk'



   .. py:attribute:: PERMISSION_ASK
      :value: 'permission_ask'



   .. py:attribute:: PERMISSION_DECISION
      :value: 'permission_decision'



   .. py:attribute:: STARTED
      :value: 'started'



   .. py:attribute:: TOOL_CALL
      :value: 'tool_call'



   .. py:attribute:: TOOL_RESULT
      :value: 'tool_result'



.. py:class:: Fact(/, **data: Any)

   Bases: :py:obj:`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
   :class:`~jeevesagent.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.


   .. py:method:: format() -> str


   .. py:attribute:: confidence
      :type:  float
      :value: 1.0



   .. py:attribute:: id
      :type:  str
      :value: None



   .. py:attribute:: object
      :type:  str


   .. py:attribute:: predicate
      :type:  str


   .. py:attribute:: recorded_at
      :type:  datetime.datetime
      :value: None



   .. py:attribute:: sources
      :type:  list[str]
      :value: None



   .. py:attribute:: subject
      :type:  str


   .. py:attribute:: user_id
      :type:  str | None
      :value: None



   .. py:attribute:: valid_from
      :type:  datetime.datetime
      :value: None



   .. py:attribute:: valid_until
      :type:  datetime.datetime | None
      :value: None



.. py:class:: MemoryBlock(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:method:: format() -> str


   .. py:attribute:: content
      :type:  str


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: pinned_order
      :type:  int
      :value: 0



   .. py:attribute:: updated_at
      :type:  datetime.datetime
      :value: None



.. py:class:: MemoryExport(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   Full data dump for a single user — GDPR / data-portability use.

   Returned by :meth:`Memory.export`. Carries the complete record of
   everything the memory holds for ``user_id``: all episodes, all
   facts, working blocks the user touched. Serialise with
   ``.model_dump_json()`` for download or downstream processing.

   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.


   .. py:attribute:: episodes
      :type:  list[Episode]
      :value: None



   .. py:attribute:: exported_at
      :type:  datetime.datetime
      :value: None



   .. py:attribute:: facts
      :type:  list[Fact]
      :value: None



   .. py:attribute:: user_id
      :type:  str | None


.. py:class:: MemoryProfile(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   Summary of what a :class:`Memory` knows about a single user.

   Returned by :meth:`Memory.profile`. Cheap aggregate counts +
   last-seen timestamp + the most-recent facts; suitable for
   rendering a "what does the bot know about me?" view to the
   end user, or a tenant dashboard for ops.

   Backends that don't track full episode counts (e.g. Redis without
   `FT.SEARCH` aggregations available) report what they can; the
   counts are best-effort, never wildly wrong.

   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.


   .. py:attribute:: episode_count
      :type:  int
      :value: 0



   .. py:attribute:: fact_count
      :type:  int
      :value: 0



   .. py:attribute:: last_seen
      :type:  datetime.datetime | None
      :value: None



   .. py:attribute:: recent_sessions
      :type:  list[str]
      :value: None


      Up to the 10 most-recent ``session_id``s touched, newest first.


   .. py:attribute:: sample_facts
      :type:  list[Fact]
      :value: None


      Up to 10 of the most-recently-recorded facts about the user.


   .. py:attribute:: user_id
      :type:  str | None


.. py:class:: Message(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:attribute:: content
      :type:  str


   .. py:attribute:: model_config

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


   .. py:attribute:: name
      :type:  str | None
      :value: None



   .. py:attribute:: role
      :type:  Role


   .. py:attribute:: tool_call_id
      :type:  str | None
      :value: None



   .. py:attribute:: tool_calls
      :type:  tuple[ToolCall, Ellipsis]
      :value: ()



.. py:class:: ModelChunk(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:attribute:: finish_reason
      :type:  str | None
      :value: None



   .. py:attribute:: kind
      :type:  Literal['text', 'tool_call', 'finish']


   .. py:attribute:: text
      :type:  str | None
      :value: None



   .. py:attribute:: tool_call
      :type:  ToolCall | None
      :value: None



   .. py:attribute:: usage
      :type:  Usage | None
      :value: None



.. py:class:: PermissionDecision(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:method:: allow_(reason: str | None = None) -> PermissionDecision
      :classmethod:



   .. py:method:: ask_(reason: str | None = None) -> PermissionDecision
      :classmethod:



   .. py:method:: deny_(reason: str) -> PermissionDecision
      :classmethod:



   .. py:property:: allow
      :type: bool



   .. py:property:: ask
      :type: bool



   .. py:attribute:: decision
      :type:  Literal['allow', 'deny', 'ask']


   .. py:property:: deny
      :type: bool



   .. py:attribute:: model_config

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


   .. py:attribute:: reason
      :type:  str | None
      :value: None



.. py:class:: Role

   Bases: :py:obj:`enum.StrEnum`


   Enum where members are also (and must be) strings

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


   .. py:attribute:: ASSISTANT
      :value: 'assistant'



   .. py:attribute:: SYSTEM
      :value: 'system'



   .. py:attribute:: TOOL
      :value: 'tool'



   .. py:attribute:: USER
      :value: 'user'



.. py:class:: RunResult(/, **data: Any)

   Bases: :py:obj:`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 :meth:`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.


   .. py:attribute:: cost_usd
      :type:  float
      :value: 0.0



   .. py:property:: duration
      :type: datetime.timedelta


      Wall-clock latency between ``started_at`` and ``finished_at``.


   .. py:attribute:: finished_at
      :type:  datetime.datetime


   .. py:attribute:: interrupted
      :type:  bool
      :value: False



   .. py:attribute:: interruption_reason
      :type:  str | None
      :value: None



   .. py:attribute:: model_config

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


   .. py:attribute:: output
      :type:  str


   .. py:attribute:: parsed
      :type:  Any | None
      :value: None


      The validated Pydantic instance when ``output_schema=`` was
      supplied to :meth:`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.


   .. py:attribute:: session_id
      :type:  str


   .. py:attribute:: started_at
      :type:  datetime.datetime


   .. py:attribute:: tokens_in
      :type:  int
      :value: 0



   .. py:attribute:: tokens_out
      :type:  int
      :value: 0



   .. py:property:: total_tokens
      :type: int


      ``tokens_in + tokens_out``.

      :type: Convenience


   .. py:attribute:: turns
      :type:  int


.. py:class:: Span(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:attribute:: attributes
      :type:  dict[str, Any]
      :value: None



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: span_id
      :type:  str


   .. py:attribute:: started_at
      :type:  datetime.datetime
      :value: None



   .. py:attribute:: trace_id
      :type:  str


.. py:class:: ToolCall(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:method:: idempotency_key() -> str


   .. py:method:: is_destructive() -> bool


   .. py:attribute:: args
      :type:  dict[str, Any]
      :value: None



   .. py:attribute:: destructive
      :type:  bool
      :value: False



   .. py:attribute:: id
      :type:  str
      :value: None



   .. py:attribute:: tool
      :type:  str


   .. py:attribute:: tool_def
      :type:  ToolDef | None
      :value: None



.. py:class:: ToolDef(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: input_schema
      :type:  dict[str, Any]
      :value: None



   .. py:attribute:: model_config

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


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: server
      :type:  str | None
      :value: None



.. py:class:: ToolEvent(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:attribute:: at
      :type:  datetime.datetime
      :value: None



   .. py:attribute:: kind
      :type:  Literal['added', 'removed', 'updated']


   .. py:attribute:: server
      :type:  str | None
      :value: None



   .. py:attribute:: tool
      :type:  str


.. py:class:: ToolResult(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:method:: denied_(call_id: str, reason: str, **kwargs: Any) -> ToolResult
      :classmethod:



   .. py:method:: error_(call_id: str, message: str, **kwargs: Any) -> ToolResult
      :classmethod:



   .. py:method:: success(call_id: str, output: Any, **kwargs: Any) -> ToolResult
      :classmethod:



   .. py:attribute:: call_id
      :type:  str


   .. py:attribute:: denied
      :type:  bool
      :value: False



   .. py:attribute:: duration_ms
      :type:  float | None
      :value: None



   .. py:attribute:: error
      :type:  str | None
      :value: None



   .. py:attribute:: ok
      :type:  bool


   .. py:attribute:: output
      :type:  Any
      :value: None



   .. py:attribute:: reason
      :type:  str | None
      :value: None



   .. py:attribute:: started_at
      :type:  datetime.datetime
      :value: None



.. py:class:: Usage(/, **data: Any)

   Bases: :py:obj:`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.


   .. py:attribute:: cost_usd
      :type:  float
      :value: 0.0



   .. py:attribute:: input_tokens
      :type:  int
      :value: 0



   .. py:attribute:: model_config

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


   .. py:attribute:: output_tokens
      :type:  int
      :value: 0



