avp-cli 0.1.0__py3-none-any.whl

avp/__init__.py

@@ -0,0 +1,31 @@
+"""avp — Python reference implementation for the Agent Voyager Project (v0.1 model).
+
+The wire format is built on CloudEvents 1.0, OpenTelemetry GenAI semantic
+conventions, OTel spans, JSON-RPC 2.0, MCP, Agent Skills, and JSON Schema.
+See FOUNDATIONS.md for the full mapping.
+
+Public API lives in the spec-scoped submodules; this package's top level
+exposes only version metadata. Import wire types and helpers directly from
+the module that owns them:
+
+    from avp.commission import Commission, McpServerHttp, McpServerStdio, Skill
+    from avp.descriptor import AgentDescriptor
+    from avp.trajectory import (
+        AgentStartedEvent,
+        Event,
+        parse_event,
+        event_to_wire,
+    )
+    from avp.tracer import AVPTracer, current_tracer
+    from avp.io import iter_events, write_event
+    from avp.enums import ErrorCode, StopReason
+    from avp.pricing import compute_cost, load_default_prices
+
+Doing it this way keeps the spec ↔ module mapping 1:1 and prevents drift
+into a single "everything-bag" import surface.
+"""
+
+__version__ = "0.1.0"
+SCHEMA_VERSION = "0.1"
+
+__all__ = ["SCHEMA_VERSION", "__version__"]

avp/commission.py

@@ -0,0 +1,236 @@
+"""avp.commission — Pydantic types for the AVP Commission Spec.
+
+Defines the Commission shape (supervisor → agent setup message) and the
+managed-asset entries the supervisor declares inline. This module mirrors
+the [Commission spec](../../../../spec/v0.1/commission.md).
+
+Consumers wanting only the run-config object can:
+
+    from avp.commission import Commission, McpServerHttp, McpServerStdio
+
+…without dragging in Trajectory / Descriptor types.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from avp.envelope import _STRICT
+
+_ID_PATTERN = r"^[a-z0-9_-]+$"
+
+# `model` is a canonical models.dev slug: "<origin>/<model>" (e.g.
+# "anthropic/claude-opus-4-8", "openai/gpt-4o"). The origin segment is the
+# model's home namespace and the pricing key; it is independent of the
+# `Provider.id` storefront that actually serves the tokens.
+_MODEL_SLUG_PATTERN = r"^[^/]+/.+$"
+
+
+class SecretRef(BaseModel):
+    """A reference to a secret the supervisor resolves out of band.
+
+    Carries a `vault` handle, never the secret value. The supervisor maps the
+    handle to material (env var, secrets file, broker) at run time; the value
+    never appears on the wire or in the trajectory. Used by `Provider.credential`
+    and `McpServerHttp.auth`.
+    """
+
+    model_config = _STRICT
+    vault: str = Field(min_length=1, pattern=_ID_PATTERN)
+
+
+class McpServerHttp(BaseModel):
+    """Inline HTTP MCP server entry in Commission.mcp_servers."""
+
+    model_config = _STRICT
+    id: str = Field(min_length=1, pattern=_ID_PATTERN)
+    type: Literal["http"]
+    url: str = Field(min_length=1)
+    # Non-secret request headers. Credentials go in `auth` (a SecretRef the
+    # supervisor resolves out of band), not here.
+    headers: dict[str, str] | None = None
+    auth: SecretRef | None = None
+
+
+class McpServerStdio(BaseModel):
+    """Inline stdio MCP server entry in Commission.mcp_servers."""
+
+    model_config = _STRICT
+    id: str = Field(min_length=1, pattern=_ID_PATTERN)
+    type: Literal["stdio"]
+    command: list[str] = Field(min_length=1)
+    args: list[str] | None = None
+    env: dict[str, str] | None = None
+
+
+McpServer = Annotated[McpServerHttp | McpServerStdio, Field(discriminator="type")]
+
+
+class Provider(BaseModel):
+    """Optional LLM routing override: which storefront serves the model.
+
+    Absent → the agent uses its native default (whatever its own environment
+    configures). Present → the supervisor directs the agent at a specific
+    endpoint. `id` selects the protocol/auth family (e.g. "anthropic",
+    "openai", "openrouter"); `base_url` overrides the endpoint; `credential`
+    references the API key by vault handle (never the value).
+
+    The model's origin (the `Commission.model` slug's first segment) and the
+    storefront `id` are independent axes: `model: "openai/gpt-4o"` with
+    `provider.id: "openrouter"` reads as "OpenAI's gpt-4o, bought through
+    OpenRouter". An agent that cannot speak the requested provider's protocol
+    MUST fail (error_occurred + agent_stopped reason=error), never silently
+    run elsewhere.
+    """
+
+    model_config = _STRICT
+    id: str = Field(min_length=1, pattern=_ID_PATTERN)
+    base_url: str | None = None
+    credential: SecretRef | None = None
+
+
+class Skill(BaseModel):
+    """Inline skill entry in Commission.skills."""
+
+    model_config = _STRICT
+    id: str = Field(min_length=1, pattern=_ID_PATTERN)
+    files: dict[str, str]
+
+    @field_validator("files")
+    @classmethod
+    def _require_skill_md(cls, v: dict[str, str]) -> dict[str, str]:
+        if "SKILL.md" not in v:
+            raise ValueError("files must contain 'SKILL.md'")
+        return v
+
+    def _frontmatter_value(self, key: str) -> str | None:
+        content = self.files.get("SKILL.md", "")
+        if not content.startswith("---"):
+            return None
+        end = content.find("---", 3)
+        if end == -1:
+            return None
+        for line in content[3:end].splitlines():
+            if line.startswith(f"{key}:"):
+                return line[len(key) + 1 :].strip() or None
+        return None
+
+    @property
+    def name(self) -> str | None:
+        return self._frontmatter_value("name")
+
+    @property
+    def description(self) -> str | None:
+        return self._frontmatter_value("description")
+
+
+class SupervisorPreamble(BaseModel):
+    """Identifies the supervisor that is requesting the run.
+
+    Carried inside `Commission.supervisor` and projected onto the
+    `run_requested` event's `data` (`avp.supervisor.name` +
+    `avp.supervisor.version`) so a trajectory consumer can attribute the
+    run to the originating supervisor without an out-of-band lookup. The
+    event's `source` is `avp://agent` (the agent is the sole producer on
+    the wire); supervisor attribution lives inside `data`.
+
+    `name` SHOULD be a stable identifier for the supervisor implementation
+    or instance (e.g. `"avp-cli"`, `"acme.scheduler"`).
+    `version` is optional but recommended; it travels with the trajectory
+    and lets auditors correlate a run with the exact supervisor build
+    that requested it.
+    """
+
+    model_config = _STRICT
+    name: str = Field(min_length=1)
+    version: str | None = None
+
+
+class Commission(BaseModel):
+    """Supervisor's declaration of the supervisor-managed environment slice.
+
+    Managed asset entries (`mcp_servers`, `skills`) carry inline connection
+    material; no resolver round-trip is needed. The agent dials MCP servers
+    and injects skill content directly from these fields at startup.
+
+    Anything the agent provides on its own (in-process tools, baked-in
+    skills) is invisible to AVP and the Commission entirely. The agent's own
+    contribution surfaces in `agent_described.data["avp.descriptor"]` so
+    consumers can audit what the agent showed up with. The agent's runtime
+    layer merges its internal contribution with the Commission-managed assets
+    into one bag the loop dispatches against; collisions on `id` are a
+    startup error.
+    """
+
+    model_config = _STRICT
+
+    schema_version: Literal["0.1"]
+    run_id: str = Field(min_length=1)
+
+    # Supervisor identity. Optional but RECOMMENDED. When present, the agent
+    # stamps `run_requested.data.avp.supervisor.*` from this field so the
+    # trajectory records who requested the run. When absent, the agent
+    # still emits `run_requested` but with `avp.supervisor.name="unknown"`.
+    supervisor: SupervisorPreamble | None = None
+
+    # Supervisor-managed assets. Connection material is inline; agents dial
+    # MCP servers and load skill content directly at startup.
+    mcp_servers: list[McpServer] | None = None
+    skills: list[Skill] | None = None
+
+    # Optional LLM routing override. Absent → the agent's native default.
+    provider: Provider | None = None
+
+    # Allow-lists over the agent's Descriptor-declared surface. Each list
+    # gates the parallel `descriptor.*` field for this run.
+    #
+    #   - None (absent) → every descriptor entry of that kind is exposed
+    #                     (default).
+    #   - []            → none are exposed.
+    #   - [n1, n2, …]   → only the listed names/ids are exposed; the agent
+    #                     hides the rest from the model and runtime-blocks
+    #                     any hallucinated invocation with a `tool_returned`
+    #                     (isError=True) (or, for subagents, a
+    #                     `subagent_returned` with `reason=error`).
+    #
+    # Names MUST appear in the corresponding descriptor field at startup or
+    # the agent emits `error_occurred(code: "commission_collision")` and
+    # stops with `reason=error`. Subtractive-only: these have no effect on
+    # supervisor-managed assets (those are gated by being-in-the-Commission).
+    # `enabled_builtin_mcp_servers` filters `descriptor.mcp_servers[].id`;
+    # disabling a server prevents the agent from dialing it, so its tools
+    # are unavailable for the run.
+    enabled_builtin_tools: list[str] | None = None
+    enabled_builtin_subagents: list[str] | None = None
+    enabled_builtin_skills: list[str] | None = None
+    enabled_builtin_mcp_servers: list[str] | None = None
+
+    output_schema: dict[str, Any] | None = None
+
+    # Agent plane (what the agent runs)
+    prompt: str | None = None
+    system_prompt: str | None = None
+    # Canonical models.dev slug "<origin>/<model>" (e.g. "anthropic/claude-opus-4-8").
+    # The pattern requires a non-empty origin and model id. Required: the origin
+    # segment is the pricing key and the native-default routing hint; agents
+    # split it off to get the SDK-native model id.
+    model: str = Field(min_length=1, pattern=_MODEL_SLUG_PATTERN)
+
+    # Metadata
+    thread_id: str | None = None
+    tags: list[str] | None = None
+    meta: dict[str, Any] | None = None
+
+
+__all__ = [
+    "Commission",
+    "McpServer",
+    "McpServerHttp",
+    "McpServerStdio",
+    "Provider",
+    "SecretRef",
+    "Skill",
+    "SupervisorPreamble",
+]

avp/content.py

@@ -0,0 +1,273 @@
+"""avp.content — AVP content block types for assistant message content.
+
+Normalized content union covering the message-history shapes of Anthropic
+Messages, OpenAI Chat Completions + Responses, Google Gemini
+generateContent, AWS Bedrock Converse, Cohere Chat, and Mistral Chat.
+The goal is non-lossy round-trip of agent history across providers.
+
+Every block sets `model_config = ConfigDict(extra="allow")` so unmodeled
+provider-specific fields (Anthropic `cache_control`, OpenAI
+`encrypted_content`, Gemini `thought_signature`, future additions)
+round-trip unchanged without spec churn.
+
+Discriminate on the `type` field. Serialize with
+`model_dump(by_alias=True, mode="json")`.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+from avp.envelope import _OPEN
+
+# ── Source variants ───────────────────────────────────────────────────────────
+
+
+class Base64Source(BaseModel):
+    """Inline base64-encoded media. Anthropic `source.type=base64`, Gemini
+    `inline_data`, Bedrock `source.bytes`."""
+
+    model_config = _OPEN
+    type: Literal["base64"] = "base64"
+    media_type: str
+    data: str
+
+
+class UrlSource(BaseModel):
+    """External URL. Anthropic `source.type=url`, OpenAI `image_url`,
+    Gemini `file_data` (when `file_uri` is a public URL)."""
+
+    model_config = _OPEN
+    type: Literal["url"] = "url"
+    url: str
+
+
+class FileSource(BaseModel):
+    """Provider-hosted file reference. OpenAI Files API `file_id`, Anthropic
+    Files API `file_id`, Gemini `file_data.file_uri` (Files API URI)."""
+
+    model_config = _OPEN
+    type: Literal["file"] = "file"
+    file_id: str
+
+
+Source = Annotated[Base64Source | UrlSource | FileSource, Field(discriminator="type")]
+
+
+# ── Citations / annotations ───────────────────────────────────────────────────
+
+
+class Citation(BaseModel):
+    """Span-anchored attribution on a text or document block. Unifies
+    Anthropic citations (`char_location`, `page_location`,
+    `content_block_location`), OpenAI annotations (`url_citation`,
+    `file_citation`, `file_path`), and Gemini grounding chunks. `type`
+    carries the provider's raw citation kind verbatim so downstream
+    consumers can normalize without re-deriving it."""
+
+    model_config = _OPEN
+    type: str
+    cited_text: str | None = None
+    start_index: int | None = Field(default=None, ge=0)
+    end_index: int | None = Field(default=None, ge=0)
+    source_id: str | None = None
+    source_url: str | None = None
+    source_title: str | None = None
+
+
+# ── Blocks ────────────────────────────────────────────────────────────────────
+
+
+class TextBlock(BaseModel):
+    """Plain text content. Anthropic `text`, OpenAI `text` /
+    `output_text` / `input_text`, Gemini text part, Bedrock `text`,
+    Cohere `text`, Mistral `text`. `citations` carries Anthropic citations,
+    OpenAI annotations, and Gemini grounding spans anchored into this text."""
+
+    model_config = _OPEN
+    type: Literal["text"] = "text"
+    text: str
+    citations: list[Citation] | None = None
+
+
+class ThinkingBlock(BaseModel):
+    """Reasoning / chain-of-thought emitted by the model.
+
+    Anthropic extended thinking, OpenAI o-series `reasoning` items,
+    Gemini `thought` parts, Bedrock `reasoningContent`, Mistral thinking.
+    `signature` is the opaque blob the provider requires echoed back on
+    the next turn for continued reasoning: Anthropic's cryptographic
+    signature, OpenAI's `encrypted_content`, or Gemini's
+    `thought_signature`. `redacted` flags blocks whose plaintext is
+    unavailable (encrypted-only form)."""
+
+    model_config = _OPEN
+    type: Literal["thinking"] = "thinking"
+    thinking: str
+    signature: str | None = None
+    redacted: bool | None = None
+
+
+class ImageBlock(BaseModel):
+    """Image content. Anthropic `image`, OpenAI `image_url` /
+    `input_image`, Gemini `inline_data` / `file_data` image, Bedrock
+    `image`."""
+
+    model_config = _OPEN
+    type: Literal["image"] = "image"
+    source: Source
+
+
+class AudioBlock(BaseModel):
+    """Audio content. OpenAI `input_audio` (input) and `audio` (output),
+    Gemini `inline_data` audio, Bedrock `audio`. `transcript` carries
+    OpenAI's output-audio transcript when present."""
+
+    model_config = _OPEN
+    type: Literal["audio"] = "audio"
+    source: Source
+    transcript: str | None = None
+
+
+class VideoBlock(BaseModel):
+    """Video content. Gemini `inline_data` / `file_data` video, Bedrock
+    `video`."""
+
+    model_config = _OPEN
+    type: Literal["video"] = "video"
+    source: Source
+
+
+class DocumentBlock(BaseModel):
+    """Document / file content (typically PDFs). Anthropic `document`
+    (with citation support), OpenAI `input_file`, Gemini `file_data`,
+    Bedrock `document`. `title` is the document name used as the
+    citation target; `context` is supplementary metadata Anthropic
+    surfaces alongside the document for the model."""
+
+    model_config = _OPEN
+    type: Literal["document"] = "document"
+    source: Source
+    title: str | None = None
+    context: str | None = None
+    citations: list[Citation] | None = None
+
+
+class ToolUseBlock(BaseModel):
+    """Model invokes a client-dispatched tool. Anthropic `tool_use`,
+    OpenAI `function_call` / `tool_calls`, Gemini `function_call`,
+    Bedrock `toolUse`, Cohere tool_calls, Mistral tool_calls."""
+
+    model_config = _OPEN
+    type: Literal["tool_use"] = "tool_use"
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+ToolResultContent = Annotated[TextBlock | ImageBlock | DocumentBlock, Field(discriminator="type")]
+
+
+class ToolResultBlock(BaseModel):
+    """Result of a client-dispatched tool call. Anthropic `tool_result`,
+    OpenAI `function_call_output` / tool-role message, Gemini
+    `function_response`, Bedrock `toolResult`. Anthropic permits nested
+    text/image/document content blocks; other providers serialize a
+    flat string. `structured_content` carries a programmatic payload
+    alongside the human-readable `content` (MCP's `structuredContent`,
+    Gemini `function_response.response`, Bedrock `toolResult.content.json`);
+    the two channels are complementary, not alternatives. `is_error`
+    flags rejections."""
+
+    model_config = _OPEN
+    type: Literal["tool_result"] = "tool_result"
+    tool_use_id: str
+    content: str | list[ToolResultContent]
+    structured_content: dict[str, Any] | None = None
+    is_error: bool | None = None
+
+
+class ServerToolUseBlock(BaseModel):
+    """Built-in tool executed by the provider rather than the agent.
+    Anthropic `server_tool_use` (web_search, code_execution), OpenAI
+    Responses `web_search_call` / `file_search_call` / `computer_call` /
+    `code_interpreter_call`, Gemini `executable_code` / `google_search`.
+    `name` carries the tool kind (e.g. "web_search", "code_interpreter",
+    "computer_use", "google_search"). Distinct from `tool_use` because
+    the agent never dispatches these; they are observability of a
+    provider-side action."""
+
+    model_config = _OPEN
+    type: Literal["server_tool_use"] = "server_tool_use"
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+class ServerToolResultBlock(BaseModel):
+    """Result of a provider-executed built-in tool. Pairs with
+    `ServerToolUseBlock`. Anthropic `web_search_tool_result`, OpenAI
+    Responses `*_call_output`, Gemini `code_execution_result`.
+    `content` is provider-shaped (search-result rows, code stdout,
+    computer-use screenshots, ...)."""
+
+    model_config = _OPEN
+    type: Literal["server_tool_result"] = "server_tool_result"
+    tool_use_id: str
+    name: str
+    content: Any
+    is_error: bool | None = None
+
+
+class RefusalBlock(BaseModel):
+    """Structured refusal distinct from generated text. OpenAI assistant
+    message `refusal` field and Responses `output_refusal` item. Other
+    providers emit refusals as plain text plus a finish reason; this
+    block represents only providers that ship a typed refusal."""
+
+    model_config = _OPEN
+    type: Literal["refusal"] = "refusal"
+    refusal: str
+
+
+# ── Discriminated union ───────────────────────────────────────────────────────
+
+
+AVPContentBlock = Annotated[
+    TextBlock
+    | ThinkingBlock
+    | ImageBlock
+    | AudioBlock
+    | VideoBlock
+    | DocumentBlock
+    | ToolUseBlock
+    | ToolResultBlock
+    | ServerToolUseBlock
+    | ServerToolResultBlock
+    | RefusalBlock,
+    Field(discriminator="type"),
+]
+
+
+__all__ = [
+    "AVPContentBlock",
+    "AudioBlock",
+    "Base64Source",
+    "Citation",
+    "DocumentBlock",
+    "FileSource",
+    "ImageBlock",
+    "RefusalBlock",
+    "ServerToolResultBlock",
+    "ServerToolUseBlock",
+    "Source",
+    "TextBlock",
+    "ThinkingBlock",
+    "ToolResultBlock",
+    "ToolResultContent",
+    "ToolUseBlock",
+    "UrlSource",
+    "VideoBlock",
+]