avp-cli 0.1.0__py3-none-any.whl

avp/descriptor.py

@@ -0,0 +1,204 @@
+"""avp.descriptor — Pydantic types for the AVP Agent Descriptor Spec.
+
+Defines `AgentDescriptor` (the agent's self-description shape) and the
+declaration types it carries: `ToolDecl`, `SubagentDecl`, `SkillDecl`,
+`McpServerDecl`. This module mirrors the
+[Agent Descriptor spec](../../../../spec/v0.1/agent-descriptor.md).
+
+Implementors building an `agent_described` event construct
+`AgentDescriptor` with typed decl lists:
+
+    from avp.descriptor import AgentDescriptor, ToolDecl
+
+    AgentDescriptor(
+        agent_name="my-agent",
+        agent_version="1.0.0",
+        spec_version="0.1",
+        tools=[ToolDecl(name="Read")],
+    )
+
+The decl types are also reused by `avp.trajectory` for events that share
+the same shape (`agent_started.data["avp.tools"]`,
+`agent_started.data["avp.mcp_servers"]`).
+
+This module is self-contained: importing from it does not drag in
+Trajectory / Commission / Resolver API types.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from avp.envelope import _OPEN, _STRICT
+
+
+class ToolDecl(BaseModel):
+    """Tool descriptor used by `AgentDescriptor.tools` and
+    `agent_started.data["avp.tools"]`.
+
+    MCP-shaped: `name` plus optional `description` and `inputSchema`. The
+    decl describes a single tool's model-facing identity. Dispatch is
+    discriminated by `avp.mcp_server_id`: when set, the tool is sourced
+    from the MCP server with that `id` in `mcp_servers[]`; when absent,
+    the tool runs locally in the agent's process. The per-invocation
+    discriminator `avp.tool.dispatch_target` on `tool_invoked` mirrors
+    presence of this field."""
+
+    model_config = _OPEN
+    name: str
+    description: str | None = None
+    inputSchema: dict[str, Any] | None = Field(default=None, alias="inputSchema")
+    mcp_server_id: str | None = Field(default=None, alias="avp.mcp_server_id")
+
+
+class SubagentDecl(BaseModel):
+    """Subagent descriptor in `agent_started.data["avp.subagents"]`: what the
+    parent model sees when deciding whether to delegate. Same MCP-shaped
+    triple (`name`, `description`, `inputSchema`) tools use, so adapters
+    can render subagents to the model's tool list with no translation.
+
+    `description` is optional to match `ToolDecl`: when surfacing a
+    agent-built-in subagent (e.g. the Claude Agent SDK's `general-purpose`)
+    the agent has authoritative knowledge of the name but not the prose
+    description. Honest-null beats authored-prose-that-drifts."""
+
+    model_config = _OPEN
+    name: str
+    description: str | None = None
+    inputSchema: dict[str, Any] | None = Field(default=None, alias="inputSchema")
+    agent_type: str | None = Field(default=None, alias="avp.agent_type")
+
+
+class SkillDecl(BaseModel):
+    """Skill descriptor in `AgentDescriptor.skills` and
+    `agent_started.data["avp.skills"]`: name plus optional metadata about each
+    skill the agent ships with or has loaded for the run.
+
+    Replaces the v0.1-prototype `list[str]` shape (names-only) with a
+    structured decl matching `ToolDecl` / `SubagentDecl`. Description
+    comes from the SKILL.md frontmatter when the agent surfaces it
+    (e.g. via `ClaudeSDKClient.get_context_usage()` which returns a
+    `skills` breakdown including frontmatter); `version` is the skill's
+    own version when known; `avp.source` is the SKILL.md path / URI.
+
+    All fields except `name` are optional so agents that only know
+    the name (Commission-declared without enrichment) still emit valid
+    decls."""
+
+    model_config = _OPEN
+    name: str
+    description: str | None = None
+    version: str | None = None
+    source: str | None = Field(default=None, alias="avp.source")
+
+
+class McpServerDecl(BaseModel):
+    """MCP server descriptor in `AgentDescriptor.mcp_servers` and
+    `agent_started.data["avp.mcp_servers"]`: identity + terminal dial status.
+
+    Connection material (URLs, auth, command-lines) stays inside the agent
+    process and is NOT carried on the descriptor wire. The descriptor
+    records the server's id, optional display name, optional description,
+    and the terminal dial status when known. The tools the server surfaces
+    are enumerated in the sibling `tools[]` list with `avp.mcp_server_id`
+    set to this server's `id`; only `status: "connected"` servers
+    contribute tools.
+
+    `id` is the agent's correlation key for this server across the wire
+    (descriptor entry, tool entry's `avp.mcp_server_id`). It is intentionally
+    looser than `Commission.McpServerRef.id`: the descriptor enumerates BOTH
+    Commission-resolved servers (where `id` is the supervisor-authored slug)
+    AND agent-baked-in / environment-resident servers (where `id` is whatever
+    the environment names them, e.g. `"claude.ai Dashboard Builder"`). Forcing
+    a slug here would either lose fidelity or require every agent to invent
+    the same slugification rule. Commission-authored ids stay slug-clean by
+    virtue of `Commission.McpServerRef.id`'s pattern; descriptor ids must
+    only be non-empty.
+
+    `name` is the display name when the environment provides one distinct
+    from `id` (typical for Commission-resolved servers: `id` is the
+    Commission slug, `name` is the human-readable label from the resolved
+    config). For environment-resident servers whose only identifier is
+    the display name, `id` carries that string and `name` is omitted.
+
+    `status` records the dial outcome at startup. Pre-flight `<agent> describe`
+    MAY omit it (no dial has happened); on-the-wire `agent_described` and
+    `agent_started` populate it. Values mirror the Claude Agent SDK's
+    `McpServerStatus.status` enum."""
+
+    model_config = _OPEN
+    id: str = Field(min_length=1)
+    name: str | None = None
+    description: str | None = None
+    status: Literal["connected", "failed", "needs-auth", "pending", "disabled"] | None = None
+
+
+class AgentDescriptor(BaseModel):
+    """Self-description of an AVP agent: the static surface it ships with.
+
+    Identity, capabilities, supported models, system prompt, baked-in user
+    prompt (for autonomous agents), MCP servers, tools, skills, subagents.
+    Provenance inside the agent doesn't matter on the wire: an SDK preset
+    tool (`Grep`), a runtime-bundled skill, and a hand-coded tool are all
+    just "what's in the agent" to a Descriptor consumer.
+
+    Two views, normatively consistent:
+
+      1. **Pre-flight**: `<agent> describe` prints the Descriptor as JSON.
+      2. **On the wire**: `agent_described.data["avp.descriptor"]` carries
+         the same payload during a run.
+
+    The pre-flight view MAY omit MCP-surfaced `tools[]` entries (those
+    whose `avp.mcp_server_id` is set) and per-server `mcp_servers[].status`,
+    since both require the agent to dial its MCP servers and run
+    `tools/list` — work the agent only needs to do at run-time. Every
+    other field MUST be identical between the two views.
+
+    Anything that varies per invocation (per-call prompt, run_id, thread_id,
+    additional supervisor-managed assets) belongs on the Commission, not
+    here.
+    """
+
+    model_config = _STRICT
+    agent_name: str = Field(min_length=1)
+    agent_version: str = Field(min_length=1)
+    spec_version: Literal["0.1"]
+    default_model: str | None = None
+    # Optional whitelist of models the agent's driver / wrapped SDK can run.
+    # Each entry is a glob pattern matched against `Commission.model`
+    # (fnmatch semantics): "claude-*" matches any Claude model,
+    # "claude-haiku-4-5-*" pins to Haiku 4.5 builds, "gpt-*" matches
+    # any GPT. When None, the agent advertises support for any model
+    # the supervisor provides, but the driver may still fail at the
+    # provider call. When set, an agent SHOULD validate `Commission.model`
+    # at startup and emit `error_occurred(code: "unsupported_model")` +
+    # `agent_stopped(reason: "error")` before any model turn if the
+    # provided model is not matched.
+    supported_models: list[str] | None = None
+    # System prompt the agent ships with. Commission.system_prompt overrides
+    # when both are set (see spec §2.7).
+    system_prompt: str | None = None
+    # Baked-in user prompt for autonomous agents (cron-style runs with no
+    # per-call user message). Commission.prompt overrides when both are set.
+    prompt: str | None = None
+    # MCP servers the agent dials at startup. Connection material stays
+    # inside the agent process; only identity (id, name, description) and
+    # the terminal dial `status` are on the wire. Tools surfaced by these
+    # servers appear in `tools` with `avp.mcp_server_id` set to the
+    # server's id.
+    mcp_servers: list[McpServerDecl] | None = None
+    tools: list[ToolDecl] | None = None
+    subagents: list[SubagentDecl] | None = None
+    skills: list[SkillDecl] | None = None
+    capabilities: list[str] | None = None
+
+
+__all__ = [
+    "AgentDescriptor",
+    "McpServerDecl",
+    "SkillDecl",
+    "SubagentDecl",
+    "ToolDecl",
+]

avp/envelope.py

@@ -0,0 +1,108 @@
+"""Shared CloudEvents 1.0 / OTel span scaffolding for AVP v0.1.
+
+Private module. Consumers MUST import from the spec-scoped namespaces
+(`avp.trajectory`, `avp.commission`, `avp.descriptor`)
+which re-export the public bits of this file.
+
+What lives here is the cross-cutting wire scaffolding shared by every
+spec module:
+
+- CloudEvents 1.0 envelope (`_CloudEventBase`).
+- OTel span identification carried on every event's `data`
+  (`_SpanData`).
+- Source URI (`SOURCE_AGENT`) used by every event type. The agent is
+  the sole producer on the wire (spec §8 conformance #1); supervisor
+  attribution lives in `run_requested.data` (`avp.commission` +
+  `avp.supervisor.*`), not in the envelope's `source` field.
+- Pydantic `model_config` presets (`_STRICT`, `_OPEN`) used by every
+  spec model.
+- ID / timestamp generators used as Pydantic field defaults
+  (`now_iso`, `new_event_id`, `new_trace_id`, `new_span_id`,
+  `ZERO_SPAN_ID`).
+
+Nothing spec-specific belongs here. Commission, Descriptor, and
+trajectory event types live in their own modules.
+"""
+
+from __future__ import annotations
+
+import secrets
+import uuid
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Iso8601 = str
+
+
+def now_iso() -> str:
+    """ISO 8601 / RFC 3339 timestamp with Z suffix."""
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+def new_event_id() -> str:
+    """CloudEvents 1.0 requires `id` unique within `source`. UUID v4 satisfies that."""
+    return str(uuid.uuid4())
+
+
+def new_trace_id() -> str:
+    """OTel trace ID: 16 random bytes, hex-encoded (32 lowercase chars)."""
+    return secrets.token_hex(16)
+
+
+def new_span_id() -> str:
+    """OTel span ID: 8 random bytes, hex-encoded (16 lowercase chars)."""
+    return secrets.token_hex(8)
+
+
+# 16 zero hex chars: the OTel "absent parent" sentinel for top-level spans.
+ZERO_SPAN_ID = "0" * 16
+
+
+# Source URI (CloudEvents reverse-DNS). The agent is the sole producer on
+# the wire (spec §8 conformance #1); every event carries `avp://agent`.
+# Supervisor attribution, when applicable, rides inside
+# `run_requested.data` (`avp.commission` + `avp.supervisor.*`).
+SOURCE_AGENT = "avp://agent"
+
+
+# Pydantic model_config presets. `populate_by_name=True` lets parsers accept
+# either the alias (wire form: dotted) or the Python attribute name. `by_alias`
+# is passed at serialization time to emit the alias form on the wire.
+_STRICT = ConfigDict(extra="forbid", populate_by_name=True, ser_json_omit_default=False)
+_OPEN = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class _SpanData(BaseModel):
+    """Span identification carried by every AVP event's `data` payload.
+
+    `extra="allow"` lets vendor-namespaced extension attributes (e.g.,
+    `vendor.priority`, `vendor.trace_id`) round-trip through the trajectory
+    verbatim. Spec-defined attributes are validated; unknown keys pass through.
+    """
+
+    model_config = _OPEN
+    trace_id: str = Field(min_length=32, max_length=32, pattern=r"^[0-9a-f]{32}$")
+    span_id: str = Field(min_length=16, max_length=16, pattern=r"^[0-9a-f]{16}$")
+    parent_span_id: str = Field(min_length=16, max_length=16, pattern=r"^[0-9a-f]{16}$")
+    meta: dict[str, Any] | None = Field(default=None, alias="avp.meta")
+
+
+class _CloudEventBase(BaseModel):
+    """Shared CloudEvents 1.0 envelope fields. Specific events override
+    `type` and `source` with Literal constants and define `data: <Type>Data`.
+
+    Per CloudEvents §1: required `specversion`, `id`, `source`, `type`.
+    Optional: `subject`, `time`, `datacontenttype`, `dataschema`. AVP uses
+    `subject` to carry run_id.
+    """
+
+    model_config = _STRICT
+    specversion: Literal["1.0"] = "1.0"
+    id: str = Field(min_length=1, default_factory=new_event_id)
+    time: Iso8601 = Field(default_factory=now_iso)
+    subject: str | None = Field(default=None, min_length=1)  # run_id
+    datacontenttype: str | None = "application/json"
+    dataschema: str | None = None
+    correlation_id: str | None = Field(default=None, min_length=1, alias="avp.correlation_id")

avp/gen_ai.py

@@ -0,0 +1,160 @@
+"""avp.gen_ai — Project AVP trajectory events into OpenTelemetry GenAI attributes.
+
+OTel GenAI semantic conventions registry:
+  https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
+
+AVP's wire format carries attributes under its own `avp.*` namespace.
+Consumers forwarding the same data into an OTel-native backend (OTLP
+collectors, Honeycomb / Datadog / Grafana GenAI views) call
+`to_gen_ai_attrs(event)` to derive a dict of `gen_ai.*` attributes ready
+to attach to a span. The AVP wire stays put; this is the projection
+layer.
+
+The projection is one-way (AVP wire → OTel attrs), one event at a time.
+AVP-specific fields without an OTel equivalent (`avp.cost_usd`,
+`avp.refusal.category`, ...) are intentionally NOT projected. See
+`FOUNDATIONS.md` for the mapping table and rationale.
+
+## Un-projected OTel GenAI attributes
+
+The following registry attributes are NOT in the projection:
+
+**Spec gaps — present in OTel, absent from AVP wire today:**
+
+  - Sampling parameters: `gen_ai.request.{max_tokens, temperature, top_p,
+    top_k, frequency_penalty, presence_penalty, seed, stop_sequences,
+    choice_count, stream}`. Belong on `Commission` / `agent_started`.
+  - `gen_ai.response.id` — provider-assigned response id (e.g. OpenAI's
+    `id`). Would live on `AssistantMessageData`.
+  - `gen_ai.tool.{type, description, definitions}` — tool classification
+    and per-tool metadata. AVP has descriptions on
+    `agent_started.tools[]` decls but not on dispatch events.
+
+**Projector-shape limitation:**
+
+  - `gen_ai.input.messages` — requires the prior event stream, not a
+    single event. Build via `avp.history.to_messages(events_so_far)`
+    and attach manually when entering an `assistant_message` span.
+
+**Out of scope for AVP (see [trajectory.md §1.1](../../../spec/v0.1/trajectory.md) non-goals):**
+
+  - Retrieval: `gen_ai.retrieval.{query.text, documents}` — RAG-specific.
+  - Evaluation: `gen_ai.evaluation.{name, score.value, score.label,
+    explanation}` — post-hoc annotation, not runtime.
+  - Workflow / data source: `gen_ai.{workflow.name, data_source.id}` —
+    supervisor-framework concerns above the wire.
+  - Embeddings: `gen_ai.request.encoding_formats`,
+    `gen_ai.embeddings.dimension.count` — AVP isn't designed for
+    embedding workloads.
+  - Per-token granularity: `gen_ai.token.type`.
+  - Output modality: `gen_ai.output.type`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from avp.trajectory import (
+    AgentDescribedEvent,
+    AgentStartedEvent,
+    AssistantMessageEvent,
+    Event,
+    SubagentInvokedEvent,
+    SubagentReturnedEvent,
+    ToolInvokedEvent,
+    ToolReturnedEvent,
+)
+
+
+def _drop_none(attrs: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in attrs.items() if v is not None}
+
+
+def to_gen_ai_attrs(event: Event) -> dict[str, Any]:
+    """Project an AVP `Event` into a dict of OTel `gen_ai.*` attributes.
+
+    Keys are the OTel GenAI registry names; values are passed through
+    from the AVP payload unchanged (no unit conversion). Returns `{}`
+    for events with no GenAI projection (`run_requested`, `agent_stopped`,
+    `mcp_*`, `error_occurred`, `UnknownEvent`).
+    """
+    if isinstance(event, AgentStartedEvent):
+        d = event.data
+        return _drop_none(
+            {
+                "gen_ai.provider.name": d.provider_name,
+                "gen_ai.operation.name": d.operation_name,
+                "gen_ai.request.model": d.request_model,
+                "gen_ai.conversation.id": d.thread_id,
+                "gen_ai.system_instructions": d.system_prompt,
+            }
+        )
+
+    if isinstance(event, AssistantMessageEvent):
+        d = event.data
+        u = d.usage
+        output_messages = [
+            {
+                "role": "assistant",
+                "content": [
+                    b.model_dump(by_alias=True, exclude_none=True, mode="json") for b in d.content
+                ],
+            }
+        ]
+        return _drop_none(
+            {
+                "gen_ai.provider.name": d.provider_name,
+                "gen_ai.request.model": d.request_model,
+                "gen_ai.response.model": d.response_model,
+                "gen_ai.response.finish_reasons": d.response_finish_reasons,
+                "gen_ai.response.time_to_first_chunk": d.response_time_to_first_chunk,
+                "gen_ai.usage.input_tokens": u.input_tokens,
+                "gen_ai.usage.output_tokens": u.output_tokens,
+                "gen_ai.usage.cache_read.input_tokens": u.cache_read_input_tokens,
+                "gen_ai.usage.cache_creation.input_tokens": u.cache_creation_input_tokens,
+                "gen_ai.usage.reasoning.output_tokens": u.reasoning_output_tokens,
+                "gen_ai.output.messages": output_messages,
+            }
+        )
+
+    if isinstance(event, ToolInvokedEvent):
+        d = event.data
+        return {
+            "gen_ai.tool.name": d.tool_name,
+            "gen_ai.tool.call.id": d.tool_call_id,
+            "gen_ai.tool.call.arguments": d.tool_input,
+        }
+
+    if isinstance(event, ToolReturnedEvent):
+        d = event.data
+        return {
+            "gen_ai.tool.name": d.tool_name,
+            "gen_ai.tool.call.id": d.tool_call_id,
+            "gen_ai.tool.call.result": d.tool_result.content,
+        }
+
+    if isinstance(event, SubagentInvokedEvent):
+        d = event.data
+        return _drop_none(
+            {
+                "gen_ai.operation.name": "invoke_agent",
+                "gen_ai.agent.name": d.subagent_name,
+                "gen_ai.agent.description": d.subagent_description,
+                "gen_ai.agent.id": d.subagent_run_id,
+            }
+        )
+
+    if isinstance(event, SubagentReturnedEvent):
+        return {"gen_ai.agent.name": event.data.subagent_name}
+
+    if isinstance(event, AgentDescribedEvent):
+        desc = event.data.descriptor
+        return {
+            "gen_ai.agent.name": desc.agent_name,
+            "gen_ai.agent.version": desc.agent_version,
+        }
+
+    return {}
+
+
+__all__ = ["to_gen_ai_attrs"]

avp/history.py

@@ -0,0 +1,86 @@
+"""avp.history — Reconstruct a provider-style message history from a trajectory.
+
+A trajectory is the agent's stream-of-events record. A *message history*
+is the provider's input shape: a list of `{role, content}` records. This
+module converts the former to the latter, faithfully enough that the
+same conversation could be replayed against any provider's chat API.
+
+The mapping is:
+
+- `agent_started.avp.system_prompt` → one `system` message.
+- `agent_started.avp.prompt`        → one `user` message (initial turn).
+- `assistant_message.avp.content`   → one `assistant` message per turn.
+- Each `tool_returned.avp.tool_result` between two assistant turns
+  bundles into a single `user` message preceding the next assistant turn
+  (mirroring how providers shuttle tool results in user-role messages).
+
+Other event types (`tool_invoked`, `mcp_*`, `error_occurred`, `agent_*`,
+`UnknownEvent`, ...) are observability or run-control facts that don't
+contribute to message history; they are skipped.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Literal
+
+from pydantic import BaseModel
+
+from avp.content import AVPContentBlock, TextBlock
+from avp.envelope import _OPEN
+from avp.trajectory import (
+    AgentStartedEvent,
+    AssistantMessageEvent,
+    Event,
+    ToolReturnedEvent,
+)
+
+
+class Message(BaseModel):
+    """One entry of a provider-style message history."""
+
+    model_config = _OPEN
+    role: Literal["user", "assistant", "system"]
+    content: list[AVPContentBlock]
+
+
+def to_messages(events: Iterable[Event]) -> list[Message]:
+    """Reconstruct a provider-style message history from a trajectory.
+
+    See the module docstring for the event-to-message mapping.
+    """
+    messages: list[Message] = []
+    pending: list[AVPContentBlock] = []
+
+    def flush() -> None:
+        if pending:
+            messages.append(Message(role="user", content=list(pending)))
+            pending.clear()
+
+    for event in events:
+        if isinstance(event, AgentStartedEvent):
+            if event.data.system_prompt:
+                messages.append(
+                    Message(
+                        role="system",
+                        content=[TextBlock(text=event.data.system_prompt)],
+                    )
+                )
+            if event.data.prompt:
+                messages.append(
+                    Message(
+                        role="user",
+                        content=[TextBlock(text=event.data.prompt)],
+                    )
+                )
+        elif isinstance(event, AssistantMessageEvent):
+            flush()
+            messages.append(Message(role="assistant", content=list(event.data.content)))
+        elif isinstance(event, ToolReturnedEvent):
+            pending.append(event.data.tool_result)
+
+    flush()
+    return messages
+
+
+__all__ = ["Message", "to_messages"]