agentenv-framework-protocol 0.1.269__py3-none-any.whl

agentenv_protocol/client.py

@@ -0,0 +1,185 @@
+"""Data-plane wire protocol client (JSON-RPC) for servers implementing the AgentEnv protocol."""
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from .manifest import INTERFACE_MANIFEST_PATH
+from .types import INTAKE_EXTENSION_URI, MCP_PATH, MCP_TRANSPORT, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataResponse, GetDataResponse, Part, ResetDataResponse
+
+logger = logging.getLogger(__name__)
+
+
+async def _rpc(base_url: str, method: str, params: dict, timeout: int, verify: bool) -> dict:
+    request = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+    async with httpx.AsyncClient(verify=verify) as client:
+        response = await client.post(f"{base_url}{RPC_PATH}", json=request, timeout=timeout)
+        response.raise_for_status()
+        body = response.json()
+    if "error" in body:
+        error = body["error"]
+        raise RuntimeError(f"{method} failed: {error.get('message')} ({error.get('data') or error.get('code')})")
+    return body["result"]
+
+
+async def reset_data(base_url: str, timeout: int = 30, verify: bool = True) -> ResetDataResponse:
+    return ResetDataResponse.model_validate(await _rpc(base_url, METHOD_RESET, {}, timeout, verify))
+
+
+async def add_data(base_url: str, parts: list[Part], timeout: int = 120, verify: bool = True) -> AddDataResponse:
+    params = {"parts": [p.model_dump(mode="json", exclude_none=True) for p in parts]}
+    return AddDataResponse.model_validate(await _rpc(base_url, METHOD_ADD, params, timeout, verify))
+
+
+async def get_data(base_url: str, timeout: int = 30, verify: bool = True) -> GetDataResponse:
+    return GetDataResponse.model_validate(await _rpc(base_url, METHOD_GET, {}, timeout, verify))
+
+
+async def get_card(base_url: str, timeout: int = 10, verify: bool = True) -> dict:
+    async with httpx.AsyncClient(verify=verify) as client:
+        response = await client.get(f"{base_url}{WELL_KNOWN_PATH}", timeout=timeout)
+        response.raise_for_status()
+        return response.json()
+
+
+async def supports_v1(base_url: str, verify: bool = True) -> bool:
+    try:
+        await get_card(base_url, verify=verify)
+        return True
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code != 404:
+            logger.warning(f"v1 probe {base_url}: unexpected {e.response.status_code}, treating as legacy")
+        return False
+    except Exception as e:
+        logger.warning(f"v1 probe {base_url}: {type(e).__name__}, treating as legacy")
+        return False
+
+
+def find_extension(card: dict, uri: str) -> dict | None:
+    """Return the EnvironmentCard extension advertised under `uri`, or None.
+
+    Extensions live under `capabilities.extensions` (mirroring A2A's AgentCard). Tolerates a
+    missing/null `capabilities` or `extensions` so legacy and no-extensions cards return None
+    rather than raising.
+    """
+    for ext in (card.get("capabilities") or {}).get("extensions") or []:
+        if ext.get("uri") == uri:
+            return ext
+    return None
+
+
+def extension_params(card: dict, uri: str) -> dict:
+    """Return the `params` of the extension at `uri`, or {} if absent or paramless."""
+    ext = find_extension(card, uri)
+    return (ext.get("params") or {}) if ext else {}
+
+
+def find_extension_method(card: dict, uri: str, method: str) -> dict | None:
+    """Return the method named `method` that the extension at `uri` advertises, or None.
+
+    `method` names an entry of the extension's `params.methods`. The returned entry's own `method`
+    key is its HTTP verb (POST unless advertised), and its `endpoint` is the method's own, else the
+    extension's.
+    """
+    advertised = extension_params(card, uri)
+    entry = (advertised.get("methods") or {}).get(method)
+    if entry is None:
+        return None
+    return {**entry, "endpoint": entry.get("endpoint") or advertised.get("endpoint"), "method": (entry.get("method") or "POST").upper()}
+
+
+def mcp_path(card: dict) -> str:
+    """Return the path of the MCP endpoint a card declares, or `MCP_PATH` by convention.
+
+    Paths are relative to the address the card was fetched from.
+    """
+    for interface in card.get("additionalInterfaces") or []:
+        if interface.get("transport") == MCP_TRANSPORT and interface.get("url"):
+            return interface["url"]
+    return MCP_PATH
+
+
+def intake_declaration(card: dict) -> dict | None:
+    """Return the intake declaration advertised under `INTAKE_EXTENSION_URI`, or None.
+
+    Distinct from `extension_params`: absence of the extension (or its `params`) returns None —
+    "no claim", so consumers skip fit-checks — rather than `{}`, which would read as "declares an
+    empty intake". Mirrors the `supports_v1` 404->legacy tolerance.
+    """
+    ext = find_extension(card, INTAKE_EXTENSION_URI)
+    if not ext:
+        return None
+    params = ext.get("params")
+    return params if params else None
+
+
+def find_tool(card: dict, name: str) -> dict | None:
+    """Return the MCP tool advertised under `name`, or None.
+
+    `capabilities.tools` is advertisement-only (invocation stays MCP). Tolerates a missing/null
+    `capabilities` or `tools` so legacy and no-tools cards return None rather than raising.
+    """
+    for entry in (card.get("capabilities") or {}).get("tools") or []:
+        if entry.get("name") == name:
+            return entry
+    return None
+
+
+def find_child(card: dict, name: str) -> dict | None:
+    """Return the nested child EnvironmentCard named `name`, or None.
+
+    A composed card (e.g. a gateway fronting one or more MCP servers) nests each backing
+    environment's card under `children_environments`, with that child's endpoints already
+    rewritten to be reachable from the composed card's base_url. Callers resolve a service by
+    name here, then use the child card with `find_extension`/`invoke_extension`. Tolerates a
+    missing/null `children_environments` so single/leaf cards return None rather than raising.
+    """
+    for child in card.get("children_environments") or []:
+        if child.get("name") == name:
+            return child
+    return None
+
+
+async def get_interface_manifest(base_url: str, interface: str, endpoint: str = INTERFACE_MANIFEST_PATH, timeout: int = 30, verify: bool = True):
+    """Fetch one interface's manifest from a server's manifest index endpoint.
+
+    ``endpoint`` is the index path — pass the one advertised on the card under
+    ``GET_INTERFACES_EXTENSION_URI`` (already gateway-rewritten) or leave the
+    default when talking to a server directly. Mechanical by design: raises
+    ``httpx.HTTPStatusError`` on a non-2xx response and ``ValueError`` on a
+    non-JSON body; treating a 404 as "server opted out" is caller policy.
+    """
+    url = f"{base_url.rstrip('/')}{endpoint}/{interface}"
+    async with httpx.AsyncClient(verify=verify) as client:
+        response = await client.get(url, timeout=timeout)
+        response.raise_for_status()
+        return response.json()
+
+
+async def invoke_extension(base_url: str, card: dict, uri: str, params: dict | None = None, timeout: int = 30, verify: bool = True, *, method: str | None = None):
+    """Invoke a card extension via its advertised REST endpoint.
+
+    Reads the endpoint and HTTP verb of the extension method named `method` from the card, so the
+    card alone is enough to invoke; without `method`, the first method listed. Returns the parsed
+    JSON result; raises on a non-2xx response.
+    """
+    ext = find_extension(card, uri)
+    if ext is None:
+        raise ValueError(f"extension not advertised on card: {uri}")
+    advertised = ext.get("params") or {}
+    name = method if method is not None else next(iter(advertised.get("methods") or {}), None)
+    op = find_extension_method(card, uri, name) if name is not None else {"endpoint": advertised.get("endpoint"), "method": "POST"}
+    if op is None:
+        offered = ", ".join(advertised.get("methods") or {}) or "none"
+        raise ValueError(f"extension {uri} does not advertise method {method!r} (advertises: {offered})")
+    if not op["endpoint"]:
+        raise ValueError(f"extension {uri} has no endpoint in params")
+    url = f"{base_url}{op['endpoint']}"
+    async with httpx.AsyncClient(verify=verify) as client:
+        if op["method"] == "GET":
+            response = await client.get(url, params=params or {}, timeout=timeout)
+        else:
+            response = await client.request(op["method"], url, json=params or {}, timeout=timeout)
+        response.raise_for_status()
+        return response.json()

agentenv_protocol/manifest.py

@@ -0,0 +1,203 @@
+"""Interface Manifest: a structured description of a server's data model that
+interface renderers (CLI, GUI, ...) are generated from.
+
+Servers build manifests from their API spec, validate them against their live
+MCP tools, and serve them at ``INTERFACE_MANIFEST_PATH``, advertised on the
+EnvironmentCard under ``GET_INTERFACES_EXTENSION_URI``. Producers and
+consumers both import the schema, constants, and version rules from here.
+
+Two layers: a structural core (:class:`InterfaceManifest`) and one projection
+per interface (:class:`CliManifest` for the CLI). Manifests are structure
+only — no environment data or per-environment behavior — and every operation
+references an MCP tool by name, so renderers interact with a server purely
+through the protocol and tool calls.
+
+Skew tolerance: models ignore unknown fields, and :func:`manifest_compatible`
+permits compatible version skew, so producers and consumers can deploy
+independently.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Bumped when the manifest shape changes in a way renderers must notice.
+MANIFEST_VERSION = "0.1.0"
+
+# Where a server serves its manifest index (GET -> list of interface names);
+# one interface's manifest is at f"{INTERFACE_MANIFEST_PATH}/{interface}".
+INTERFACE_MANIFEST_PATH = "/agentenv/interface-manifest"
+
+# EnvironmentCard extension advertising the (gateway-rewritten) index endpoint
+# in `params.endpoint`. Absent = pre-extension image; `[]` from the endpoint =
+# definitively no manifests.
+GET_INTERFACES_EXTENSION_URI = "urn:agentenv:get-interfaces/v1"
+
+OperationKind = Literal["list", "read", "create", "update", "delete"]
+
+# CLI command name per core operation kind (``read`` renders as ``get``).
+CLI_COMMANDS: Dict[str, str] = {
+    "list": "list",
+    "read": "get",
+    "create": "create",
+    "update": "update",
+    "delete": "delete",
+}
+
+_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+
+
+def manifest_compatible(served: object, supported: str = MANIFEST_VERSION) -> bool:
+    """Whether a manifest at version ``served`` is consumable by a renderer built for ``supported``.
+
+    Same major is compatible; while the major is 0 (pre-1.0 semver) the minor
+    must match too, so only patch-level skew is tolerated. A missing or
+    unparseable version is incompatible.
+    """
+    if not isinstance(served, str):
+        return False
+    served_match = _VERSION_RE.match(served)
+    supported_match = _VERSION_RE.match(supported)
+    if not served_match or not supported_match:
+        return False
+    if served_match.group(1) != supported_match.group(1):
+        return False
+    if served_match.group(1) == "0" and served_match.group(2) != supported_match.group(2):
+        return False
+    return True
+
+
+class ManifestModel(BaseModel):
+    """Base for all manifest models: unknown fields from a newer producer are ignored."""
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class FieldSpec(ManifestModel):
+    """One field of an entity, as seen through the server's tools."""
+
+    name: str
+    type: str
+    format: Optional[str] = None
+    enum: Optional[List[str]] = None
+    description: Optional[str] = None
+    required: bool = False
+    read_only: bool = False
+
+
+class Relationship(ManifestModel):
+    """A field that points at another entity (for detail-view linking)."""
+
+    field: str
+    references: str
+    many: bool = False
+
+
+class ParamSpec(ManifestModel):
+    """A single input parameter of an operation/action, as the tool accepts it.
+
+    Carries everything an interface projection needs to render the input
+    without re-reading the spec: its type, array item type, whether it is
+    required, and (for enum fields) the constrained set of allowed values.
+    """
+
+    name: str
+    type: str
+    item_type: Optional[str] = None
+    required: bool = False
+    enum: Optional[List[str]] = None
+
+
+class Operation(ManifestModel):
+    """A CRUD operation on an entity, backed by exactly one MCP tool."""
+
+    kind: OperationKind
+    tool: str
+    summary: Optional[str] = None
+    description: Optional[str] = None
+    required: List[str] = Field(default_factory=list)
+    params: List[ParamSpec] = Field(default_factory=list)
+
+
+class Action(ManifestModel):
+    """A non-CRUD tool (rendered as a button/command), backed by one MCP tool."""
+
+    tool: str
+    description: Optional[str] = None
+    params: List[ParamSpec] = Field(default_factory=list)
+
+
+class Entity(ManifestModel):
+    """A record type: its fields, relationships, and per-entity operations."""
+
+    name: str
+    fields: List[FieldSpec] = Field(default_factory=list)
+    relationships: List[Relationship] = Field(default_factory=list)
+    operations: List[Operation] = Field(default_factory=list)
+
+
+class InterfaceManifest(ManifestModel):
+    """The full structural description of a server."""
+
+    service: str
+    manifest_version: str = MANIFEST_VERSION
+    entities: List[Entity] = Field(default_factory=list)
+    actions: List[Action] = Field(default_factory=list)
+
+    def to_json(self) -> str:
+        """Deterministic, human-diffable JSON (trailing newline for POSIX).
+
+        ``exclude_none`` drops absent optionals (``format``/``enum``/
+        ``description``) so committed goldens stay compact; Pydantic consumers
+        see absent == default anyway.
+        """
+        return self.model_dump_json(indent=2, exclude_none=True) + "\n"
+
+
+# ── CLI interface projection ────────────────────────────────────────────────
+#
+# The command-oriented view of the structural core: per-entity commands
+# (list/get/create/update/delete) + actions, each backed by one MCP tool with
+# its required/optional params (enum fields carry their constrained options).
+
+
+class CliCommand(ManifestModel):
+    """One CLI command: an entity operation or action, backed by one MCP tool."""
+
+    tool: str
+    summary: Optional[str] = None
+    description: Optional[str] = None
+    params: List[ParamSpec] = Field(default_factory=list)
+
+
+class CliEntity(ManifestModel):
+    """An entity's CLI commands, keyed by verb (``list``/``get``/...)."""
+
+    entity: str
+    commands: Dict[str, CliCommand] = Field(default_factory=dict)
+
+
+class CliAction(ManifestModel):
+    """A non-CRUD tool exposed as its own top-level CLI command."""
+
+    name: str
+    tool: str
+    params: List[ParamSpec] = Field(default_factory=list)
+    description: Optional[str] = None
+
+
+class CliManifest(ManifestModel):
+    """The CLI projection of a server's structural core."""
+
+    service: str
+    manifest_version: str = MANIFEST_VERSION
+    interface: Literal["cli"] = "cli"
+    entities: List[CliEntity] = Field(default_factory=list)
+    actions: List[CliAction] = Field(default_factory=list)
+
+    def to_json(self) -> str:
+        """Deterministic, human-diffable JSON (see :meth:`InterfaceManifest.to_json`)."""
+        return self.model_dump_json(indent=2, exclude_none=True) + "\n"

agentenv_protocol/preflight.py

@@ -0,0 +1,81 @@
+"""Pre-deploy fit-check for the data-plane intake declaration.
+
+Pure functions over plain dicts — no I/O, no Mongo/S3 — so they run at authoring/
+registration time. The agent-env-side ``preflight(universe, env)`` wraps these by
+reading ``client.intake_declaration(card)`` and each service's seed ``data.json``.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+def _json_add_format(declaration: dict, content_format: str) -> Optional[dict]:
+    """Return the declared ``data/add`` format for an inline (part=data) payload, or None."""
+    for fmt in declaration.get("add") or []:
+        if fmt.get("part") == "data" and fmt.get("format") == content_format:
+            return fmt
+    return None
+
+
+def intake_fit_check(
+    declaration: Optional[dict],
+    data_json: dict,
+    *,
+    content_format: str = "json",
+) -> list[str]:
+    """Check a candidate seed ``data_json`` against a declared intake.
+
+    ``declaration`` is the dict from ``client.intake_declaration(card)`` (an
+    ``IntakeDeclaration``), or ``None``. ``data_json`` is the collection→rows seed the
+    server will load via ``load_from_json``.
+
+    Returns a list of human-readable issues; empty means it fits (or there is no claim
+    to check against). Absence of a declaration reads as "no claim" and returns ``[]``,
+    matching ``intake_declaration``'s absence semantics.
+
+    The check models the *loadable subset* and tolerates extra fields (real
+    ``data.json`` is a superset on validated-tier servers): it flags collections the
+    server does not accept and rows missing a declared required field, but never
+    complains about extra fields.
+    """
+    if not declaration:
+        return []
+
+    fmt = _json_add_format(declaration, content_format)
+    if fmt is None:
+        accepted = [
+            f"{f.get('part')}/{f.get('format')}" for f in declaration.get("add") or []
+        ]
+        return [
+            f"data/add does not accept part=data format={content_format} "
+            f"(accepted: {accepted or 'nothing'})"
+        ]
+
+    tables = fmt.get("tables")
+    if not tables:
+        # Accepted, but no per-table schema was declared — nothing more to verify.
+        return []
+
+    issues: list[str] = []
+    for collection, rows in data_json.items():
+        if not isinstance(rows, list):
+            # Scalar top-level extras (e.g. contacts.current_user_id, email.user_email)
+            # ride alongside the collections on export; they are not tables to validate.
+            continue
+        if collection not in tables:
+            issues.append(
+                f"collection '{collection}' is not accepted "
+                f"(declared: {sorted(tables)})"
+            )
+            continue
+        schema = tables[collection] or {}
+        required = schema.get("required") or []
+        if not required:
+            continue
+        for i, row in enumerate(rows):
+            if not isinstance(row, dict):
+                continue
+            missing = [r for r in required if r not in row]
+            if missing:
+                issues.append(f"{collection}[{i}] missing required field(s): {missing}")
+    return issues