agentplane-primitives 0.1.0__py3-none-any.whl

agentplane_primitives/__init__.py

@@ -0,0 +1,10 @@
+"""AgentPlane primitives: shared, versioned domain objects.
+
+Used by Chronicle, the control plane and TokenOps. This package holds data models only:
+no I/O and no business logic. The entities (Trace, Span, Envelope) are
+added in later releases; see ``docs/design.md``.
+"""
+
+from agentplane_primitives._version import __version__
+
+__all__ = ["__version__"]

agentplane_primitives/_version.py

@@ -0,0 +1,3 @@
+"""Single source of the package version (read by the build backend and at runtime)."""
+
+__version__ = "0.1.0"

agentplane_primitives/enums/__init__.py

@@ -0,0 +1,25 @@
+"""Closed sets of values shared by the entities (design section 2.9).
+
+Each enum has its own module. A new member of any enum is a schema change: see
+``docs/versioning.md``.
+"""
+
+from agentplane_primitives.enums.base_enum import BaseEnum
+from agentplane_primitives.enums.finish_reason import FinishReason
+from agentplane_primitives.enums.kind import Kind
+from agentplane_primitives.enums.link_type import LinkType
+from agentplane_primitives.enums.message_role import MessageRole
+from agentplane_primitives.enums.model_source import ModelSource
+from agentplane_primitives.enums.state import State
+from agentplane_primitives.enums.status import Status
+
+__all__ = [
+    "BaseEnum",
+    "FinishReason",
+    "Kind",
+    "LinkType",
+    "MessageRole",
+    "ModelSource",
+    "State",
+    "Status",
+]

agentplane_primitives/enums/base_enum.py

@@ -0,0 +1,15 @@
+"""``BaseEnum``: the parent of every closed enum in this package.
+
+Members are strings, and ``str()`` and f-strings give the value (``"llm"``), not the member name
+(``"Kind.LLM"``), on every supported Python version. ``enum.StrEnum`` would do this but needs
+Python 3.11; this package supports 3.10.
+"""
+
+from enum import Enum
+
+
+class BaseEnum(str, Enum):
+    """A string enum whose text form is its value."""
+
+    def __str__(self) -> str:
+        return str(self.value)

agentplane_primitives/enums/finish_reason.py

@@ -0,0 +1,17 @@
+"""``FinishReason``: why an LLM call stopped (design section 2.9).
+
+Closed enum of the canonical set. The provider's own original value stays in ``output.raw``, so
+nothing is lost when a provider value is mapped onto one of these.
+"""
+
+from agentplane_primitives.enums.base_enum import BaseEnum
+
+
+class FinishReason(BaseEnum):
+    """The canonical reason an LLM response ended."""
+
+    STOP = "stop"
+    LENGTH = "length"
+    TOOL_CALLS = "tool_calls"
+    CONTENT_FILTER = "content_filter"
+    OTHER = "other"

agentplane_primitives/enums/kind.py

@@ -0,0 +1,14 @@
+"""``Kind``: what an envelope records (design sections 2.3 and 2.9).
+
+Closed enum: there are no custom or unregistered kinds, and any other value is rejected at
+validation. A new kind is a schema change (see ``docs/versioning.md`` and ADR 0002).
+"""
+
+from agentplane_primitives.enums.base_enum import BaseEnum
+
+
+class Kind(BaseEnum):
+    """The kind of boundary crossing an envelope records. It selects the input and output shape."""
+
+    LLM = "llm"
+    TOOL = "tool"

agentplane_primitives/enums/link_type.py

@@ -0,0 +1,12 @@
+"""``LinkType``: how one envelope relates to another besides parent and child (design 2.5).
+
+Closed enum for now. ``joined`` (fan-in) is reserved for future scope and is not a member yet.
+"""
+
+from agentplane_primitives.enums.base_enum import BaseEnum
+
+
+class LinkType(BaseEnum):
+    """The relationship a link expresses."""
+
+    RETRY_OF = "retry_of"

agentplane_primitives/enums/message_role.py

@@ -0,0 +1,12 @@
+"""``MessageRole``: who a message in an LLM input is from (design section 2.9). Closed enum."""
+
+from agentplane_primitives.enums.base_enum import BaseEnum
+
+
+class MessageRole(BaseEnum):
+    """The author of a message."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"

agentplane_primitives/enums/model_source.py

@@ -0,0 +1,17 @@
+"""``ModelSource``: where ``output.model`` came from (design sections 2.3 and 2.9).
+
+Closed enum. Some SDKs do not return the served model; then the adapter copies the requested one
+and says so here, so a consumer knows how much to trust it.
+"""
+
+from agentplane_primitives.enums.base_enum import BaseEnum
+
+
+class ModelSource(BaseEnum):
+    """How the model name in the output was obtained."""
+
+    SERVED = "served"
+    """The response named the model that served the call."""
+
+    REQUESTED = "requested"
+    """The response had no model; the adapter copied the requested one."""

agentplane_primitives/enums/state.py

@@ -0,0 +1,13 @@
+"""``State``: where a Trace, Span or Envelope is in its lifecycle (design section 2.4).
+
+Closed enum. A record is mutable while open and immutable once closed.
+"""
+
+from agentplane_primitives.enums.base_enum import BaseEnum
+
+
+class State(BaseEnum):
+    """Lifecycle state shared by Trace, Span and Envelope."""
+
+    OPEN = "open"
+    CLOSED = "closed"

agentplane_primitives/enums/status.py

@@ -0,0 +1,14 @@
+"""``Status``: the result of a Span or Envelope (design sections 2.2 and 2.9).
+
+Closed enum. A Trace has no status of its own. There is no ``aborted`` value: a deliberate abort
+is a ``failure`` whose ``output.error.type`` is ``AbortCall``.
+"""
+
+from agentplane_primitives.enums.base_enum import BaseEnum
+
+
+class Status(BaseEnum):
+    """High-level result of a Span or Envelope."""
+
+    SUCCESS = "success"
+    FAILURE = "failure"

agentplane_primitives/models/__init__.py

@@ -0,0 +1,46 @@
+"""The models: Trace, Span, Envelope with its parts, the TraceContext carrier, the base class."""
+
+from agentplane_primitives.models.base import PrimitiveModel
+from agentplane_primitives.models.content_block import ContentBlock
+from agentplane_primitives.models.envelope import Envelope
+from agentplane_primitives.models.envelope_status import EnvelopeStatus
+from agentplane_primitives.models.link import Link
+from agentplane_primitives.models.llm_input import LlmInput
+from agentplane_primitives.models.llm_output import LlmOutput
+from agentplane_primitives.models.llm_params import LlmParams
+from agentplane_primitives.models.message import Message
+from agentplane_primitives.models.output_error import ABORT_CALL, OutputError
+from agentplane_primitives.models.reasoning_block import ReasoningBlock
+from agentplane_primitives.models.refusal_block import RefusalBlock
+from agentplane_primitives.models.span import Span
+from agentplane_primitives.models.text_block import TextBlock
+from agentplane_primitives.models.tool_call_block import ToolCallBlock
+from agentplane_primitives.models.tool_input import ToolInput
+from agentplane_primitives.models.tool_output import ToolOutput
+from agentplane_primitives.models.trace import Trace
+from agentplane_primitives.models.trace_context import TraceContext
+from agentplane_primitives.models.usage import Usage
+
+__all__ = [
+    "ABORT_CALL",
+    "ContentBlock",
+    "Envelope",
+    "EnvelopeStatus",
+    "Link",
+    "LlmInput",
+    "LlmOutput",
+    "LlmParams",
+    "Message",
+    "OutputError",
+    "PrimitiveModel",
+    "ReasoningBlock",
+    "RefusalBlock",
+    "Span",
+    "TextBlock",
+    "ToolCallBlock",
+    "ToolInput",
+    "ToolOutput",
+    "Trace",
+    "TraceContext",
+    "Usage",
+]

agentplane_primitives/models/base.py

@@ -0,0 +1,20 @@
+"""``PrimitiveModel``: the base class every model in this package inherits from.
+
+It holds the settings all models share, so they are decided once (design section 2.8).
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class PrimitiveModel(BaseModel):
+    """Shared model settings.
+
+    - Unknown fields are ignored on read. This only matters when writer and reader run
+      different versions (for example during a rolling upgrade); the control plane keeps the
+      full original payload, so nothing is lost.
+    - Assigning a bad value to a field is validated, not silently accepted. Changing a
+      container in place (for example ``model.metadata[key] = value``) is not checked: Python
+      gives pydantic no hook for it, so such rules hold when the model is built or assigned.
+    """
+
+    model_config = ConfigDict(extra="ignore", validate_assignment=True)

agentplane_primitives/models/content_block.py

@@ -0,0 +1,19 @@
+"""``ContentBlock``: one piece of LLM content (design sections 2.3 and 2.9).
+
+A closed set chosen by ``type``: ``text``, ``tool_call``, ``reasoning`` or ``refusal``. Any other
+``type`` is rejected. Each block has its own module.
+"""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from agentplane_primitives.models.reasoning_block import ReasoningBlock
+from agentplane_primitives.models.refusal_block import RefusalBlock
+from agentplane_primitives.models.text_block import TextBlock
+from agentplane_primitives.models.tool_call_block import ToolCallBlock
+
+ContentBlock = Annotated[
+    TextBlock | ToolCallBlock | ReasoningBlock | RefusalBlock,
+    Field(discriminator="type"),
+]

agentplane_primitives/models/envelope.py

@@ -0,0 +1,94 @@
+"""``Envelope``: one boundary crossing, as a single record (design sections 2.2 to 2.5).
+
+The fields fall into the five sections of the design. The identity fields sit at the top level,
+as in the design's example payloads; the other four sections are nested:
+
+- identity: ``envelope_id``, ``span_id``, ``trace_id``, ``parent_envelope_id``, ``name``,
+  ``kind``, ``attempt``, ``links``
+- ``envelope_status``, ``input``, ``output`` and ``metadata``
+
+``kind`` selects the shape of ``input`` and ``output``: ``tool`` uses ``ToolInput`` and
+``ToolOutput``, ``llm`` uses ``LlmInput`` and ``LlmOutput``. A payload of the other kind's shape
+is rejected. An envelope is open until closed; a closed envelope must have an ``output`` (an
+error is recorded there).
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+from agentplane_primitives.enums import Kind, State
+from agentplane_primitives.models.base import PrimitiveModel
+from agentplane_primitives.models.envelope_status import EnvelopeStatus
+from agentplane_primitives.models.link import Link
+from agentplane_primitives.models.llm_input import LlmInput
+from agentplane_primitives.models.llm_output import LlmOutput
+from agentplane_primitives.models.tool_input import ToolInput
+from agentplane_primitives.models.tool_output import ToolOutput
+from agentplane_primitives.types import (
+    SCHEMA_VERSION,
+    EnvelopeId,
+    Metadata,
+    SchemaVersion,
+    SpanId,
+    TraceId,
+)
+
+_PAYLOADS: dict[Kind, tuple[type[BaseModel], type[BaseModel]]] = {
+    Kind.TOOL: (ToolInput, ToolOutput),
+    Kind.LLM: (LlmInput, LlmOutput),
+}
+
+
+class Envelope(PrimitiveModel):
+    """The record of one call across a boundary inside a span."""
+
+    schema_version: SchemaVersion = SCHEMA_VERSION
+
+    # identity
+    envelope_id: EnvelopeId
+    span_id: SpanId
+    trace_id: TraceId
+    parent_envelope_id: EnvelopeId | None = None
+    name: str = Field(min_length=1, description="Boundary name, e.g. agent.chat.")
+    kind: Kind
+    attempt: int = Field(default=1, ge=1, description="1 for the first try, 2 for a retry, ...")
+    links: list[Link] = Field(default_factory=list)
+
+    envelope_status: EnvelopeStatus
+    input: ToolInput | LlmInput = Field(description="Shape chosen by kind: tool or llm input.")
+    output: ToolOutput | LlmOutput | None = Field(
+        default=None, description="Shape chosen by kind: tool or llm output."
+    )
+    metadata: Metadata = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _read_payloads_by_kind(cls, data: Any) -> Any:
+        # The two payload shapes overlap when unknown fields are ignored, so the kind, not the
+        # shape, decides which model reads input and output.
+        if not isinstance(data, dict):
+            return data
+        try:
+            input_model, output_model = _PAYLOADS[Kind(data.get("kind"))]
+        except ValueError:
+            # Not swallowed: the ``kind`` field is validated next and rejects the value with its
+            # own error. This package does no I/O, so there is nothing to log.
+            return data
+        data = dict(data)
+        if isinstance(data.get("input"), dict):
+            data["input"] = input_model.model_validate(data["input"])
+        if isinstance(data.get("output"), dict):
+            data["output"] = output_model.model_validate(data["output"])
+        return data
+
+    @model_validator(mode="after")
+    def _check_consistency(self) -> "Envelope":
+        input_model, output_model = _PAYLOADS[self.kind]
+        if not isinstance(self.input, input_model):
+            raise ValueError(f"input does not match kind {self.kind.value!r}")
+        if self.output is not None and not isinstance(self.output, output_model):
+            raise ValueError(f"output does not match kind {self.kind.value!r}")
+        if self.envelope_status.state is State.CLOSED and self.output is None:
+            raise ValueError("a closed envelope needs an output")
+        return self

agentplane_primitives/models/envelope_status.py

@@ -0,0 +1,28 @@
+"""``EnvelopeStatus``: the lifecycle and result of an envelope (design sections 2.2 and 2.4).
+
+An envelope is one record that is mutable until it is closed. While ``open`` it has a start time
+and nothing else; once ``closed`` it has a result and an end time. To close an envelope, build a
+new ``EnvelopeStatus``: changing the fields one by one would pass through an invalid state.
+"""
+
+from pydantic import AwareDatetime, model_validator
+
+from agentplane_primitives.enums import State, Status
+from agentplane_primitives.models.base import PrimitiveModel
+from agentplane_primitives.utils.lifecycle_utils import validate_state_status_and_times
+
+
+class EnvelopeStatus(PrimitiveModel):
+    """State, result and timing of an envelope. Times must carry a time zone."""
+
+    state: State
+    status: Status | None = None
+    started_at: AwareDatetime
+    ended_at: AwareDatetime | None = None
+
+    @model_validator(mode="after")
+    def _validate_state_fields(self) -> "EnvelopeStatus":
+        validate_state_status_and_times(
+            self.state, self.status, self.started_at, self.ended_at, "envelope"
+        )
+        return self

agentplane_primitives/models/link.py

@@ -0,0 +1,16 @@
+"""``Link``: a typed pointer from one envelope to another (design section 2.5).
+
+Retries are declared explicitly: an envelope that retries an earlier one carries a ``retry_of``
+link to it. The linked envelope is in the same trace.
+"""
+
+from agentplane_primitives.enums import LinkType
+from agentplane_primitives.models.base import PrimitiveModel
+from agentplane_primitives.types import EnvelopeId
+
+
+class Link(PrimitiveModel):
+    """A relationship to another envelope in the same trace."""
+
+    type: LinkType
+    envelope_id: EnvelopeId

agentplane_primitives/models/llm_input.py

@@ -0,0 +1,33 @@
+"""``LlmInput``: the input of an ``llm`` envelope (design sections 2.3 and 2.9).
+
+Input is what the caller passed on this call: the requested model, the messages and the
+instructions, tool definitions and sampling settings. ``raw`` holds the arguments exactly as
+they were passed to the boundaried method, as JSON by argument name, and is always stored; the
+canonical fields are derived from it.
+
+``tools``, ``tool_choice`` and ``response_format`` are kept as JSON objects because their shape
+differs by provider. The design does not fix their structure.
+"""
+
+from pydantic import Field, JsonValue
+
+from agentplane_primitives.models.base import PrimitiveModel
+from agentplane_primitives.models.llm_params import LlmParams
+from agentplane_primitives.models.message import Message
+
+
+class LlmInput(PrimitiveModel):
+    """What was sent to the model."""
+
+    model: str = Field(min_length=1, description="The model or alias the caller asked for.")
+    messages: list[Message]
+    system: str | None = Field(default=None, description="Instructions the caller supplied.")
+    tools: list[dict[str, JsonValue]] | None = Field(
+        default=None, description="Tool definitions offered to the model."
+    )
+    tool_choice: JsonValue = Field(
+        default=None, description="Whether, or which, tool the model must use."
+    )
+    response_format: dict[str, JsonValue] | None = None
+    params: LlmParams = Field(default_factory=LlmParams)
+    raw: dict[str, JsonValue] = Field(description="Arguments as passed, by name, as JSON.")

agentplane_primitives/models/llm_output.py

@@ -0,0 +1,43 @@
+"""``LlmOutput``: the output of an ``llm`` envelope (design sections 2.3 and 2.9).
+
+Output is what is known only from the response. It carries the fixed homes for cost data, which a
+consumer such as TokenOps reads and nothing else:
+
+- ``provider``: who served the call (``unknown`` when it cannot be determined)
+- ``model`` and ``model_source``: what served it, and whether the response said so
+- ``usage``: exclusive, additive token buckets
+
+A call that failed has only ``error``; everything else is then absent. ``usage`` is null for a
+custom boundary with no adapter, and consumers must tolerate that. ``raw`` is the value returned
+by the boundaried method, as JSON, and is always stored.
+"""
+
+from pydantic import Field, JsonValue, model_validator
+
+from agentplane_primitives.enums import FinishReason, ModelSource
+from agentplane_primitives.models.base import PrimitiveModel
+from agentplane_primitives.models.content_block import ContentBlock
+from agentplane_primitives.models.output_error import OutputError
+from agentplane_primitives.models.usage import Usage
+from agentplane_primitives.types import UNKNOWN_PROVIDER, Provider
+
+
+class LlmOutput(PrimitiveModel):
+    """What came back from the model, or the error it raised."""
+
+    content: list[ContentBlock] = Field(default_factory=list)
+    finish_reason: FinishReason | None = None
+    provider: Provider = UNKNOWN_PROVIDER
+    model: str | None = Field(default=None, description="The model that served the call.")
+    model_source: ModelSource | None = None
+    usage: Usage | None = None
+    response_id: str | None = None
+    deployment_id: str | None = None
+    raw: JsonValue = Field(default=None, description="The returned value, as JSON.")
+    error: OutputError | None = None
+
+    @model_validator(mode="after")
+    def _model_and_source_go_together(self) -> "LlmOutput":
+        if (self.model is None) != (self.model_source is None):
+            raise ValueError("model and model_source must be given together")
+        return self

agentplane_primitives/models/llm_params.py

@@ -0,0 +1,19 @@
+"""``LlmParams``: the sampling settings the caller passed (design section 2.3).
+
+Every field is optional: only what the caller set is recorded. Defaults baked into a client's
+configuration are metadata, not input.
+"""
+
+from pydantic import Field
+
+from agentplane_primitives.models.base import PrimitiveModel
+
+
+class LlmParams(PrimitiveModel):
+    """Sampling parameters passed on this call."""
+
+    temperature: float | None = None
+    top_p: float | None = None
+    max_tokens: int | None = Field(default=None, ge=0)
+    seed: int | None = None
+    stop: list[str] | None = None

agentplane_primitives/models/message.py

@@ -0,0 +1,26 @@
+"""``Message``: one message in an LLM input (design sections 2.3 and 2.9).
+
+``content`` is plain text or a list of content blocks. A ``tool`` message (a tool result being
+handed back to the model) names the call it answers in ``tool_call_id``: the ``id`` of the
+``ToolCallBlock`` the model produced, copied from the provider's own id (OpenAI ``tool_call_id``,
+Anthropic ``tool_use_id``, Bedrock ``toolUseId``). Not every provider sends one, so it is
+optional, and it is not checked against earlier messages. Anthropic carries a tool result as a
+``tool_result`` block inside a user message; an adapter maps that to a ``tool`` message here. The
+provider's exact message shape is kept in ``input.raw``.
+"""
+
+from pydantic import Field
+
+from agentplane_primitives.enums import MessageRole
+from agentplane_primitives.models.base import PrimitiveModel
+from agentplane_primitives.models.content_block import ContentBlock
+
+
+class Message(PrimitiveModel):
+    """A single message with a role."""
+
+    role: MessageRole
+    content: str | list[ContentBlock]
+    tool_call_id: str | None = Field(
+        default=None, description="For role=tool: the id of the tool call this answers."
+    )

agentplane_primitives/models/output_error.py

@@ -0,0 +1,18 @@
+"""``OutputError``: how a failed call is described inside an output (design sections 2.3, 2.9).
+
+Error information belongs to ``output``, not to metadata. ``type`` is the exception class name; the
+reserved value ``"AbortCall"`` means a hook stopped the call on purpose.
+"""
+
+from pydantic import Field
+
+from agentplane_primitives.models.base import PrimitiveModel
+
+ABORT_CALL = "AbortCall"
+
+
+class OutputError(PrimitiveModel):
+    """An error raised by the call, recorded in ``output.error``."""
+
+    type: str = Field(min_length=1, description="Exception class name, e.g. RateLimitError.")
+    message: str = Field(description="The exception message.")

agentplane_primitives/models/reasoning_block.py

@@ -0,0 +1,12 @@
+"""``ReasoningBlock``: the model's visible reasoning text (design section 2.3)."""
+
+from typing import Literal
+
+from agentplane_primitives.models.base import PrimitiveModel
+
+
+class ReasoningBlock(PrimitiveModel):
+    """Reasoning content returned by the model."""
+
+    type: Literal["reasoning"] = "reasoning"
+    text: str

agentplane_primitives/models/refusal_block.py

@@ -0,0 +1,12 @@
+"""``RefusalBlock``: the model declining to answer (design section 2.3)."""
+
+from typing import Literal
+
+from agentplane_primitives.models.base import PrimitiveModel
+
+
+class RefusalBlock(PrimitiveModel):
+    """A refusal returned by the model."""
+
+    type: Literal["refusal"] = "refusal"
+    text: str

agentplane_primitives/models/registry.py

@@ -0,0 +1,15 @@
+"""``PUBLIC_MODELS``: the models that get a committed JSON Schema file.
+
+Add a model here in the same pull request that introduces it, then run
+``python scripts/generate_schemas.py`` and commit the new file. Helper models that only appear
+inside another model (such as ``Link`` inside ``Envelope``) do not need an entry: they are
+included in that model's schema.
+"""
+
+from pydantic import BaseModel
+
+from agentplane_primitives.models.envelope import Envelope
+from agentplane_primitives.models.span import Span
+from agentplane_primitives.models.trace import Trace
+
+PUBLIC_MODELS: tuple[type[BaseModel], ...] = (Trace, Span, Envelope)

agentplane_primitives/models/span.py

@@ -0,0 +1,48 @@
+"""``Span``: one service's handling of a request (design sections 2.1 and 2.2).
+
+A Span sits between the Trace and its Envelopes: one process, one agent run. It is minted by its
+own service, so ``span_id`` is unique within the trace. ``parent_envelope_id`` is the envelope in
+the caller's span that made the outbound call; it is the only link between services, and it is
+empty for the first span in a trace.
+
+``status`` is ``success`` or ``failure`` and is set when the span closes, by the entry point:
+``failure`` if the request handler raised, otherwise ``success``. It is independent of envelope
+failures (a retry that was handled does not fail the span). Like an envelope, a span is open until
+closed; to close one, build a new ``Span``, because the fields are validated together.
+"""
+
+from pydantic import AwareDatetime, Field, model_validator
+
+from agentplane_primitives.enums import State, Status
+from agentplane_primitives.models.base import PrimitiveModel
+from agentplane_primitives.types import (
+    SCHEMA_VERSION,
+    EnvelopeId,
+    Metadata,
+    SchemaVersion,
+    SpanId,
+    TraceId,
+)
+from agentplane_primitives.utils.lifecycle_utils import validate_state_status_and_times
+
+
+class Span(PrimitiveModel):
+    """One service's handling of a request inside a trace. Times must carry a time zone."""
+
+    schema_version: SchemaVersion = SCHEMA_VERSION
+    span_id: SpanId
+    trace_id: TraceId
+    parent_envelope_id: EnvelopeId | None = None
+    service: str = Field(min_length=1, description="Service or agent name.")
+    state: State
+    status: Status | None = None
+    started_at: AwareDatetime
+    ended_at: AwareDatetime | None = None
+    metadata: Metadata = Field(default_factory=dict, description="Span-level setup.")
+
+    @model_validator(mode="after")
+    def _validate_state_fields(self) -> "Span":
+        validate_state_status_and_times(
+            self.state, self.status, self.started_at, self.ended_at, "span"
+        )
+        return self

agentplane_primitives/models/text_block.py

@@ -0,0 +1,12 @@
+"""``TextBlock``: plain text produced or sent in an LLM call (design section 2.3)."""
+
+from typing import Literal
+
+from agentplane_primitives.models.base import PrimitiveModel
+
+
+class TextBlock(PrimitiveModel):
+    """A piece of text."""
+
+    type: Literal["text"] = "text"
+    text: str