scion-sdk 0.5.6__py3-none-any.whl

agent_connector_sdk/__init__.py

@@ -0,0 +1,23 @@
+"""Scion SDK: the connector-facing SDK for the agent-packages fleet.
+
+Public modules are imported by their own path (``agent_connector_sdk.mcp.server``,
+``agent_connector_sdk.ports`` and so on). The package root exports the version
+and, lazily, :class:`Connector` and :func:`run`, so importing it never pulls in
+the MCP server stack.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_connector_sdk._version import __version__
+
+__all__ = ["Connector", "__version__", "run"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in ("Connector", "run"):
+        from agent_connector_sdk import connector
+
+        return getattr(connector, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

agent_connector_sdk/_contract_fields.py

@@ -0,0 +1,92 @@
+"""Typed field readers for ``ac:AccessContract`` subjects."""
+
+from __future__ import annotations
+
+from ._turtle import AccessContractError, Term
+from .credentials.references import SecretReferenceError, parse_secret_reference
+
+AC = "https://knuckles-team.github.io/agent-connector-sdk/access#"
+ACCESS_KINDS = frozenset({"mcp_tool", "http_endpoint", "graphql_query", "a2a_skill"})
+PAGINATION_MODES = frozenset({"none", "cursor", "offset", "page"})
+PUSHDOWN_OPS = frozenset({"filter", "sort", "limit", "project"})
+COST_HINTS = frozenset({"low", "medium", "high"})
+
+Props = dict[str, list[Term]]
+
+
+def _one(props: Props, name: str, subject: str) -> Term | None:
+    values = props.get(AC + name, [])
+    if len(values) > 1:
+        raise AccessContractError(f"{subject}: ac:{name} appears more than once")
+    return values[0] if values else None
+
+
+def text(props: Props, name: str, subject: str) -> str:
+    """Return a required non-empty string property."""
+    value = _one(props, name, subject)
+    if not isinstance(value, str) or not value.strip():
+        raise AccessContractError(f"{subject}: missing ac:{name}")
+    return value
+
+
+def integer(props: Props, name: str, subject: str) -> int | None:
+    """Return an optional non-negative integer property."""
+    value = _one(props, name, subject)
+    if value is not None and (not isinstance(value, int) or value < 0):
+        raise AccessContractError(
+            f"{subject}: ac:{name} must be a non-negative integer"
+        )
+    return value
+
+
+def choice(
+    props: Props,
+    name: str,
+    subject: str,
+    *,
+    allowed: frozenset[str],
+    default: str | None = None,
+) -> str:
+    """Return a property constrained to ``allowed``; ``default`` makes it optional."""
+    raw = _one(props, name, subject) if default is not None else None
+    value = text(props, name, subject) if default is None else str(raw or default)
+    if value not in allowed:
+        raise AccessContractError(f"{subject}: unknown ac:{name} {value!r}")
+    return value
+
+
+def pushdown(props: Props, subject: str) -> frozenset[str]:
+    """Return the declared pushdown operations, refusing unknown ones."""
+    ops = frozenset(str(op) for op in props.get(AC + "pushdown", []))
+    unknown = sorted(ops - PUSHDOWN_OPS)
+    if unknown:
+        raise AccessContractError(f"{subject}: unknown ac:pushdown {unknown}")
+    return ops
+
+
+def parameters(props: Props) -> tuple[str, ...]:
+    """Return the declared operation parameters in sorted order."""
+    return tuple(sorted(str(p) for p in props.get(AC + "parameter", [])))
+
+
+def auth_ref(props: Props, subject: str) -> str | None:
+    """Return a rendered credential reference, refusing a literal secret."""
+    value = _one(props, "authRef", subject)
+    if value is None:
+        return None
+    try:
+        return parse_secret_reference(str(value)).render()
+    except SecretReferenceError:
+        raise AccessContractError(
+            f"{subject}: ac:authRef must be a credential reference, not a secret"
+        ) from None
+
+
+def bindings(graph: dict[str, Props], contract: str) -> tuple[tuple[str, str], ...]:
+    """Return the sorted (property, field) pairs bound to ``contract``."""
+    pairs = []
+    for subject, props in graph.items():
+        if contract in props.get(AC + "contract", []):
+            prop = text(props, "property", subject)
+            pairs.append((prop, text(props, "field", subject)))
+    return tuple(sorted(pairs))

agent_connector_sdk/_extras.py

@@ -0,0 +1,22 @@
+"""Clear errors for features that need an optional extra of the base install."""
+
+from __future__ import annotations
+
+import importlib
+
+__all__ = ["require_mcp_extra"]
+
+
+def require_mcp_extra(feature: str) -> None:
+    """Raise ``ImportError`` naming the ``mcp`` extra when fastmcp or mcp is absent."""
+    missing = []
+    for name in ("fastmcp", "mcp"):
+        try:
+            importlib.import_module(name)
+        except ImportError:
+            missing.append(name)
+    if missing:
+        raise ImportError(
+            f"{feature} needs {' and '.join(missing)}, which the base install of "
+            'scion-sdk leaves out; install "scion-sdk[mcp]"'
+        )

agent_connector_sdk/_turtle.py

@@ -0,0 +1,116 @@
+"""Flat Turtle reader used by the access-contract parser.
+
+It tokenizes one restricted profile (see :mod:`agent_connector_sdk.access_contract`)
+and raises :class:`AccessContractError` on anything outside it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+
+RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
+
+_TOKEN_RE = re.compile(
+    r"(?P<ws>\s+|#[^\n]*)"
+    r"|(?P<iri><[^<>\s]*>)"
+    r'|(?P<str>"(?:[^"\\\n]|\\.)*")'
+    r"|(?P<int>-?\d+)"
+    r"|(?P<prefix>@prefix)"
+    r"|(?P<pname>[A-Za-z_]?[\w-]*:(?:[\w-](?:[\w.-]*[\w-])?)?)"
+    r"|(?P<a>a(?=\s))"
+    r"|(?P<punct>[;,.])"
+)
+
+Term = str | int
+Triple = tuple[str, str, Term]
+
+
+class AccessContractError(ValueError):
+    """A connector ontology declares an invalid access contract."""
+
+
+def _tokens(text: str) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    pos = 0
+    while pos < len(text):
+        match = _TOKEN_RE.match(text, pos)
+        if match is None or match.end() == pos:
+            raise AccessContractError(f"unsupported Turtle at offset {pos}")
+        kind = match.lastgroup or ""
+        if kind != "ws":
+            out.append((kind, match.group()))
+        pos = match.end()
+    return out
+
+
+class _Reader:
+    def __init__(self, text: str) -> None:
+        self.toks = _tokens(text)
+        self.pos = 0
+        self.prefixes: dict[str, str] = {}
+        self.triples: list[Triple] = []
+
+    def next(self) -> tuple[str, str]:
+        if self.pos >= len(self.toks):
+            raise AccessContractError("unexpected end of Turtle")
+        self.pos += 1
+        return self.toks[self.pos - 1]
+
+    def expect(self, value: str) -> None:
+        if self.next()[1] != value:
+            raise AccessContractError(f"expected {value!r}")
+
+    def term(self) -> Term:
+        kind, value = self.next()
+        if kind == "iri":
+            return value[1:-1]
+        if kind == "a":
+            return RDF_TYPE
+        if kind == "pname":
+            prefix, _, local = value.partition(":")
+            if prefix not in self.prefixes:
+                raise AccessContractError(f"undeclared prefix {prefix!r}")
+            return self.prefixes[prefix] + local
+        if kind == "str":
+            return value[1:-1].replace('\\"', '"').replace("\\\\", "\\")
+        if kind == "int":
+            return int(value)
+        raise AccessContractError(f"unexpected token {value!r}")
+
+    def prefix(self) -> None:
+        kind, name = self.next()
+        iri = self.next()
+        if kind != "pname" or not name.endswith(":") or iri[0] != "iri":
+            raise AccessContractError("malformed @prefix")
+        self.prefixes[name[:-1]] = iri[1][1:-1]
+        self.expect(".")
+
+    def statement(self) -> None:
+        subject = str(self.term())
+        sep = ";"
+        while sep == ";":
+            predicate = str(self.term())
+            sep = ","
+            while sep == ",":
+                self.triples.append((subject, predicate, self.term()))
+                sep = self.next()[1]
+        if sep != ".":
+            raise AccessContractError("statement must end with '.'")
+
+    def read(self) -> list[Triple]:
+        while self.pos < len(self.toks):
+            if self.toks[self.pos][0] == "prefix":
+                self.pos += 1
+                self.prefix()
+            else:
+                self.statement()
+        return self.triples
+
+
+def parse_graph(text: str) -> dict[str, dict[str, list[Term]]]:
+    """Read flat Turtle into a subject -> predicate -> objects index."""
+    graph: dict[str, dict[str, list[Term]]] = defaultdict(lambda: defaultdict(list))
+    for subject, predicate, obj in _Reader(text).read():
+        graph[subject][predicate].append(obj)
+    return graph

agent_connector_sdk/_version.py

@@ -0,0 +1,8 @@
+"""The SDK version, read from installed package metadata.
+
+``pyproject.toml`` is the only file that spells it (SDK-CONNECTOR-CONTROL-R071.2).
+"""
+
+from agent_connector_sdk.connector_identity import distribution_version
+
+__version__ = distribution_version("scion-sdk")

agent_connector_sdk/a2a/__init__.py

@@ -0,0 +1,46 @@
+"""Agent-to-Agent (A2A) protocol pieces any connector or host can reuse.
+
+CONCEPT:SDK-CONNECTOR-CONTROL-R014.21
+
+The base install carries the wire models and the JSON-RPC client (pydantic and
+httpx only). The server-side application factory needs the optional ``a2a``
+extra (fasta2a and starlette); a host such as arbora mounts it behind its own
+admission and authentication. Nothing here stores tasks or builds cards from a
+graph: durable task state and graph-derived cards belong to the host.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import A2AClient, A2AResult
+from .models import (
+    A2AMessage,
+    A2ATask,
+    A2ATaskStatus,
+    AgentCard,
+    AgentSkill,
+    TaskState,
+    TextPart,
+)
+
+__all__ = [
+    "A2AClient",
+    "A2AMessage",
+    "A2AResult",
+    "A2ATask",
+    "A2ATaskStatus",
+    "AgentCard",
+    "AgentSkill",
+    "TaskState",
+    "TextPart",
+    "create_a2a_app",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "create_a2a_app":
+        from .app import create_a2a_app
+
+        return create_a2a_app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

agent_connector_sdk/a2a/app.py

@@ -0,0 +1,83 @@
+"""Server-side A2A application factory (needs the ``a2a`` extra).
+
+CONCEPT:SDK-CONNECTOR-CONTROL-R014.21
+
+Builds a fasta2a ASGI app for a pydantic-ai agent. The caller supplies the
+broker and storage; this SDK holds no task store. A host mounts the returned
+app behind its own admission and authentication.
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import AsyncIterator
+from typing import Any
+
+from .models import AgentSkill
+
+__all__ = ["create_a2a_app", "require_a2a_extra"]
+
+
+def require_a2a_extra(feature: str) -> None:
+    """Raise ``ImportError`` naming the ``a2a`` extra when it is absent."""
+    missing = []
+    for name in ("fasta2a", "starlette"):
+        try:
+            importlib.import_module(name)
+        except ImportError:
+            missing.append(name)
+    if missing:
+        raise ImportError(
+            f"{feature} needs {' and '.join(missing)}, which the base install of "
+            'scion-sdk leaves out; install "scion-sdk[a2a]"'
+        )
+
+
+def create_a2a_app(
+    agent: Any,
+    *,
+    name: str,
+    url: str,
+    version: str,
+    description: str = "",
+    skills: list[AgentSkill] | None = None,
+    storage: Any,
+    broker: Any,
+) -> Any:
+    """Return the fasta2a application for ``agent`` with the given card fields."""
+    require_a2a_extra("create_a2a_app")
+    from fasta2a import FastA2A, Skill
+    from fasta2a.pydantic_ai import AgentWorker
+    from starlette.types import ASGIApp  # noqa: F401 - the extra's contract
+
+    worker = AgentWorker(agent=agent, broker=broker, storage=storage)
+    card_skills = [
+        Skill(
+            id=skill.id,
+            name=skill.name,
+            description=skill.description,
+            tags=list(skill.tags),
+            input_modes=list(skill.input_modes),
+            output_modes=list(skill.output_modes),
+        )
+        for skill in skills or []
+    ]
+
+    async def lifespan(
+        app: Any,
+    ) -> AsyncIterator[None]:  # pragma: no cover - exercised by the host
+        async with app.task_manager, worker.run():
+            yield
+
+    from contextlib import asynccontextmanager
+
+    return FastA2A(
+        storage=storage,
+        broker=broker,
+        name=name,
+        url=url,
+        version=version,
+        description=description or None,
+        skills=card_skills,
+        lifespan=asynccontextmanager(lifespan),
+    )

agent_connector_sdk/a2a/client.py

@@ -0,0 +1,117 @@
+"""Bounded JSON-RPC client for one A2A exchange.
+
+CONCEPT:SDK-CONNECTOR-CONTROL-R014.21
+
+``message/send`` then ``tasks/get`` polling until the task leaves a pending
+state or the deadline passes. Failures come back as an :class:`A2AResult` with
+a fixed message; remote error bodies are never echoed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+from pydantic import ValidationError
+
+from .models import A2AMessage, A2ATask, AgentCard
+
+CARD_PATH = "/.well-known/agent-card.json"
+_MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class A2AResult:
+    content: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+
+class A2AClient:
+    """Call one remote A2A agent. Supply ``transport`` to reuse a host's egress."""
+
+    def __init__(
+        self,
+        *,
+        timeout: float = 300.0,
+        poll_interval: float = 2.0,
+        request_timeout: float = 60.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if timeout <= 0 or poll_interval <= 0 or request_timeout <= 0:
+            raise ValueError("A2A client timeouts must be positive")
+        self.timeout = timeout
+        self.poll_interval = poll_interval
+        self.request_timeout = min(request_timeout, timeout)
+        self._transport = transport
+
+    def _client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            timeout=self.request_timeout,
+            transport=self._transport,
+            follow_redirects=False,
+        )
+
+    @staticmethod
+    def _json(response: httpx.Response) -> Any:
+        response.raise_for_status()
+        if len(response.content) > _MAX_RESPONSE_BYTES:
+            raise ValueError("A2A response exceeds its bound")
+        return response.json()
+
+    async def fetch_card(self, base_url: str) -> AgentCard | None:
+        """Fetch and validate a peer's agent card; ``None`` when unusable."""
+        try:
+            async with self._client() as client:
+                data = self._json(await client.get(base_url.rstrip("/") + CARD_PATH))
+            return AgentCard.model_validate(data)
+        except (httpx.HTTPError, ValueError, ValidationError):
+            return None
+
+    async def _rpc(
+        self,
+        client: httpx.AsyncClient,
+        url: str,
+        method: str,
+        params: dict[str, Any],
+        rid: int,
+    ) -> dict[str, Any]:
+        payload = {"jsonrpc": "2.0", "method": method, "params": params, "id": rid}
+        data = self._json(await client.post(url, json=payload))
+        if not isinstance(data, dict):
+            raise ValueError("A2A response root must be an object")
+        return data
+
+    async def send(self, url: str, text: str) -> A2AResult:
+        """Send one user text message and wait for the task's agent reply."""
+        message = A2AMessage.user_text(text)
+        try:
+            async with asyncio.timeout(self.timeout), self._client() as client:
+                sent = await self._rpc(
+                    client, url, "message/send", {"message": message.wire()}, 1
+                )
+                if "error" in sent:
+                    return A2AResult(error="A2A peer rejected the request")
+                task = A2ATask.model_validate(sent.get("result"))
+                while task.pending:
+                    await asyncio.sleep(self.poll_interval)
+                    polled = await self._rpc(
+                        client, url, "tasks/get", {"id": task.id}, 2
+                    )
+                    if "error" in polled:
+                        return A2AResult(error="A2A peer rejected task polling")
+                    task = A2ATask.model_validate(polled.get("result"))
+        except TimeoutError:
+            return A2AResult(error="A2A execution deadline exceeded")
+        except (httpx.HTTPError, ValueError, ValidationError) as exc:
+            return A2AResult(error=f"A2A communication failed ({type(exc).__name__})")
+        reply = task.last_agent_message()
+        if task.status.state != "completed" or reply is None:
+            return A2AResult(error=f"A2A task ended {task.status.state}")
+        return A2AResult(content=reply.text(), metadata=dict(reply.metadata))

agent_connector_sdk/a2a/models.py

@@ -0,0 +1,112 @@
+"""A2A wire models: agent card, skills, messages and tasks.
+
+CONCEPT:SDK-CONNECTOR-CONTROL-R014.21
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+TaskState = Literal[
+    "submitted",
+    "working",
+    "input-required",
+    "completed",
+    "canceled",
+    "failed",
+    "rejected",
+    "auth-required",
+    "unknown",
+]
+TERMINAL_STATES: frozenset[str] = frozenset(
+    {"completed", "canceled", "failed", "rejected"}
+)
+PENDING_STATES: frozenset[str] = frozenset({"submitted", "working"})
+
+
+class _Wire(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class AgentSkill(_Wire):
+    """One skill an agent card advertises."""
+
+    id: str = Field(min_length=1, max_length=256)
+    name: str = Field(min_length=1, max_length=256)
+    description: str = Field(default="", max_length=4096)
+    tags: list[str] = Field(default_factory=list, max_length=64)
+    input_modes: list[str] = Field(default_factory=lambda: ["text"], alias="inputModes")
+    output_modes: list[str] = Field(
+        default_factory=lambda: ["text"], alias="outputModes"
+    )
+
+
+class AgentCard(_Wire):
+    """The document an agent serves at ``/.well-known/agent-card.json``."""
+
+    name: str = Field(min_length=1, max_length=256)
+    url: str = Field(min_length=1, max_length=2048)
+    version: str = Field(default="0.0.0", max_length=64)
+    description: str = Field(default="", max_length=4096)
+    protocol_version: str = Field(default="0.3.0", alias="protocolVersion")
+    skills: list[AgentSkill] = Field(default_factory=list, max_length=256)
+    default_input_modes: list[str] = Field(
+        default_factory=lambda: ["text"], alias="defaultInputModes"
+    )
+    default_output_modes: list[str] = Field(
+        default_factory=lambda: ["text"], alias="defaultOutputModes"
+    )
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+
+    def wire(self) -> dict[str, Any]:
+        return self.model_dump(by_alias=True)
+
+
+class TextPart(_Wire):
+    kind: Literal["text"] = "text"
+    text: str
+
+
+class A2AMessage(_Wire):
+    kind: Literal["message"] = "message"
+    role: Literal["user", "agent"]
+    parts: list[TextPart] = Field(default_factory=list)
+    message_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()), alias="messageId"
+    )
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def user_text(cls, text: str) -> A2AMessage:
+        return cls(role="user", parts=[TextPart(text=text)])
+
+    def text(self) -> str:
+        return "".join(part.text for part in self.parts)
+
+    def wire(self) -> dict[str, Any]:
+        return self.model_dump(by_alias=True, exclude_defaults=False)
+
+
+class A2ATaskStatus(_Wire):
+    state: TaskState = "unknown"
+
+
+class A2ATask(_Wire):
+    kind: Literal["task"] = "task"
+    id: str = Field(min_length=1)
+    context_id: str | None = Field(default=None, alias="contextId")
+    status: A2ATaskStatus = Field(default_factory=A2ATaskStatus)
+    history: list[A2AMessage] = Field(default_factory=list)
+
+    @property
+    def pending(self) -> bool:
+        return self.status.state in PENDING_STATES
+
+    def last_agent_message(self) -> A2AMessage | None:
+        for message in reversed(self.history):
+            if message.role != "user":
+                return message
+        return None