Models

Agent State

polymathera.colony.agents.models.AgentState

Bases: str, Enum

Agent lifecycle states.

Agent Metadata

polymathera.colony.agents.models.AgentMetadata

Bases: BaseModel

Metadata for agents.

from_data(*, caller=None, **kwargs) classmethod

Construct an :class:AgentMetadata from a payload sourced from outside the typed Python boundary — most commonly a JSON dict the LLM emitted at the REPL and spread via **.

Why this exists separately from AgentMetadata(**kwargs):

• The constructor's :meth:_reject_silently_dropped_context_kwargs validator loudly rejects any tenant_id / colony_id / session_id / run_id at the top level so typed Python code can't accidentally pass them (they're read-only @properties delegating to syscontext — the constructor would silently drop them otherwise, which masked real bugs).
• LLM-driven callers don't get that contract. The REPL serialises whatever the planner emits, and the planner will happily include tenant_id thinking it's a field. Failing the spawn with a pydantic ValueError on every such call is a worse failure mode than silently stripping the keys — the syscontext default_factory captures the parent's context, so the LLM's intent ("inherit tenant identity from the spawn site") is what actually happens anyway.

This helper bridges the two: strip the context keys with a WARN log naming the caller, then forward the cleaned payload through the typed constructor (which still enforces every other invariant).

Parameters:

Name	Type	Description	Default
caller	str | None	Free-form identifier (e.g. capability + action, spawn-site agent_id) included in the WARN log so the operator can locate the source of sloppy payloads. Falls back to "unspecified" when omitted.	None
**kwargs	Any	The dict payload (typically a **spread of the LLM-emitted metadata dict).	{}

Returns:

Type	Description
AgentMetadata	A typed :class:AgentMetadata. The returned instance's
AgentMetadata	tenant_id / colony_id / session_id /
AgentMetadata	run_id come from syscontext (constructor's
AgentMetadata	default_factory captures the active execution context),
AgentMetadata	NOT from the kwargs — even if the LLM passed them.

Source code in src/polymathera/colony/agents/models.py

@classmethod
def from_data(
    cls,
    *,
    caller: str | None = None,
    **kwargs: Any,
) -> AgentMetadata:
    """Construct an :class:`AgentMetadata` from a payload sourced
    from outside the typed Python boundary — most commonly a JSON
    dict the LLM emitted at the REPL and spread via ``**``.

    Why this exists separately from ``AgentMetadata(**kwargs)``:

    - The constructor's
      :meth:`_reject_silently_dropped_context_kwargs` validator
      loudly rejects any ``tenant_id`` / ``colony_id`` /
      ``session_id`` / ``run_id`` at the top level so typed
      Python code can't accidentally pass them (they're read-only
      @properties delegating to ``syscontext`` — the constructor
      would silently drop them otherwise, which masked real
      bugs).
    - LLM-driven callers don't get that contract. The REPL
      serialises whatever the planner emits, and the planner
      will happily include ``tenant_id`` thinking it's a field.
      Failing the spawn with a pydantic ``ValueError`` on every
      such call is a worse failure mode than silently stripping
      the keys — the syscontext default_factory captures the
      parent's context, so the LLM's intent ("inherit tenant
      identity from the spawn site") is what actually happens
      anyway.

    This helper bridges the two: strip the context keys with a
    WARN log naming the caller, then forward the cleaned payload
    through the typed constructor (which still enforces every
    other invariant).

    Args:
        caller: Free-form identifier (e.g. capability + action,
            spawn-site agent_id) included in the WARN log so the
            operator can locate the source of sloppy payloads.
            Falls back to "unspecified" when omitted.
        **kwargs: The dict payload (typically a ``**spread`` of
            the LLM-emitted metadata dict).

    Returns:
        A typed :class:`AgentMetadata`. The returned instance's
        ``tenant_id`` / ``colony_id`` / ``session_id`` /
        ``run_id`` come from ``syscontext`` (constructor's
        default_factory captures the active execution context),
        NOT from the kwargs — even if the LLM passed them.
    """

    stripped = [
        k for k in cls._CONTEXT_KWARG_NAMES if k in kwargs
    ]
    if stripped:
        cleaned: dict[str, Any] = {
            k: v for k, v in kwargs.items() if k not in stripped
        }
        logger.warning(
            "AgentMetadata.from_data: dropped read-only "
            "context keys %s from untrusted payload — these "
            "inherit from the active syscontext and cannot be "
            "set per-call. Caller=%s.",
            stripped, caller or "unspecified",
        )
    else:
        cleaned = kwargs
    return cls(**cleaned)

update(**kwargs)

Update metadata fields.

Source code in src/polymathera/colony/agents/models.py

def update(self, **kwargs) -> None:
    """Update metadata fields."""
    for key, value in kwargs.items():
        if hasattr(self, key):
            setattr(self, key, value)

Action Types

polymathera.colony.agents.models.ActionType

Bases: str, Enum

Types of actions agents can perform.