agentship-core 0.0.1__tar.gz

agentship_core-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Env / secrets — never commit
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Docs build
+site/

agentship_core-0.0.1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: agentship-core
+Version: 0.0.1
+Summary: AgentShip kernel — spec, context, runtime, registry, errors, middleware, and the echo engine. The thin, vendor-free harness core.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Provides-Extra: jwt
+Requires-Dist: httpx>=0.27; extra == 'jwt'
+Requires-Dist: pyjwt[crypto]>=2.9; extra == 'jwt'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# agentship-core
+
+The AgentShip kernel: spec, context, runtime, registry, errors, middleware, and the zero-dependency `echo` engine. Vendor-free — depends only on `pydantic` and `pyyaml`. Import as `agentship`.
+
+## Vendor-free by contract — and guarded against drift
+
+The kernel cannot import OpenTelemetry, `a2a-sdk`, or any other vendor library (design §4.6): engine
+and eval hooks must work with only `agentship-core` installed. That forces us to keep a few small
+implementations of our own — the semantic-convention key constants, the in-memory
+`RecordingObserver`, the A2A wire models, and the JWT/JWKS seam. We do not just trust those to match
+the standards they claim to speak; each is pinned to its upstream by a **conformance guard** — a test
+in the relevant package that validates our output against the real library. So the code stays thin and
+vendor-free, and it still can't silently drift.
+
+See [`docs/decisions/0001-integrate-not-invent.md`](../../docs/decisions/0001-integrate-not-invent.md)
+for the delegations and the keep-thin-and-guard decisions.

agentship_core-0.0.1/README.md

@@ -0,0 +1,16 @@
+# agentship-core
+
+The AgentShip kernel: spec, context, runtime, registry, errors, middleware, and the zero-dependency `echo` engine. Vendor-free — depends only on `pydantic` and `pyyaml`. Import as `agentship`.
+
+## Vendor-free by contract — and guarded against drift
+
+The kernel cannot import OpenTelemetry, `a2a-sdk`, or any other vendor library (design §4.6): engine
+and eval hooks must work with only `agentship-core` installed. That forces us to keep a few small
+implementations of our own — the semantic-convention key constants, the in-memory
+`RecordingObserver`, the A2A wire models, and the JWT/JWKS seam. We do not just trust those to match
+the standards they claim to speak; each is pinned to its upstream by a **conformance guard** — a test
+in the relevant package that validates our output against the real library. So the code stays thin and
+vendor-free, and it still can't silently drift.
+
+See [`docs/decisions/0001-integrate-not-invent.md`](../../docs/decisions/0001-integrate-not-invent.md)
+for the delegations and the keep-thin-and-guard decisions.

agentship_core-0.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentship-core"
+version = "0.0.1"
+description = "AgentShip kernel — spec, context, runtime, registry, errors, middleware, and the echo engine. The thin, vendor-free harness core."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "pydantic>=2",
+    "pyyaml>=6",
+]
+
+# Postgres substrate (the single-owner ThreadLock and, later, the durable task
+# store). Optional so a bare install stays vendor-light and runs on the in-memory
+# ThreadLock fallback; `pip install agentship-core[postgres]` opts in. psycopg3 is
+# chosen to match LangGraph's AsyncPostgresSaver — one driver for the whole stack.
+[project.optional-dependencies]
+postgres = ["psycopg[binary]>=3.1"]
+
+# The optional in-app JWT auth path (JwtAuthProvider). Not the default — behind a
+# gateway the gateway validates tokens — so PyJWT (with crypto for RS256/ES256 and
+# JWKS) is an opt-in extra rather than a base dependency. httpx backs the JWKS fetch.
+jwt = ["pyjwt[crypto]>=2.9", "httpx>=0.27"]
+
+# The zero-dependency echo engine registers here; adapter packages (e.g.
+# agentship-langgraph) add their own engines to the same group. Core discovers
+# them via importlib.metadata — no core edit needed to add an engine.
+[project.entry-points."agentship.engines"]
+echo = "agentship.engines.echo:EchoEngine"
+
+# The built-in deterministic model router registers here; a project ships its own
+# ModelRouter under the same group to swap routing policy without a core edit.
+[project.entry-points."agentship.model_routers"]
+default = "agentship.primitives.model_router:DefaultModelRouter"
+
+# The built-in auth-provider factories register here; a project or vendor ships a
+# custom provider under the same group (selected by name in service config) with no
+# core edit. Each value is a factory: (config mapping) -> AuthProvider.
+[project.entry-points."agentship.auth_providers"]
+forwarded = "agentship.auth.registry:forwarded_from_config"
+api_key = "agentship.auth.registry:api_key_from_config"
+jwt = "agentship.auth.registry:jwt_from_config"
+composite = "agentship.auth.registry:composite_from_config"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentship"]

agentship_core-0.0.1/src/agentship/__init__.py

@@ -0,0 +1,53 @@
+"""AgentShip — an open, recipe-first harness for agentic systems.
+
+Author an agent (or a team) in YAML or Python and get the plumbing wired behind
+small, stable seams. This module re-exports the kernel's public surface: the spec,
+the identity backbone, the runtime, and the error taxonomy.
+"""
+
+from __future__ import annotations
+
+from .context import Caller, RunContext, RunMode, get_run_context
+from .engines.base import Engine, EngineCapabilities, Event, Result, ResumeToken
+from .errors import (
+    AgentShipError,
+    CapabilityError,
+    EngineNotFoundError,
+    SpecError,
+)
+from .middleware import Middleware
+from .primitives.model_router import (
+    DefaultModelRouter,
+    ModelRouter,
+    resolve_model_router,
+)
+from .runtime import RunnableAgent, build_agent
+from .spec import AgentSpec, MemberSpec, ModelParams, ObservabilitySpec, load_spec, resolve_code
+
+__all__ = [
+    "AgentSpec",
+    "MemberSpec",
+    "ModelParams",
+    "ObservabilitySpec",
+    "load_spec",
+    "resolve_code",
+    "Caller",
+    "RunContext",
+    "RunMode",
+    "get_run_context",
+    "RunnableAgent",
+    "build_agent",
+    "Middleware",
+    "ModelRouter",
+    "DefaultModelRouter",
+    "resolve_model_router",
+    "Engine",
+    "EngineCapabilities",
+    "Event",
+    "ResumeToken",
+    "Result",
+    "AgentShipError",
+    "SpecError",
+    "CapabilityError",
+    "EngineNotFoundError",
+]

agentship_core-0.0.1/src/agentship/a2a/__init__.py

@@ -0,0 +1,53 @@
+"""A2A (agent-to-agent) interop — the optional networked-specialist layer (Phase 05).
+
+This package is **Layer 1**: it is imported only when an agent opts into A2A (a networked
+``specialists[].a2a:`` block or an ``a2a.expose: true`` block in YAML). Layer 0 — in-process
+specialists (P02) and direct MCP (P03) — never touches it, so the whole ``agentship.a2a``
+subtree can be absent and the default runtime stays green (the ``interop.optional`` invariant).
+
+It carries the transport-agnostic pieces that live in core: the A2A wire models
+(:mod:`agentship.a2a.models`), Agent Card generation (:mod:`agentship.a2a.card`), and the
+:class:`~agentship.a2a.resolver.SpecialistResolver` that turns one ``AgentRef`` into either an
+in-process or a networked specialist — so a supervisor's ``kit.specialist(name)`` call is
+identical whichever side of the wire the specialist lives on. The FastAPI server adapter that
+*exposes* an agent over A2A lives in ``agentship_service.a2a`` (it needs the web app), not here.
+"""
+
+from __future__ import annotations
+
+from .bridge import agent_ref_from_member
+from .card import build_agent_card
+from .client import HttpxTransport, RemoteA2aAgent
+from .models import (
+    AgentCapabilities,
+    AgentCard,
+    AgentRef,
+    AgentSkill,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    Message,
+    RemoteSpec,
+    TextPart,
+)
+from .resolver import SpecialistResolver
+from .specialist import LocalSpecialist, RemoteSpecialist, Specialist
+
+__all__ = [
+    "AgentCapabilities",
+    "AgentCard",
+    "AgentRef",
+    "AgentSkill",
+    "HttpxTransport",
+    "JsonRpcRequest",
+    "JsonRpcResponse",
+    "LocalSpecialist",
+    "Message",
+    "RemoteA2aAgent",
+    "RemoteSpec",
+    "RemoteSpecialist",
+    "Specialist",
+    "SpecialistResolver",
+    "TextPart",
+    "agent_ref_from_member",
+    "build_agent_card",
+]

agentship_core-0.0.1/src/agentship/a2a/bridge.py

@@ -0,0 +1,44 @@
+"""Bridge the authoring layer (``MemberSpec``) to a resolvable ``AgentRef`` (§C3 connective tissue).
+
+The authoring-side blocks live in :mod:`agentship.spec` (so a spec parses with the interop layer
+absent); the resolver consumes :class:`~agentship.a2a.models.AgentRef`. This module's
+:func:`agent_ref_from_member` is the one-call translation, so a multi-agent builder treats a remote
+member and an in-process one identically — mapping each to an ``AgentRef`` and letting the resolver
+pick the transport. Kept here (a2a → spec is a one-way import) rather than in ``spec`` so the spec
+module never depends on the optional interop package.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..errors import CapabilityError
+from .models import A2AAuthConfig, AgentRef, RemoteSpec
+
+if TYPE_CHECKING:
+    from ..spec import MemberSpec
+
+
+def agent_ref_from_member(member: MemberSpec) -> AgentRef:
+    """Map one declared team ``member`` onto the ``AgentRef`` the resolver understands.
+
+    A member with an ``a2a`` block becomes a **remote** ref (its URL/auth/timeout carried across); a
+    referenced (``ref``) or inline (``prompt``) member becomes a **local** ref keyed by the member
+    name — the registry key its sub-agent registers under. A member declaring no resolvable target
+    is a :class:`CapabilityError`, matching the "declare exactly one way" spec rule.
+    """
+    if member.a2a is not None:
+        auth = A2AAuthConfig(**member.a2a.auth.model_dump())
+        remote = RemoteSpec(
+            url=member.a2a.url,
+            card_path=member.a2a.card_path,
+            auth=auth,
+            timeout_seconds=member.a2a.timeout_seconds,
+        )
+        return AgentRef(name=member.name, remote=remote)
+    if member.ref is not None or member.prompt is not None:
+        return AgentRef(name=member.name, local_ref=member.name)
+    raise CapabilityError(
+        f"member {member.name!r} declares no resolvable target — cannot resolve it as a "
+        f"specialist; give it a ref, a prompt, or an a2a block"
+    )

agentship_core-0.0.1/src/agentship/a2a/card.py

@@ -0,0 +1,86 @@
+"""Generate an A2A Agent Card from an ``AgentSpec`` + the engine's real capabilities (§C4).
+
+The author never writes a card by hand. :func:`build_agent_card` reads the declarative spec and
+the engine's :class:`~agentship.engines.base.EngineCapabilities`, so every claim on the card is
+one the agent can actually honour — ``streaming`` is true only when the engine streams, the
+advertised ``securitySchemes`` are exactly the ones the service enforces. That "declare, don't
+fake" honesty is the whole point of generating rather than hand-writing (DESIGN §3 honesty).
+"""
+
+from __future__ import annotations
+
+from ..engines.base import EngineCapabilities
+from ..spec import A2aOAuth2Spec, AgentSpec
+from .models import (
+    AgentCapabilities,
+    AgentCard,
+    ClientCredentialsFlow,
+    OAuthFlows,
+    SecurityScheme,
+)
+
+#: Human-readable descriptions for the auth schemes an agent can advertise. The card names the
+#: scheme; the service enforces exactly this set (they come from one config, so they can't drift).
+_SECURITY_SCHEME_DESCRIPTIONS = {
+    "oauth2": "OAuth 2.0 bearer token (client-credentials flow).",
+    "apiKey": "Static API key in the X-API-Key header.",
+    "mtls": "Mutual TLS — a client certificate verified at the ingress.",
+}
+
+
+def _security_scheme(name: str, oauth2: A2aOAuth2Spec | None) -> SecurityScheme:
+    """Build the advertised :class:`SecurityScheme` for one scheme name in its A2A-conformant shape.
+
+    Each A2A scheme ``type`` needs different fields: ``apiKey`` must declare *where* the key travels
+    (``in: header``, ``name: X-API-Key``); ``oauth2`` must carry ``flows`` (we advertise the
+    client-credentials flow from ``oauth2`` config, or empty flows when none is given); and the
+    ``mtls`` scheme's A2A ``type`` is spelled ``mutualTLS``. The dict key stays the author's name
+    (``mtls``), only the emitted ``type`` differs.
+    """
+    description = _SECURITY_SCHEME_DESCRIPTIONS.get(name)
+    if name == "apiKey":
+        return SecurityScheme(
+            type="apiKey", name="X-API-Key", location="header", description=description
+        )
+    if name == "oauth2":
+        flows = OAuthFlows()
+        if oauth2 is not None:
+            flows = OAuthFlows(
+                client_credentials=ClientCredentialsFlow(
+                    token_url=oauth2.token_url, scopes=dict(oauth2.scopes)
+                )
+            )
+        return SecurityScheme(type="oauth2", description=description, flows=flows)
+    if name == "mtls":
+        return SecurityScheme(type="mutualTLS", description=description)
+    return SecurityScheme(type=name, description=description)
+
+
+def build_agent_card(
+    spec: AgentSpec,
+    capabilities: EngineCapabilities,
+    *,
+    base_url: str,
+    security: list[str] | None = None,
+    oauth2: A2aOAuth2Spec | None = None,
+) -> AgentCard:
+    """Build the A2A :class:`AgentCard` for ``spec`` served under ``base_url``.
+
+    ``base_url`` is the service root (e.g. ``https://host``); the card's ``url`` is the agent's
+    A2A endpoint ``{base_url}/a2a/{name}``. ``capabilities`` is the built engine's declared
+    capabilities — ``streaming`` on the card mirrors ``capabilities.streaming`` exactly, never the
+    spec's *request* to stream. ``security`` is the list of scheme names the agent enforces
+    (from its ``a2a.security`` block); each becomes both a ``securitySchemes`` entry and a
+    ``security`` requirement so the card advertises precisely what the inbound router checks.
+    ``oauth2`` supplies the token endpoint/scopes advertised on the ``oauth2`` scheme, when set.
+    """
+    root = base_url.rstrip("/")
+    schemes = {name: _security_scheme(name, oauth2) for name in (security or [])}
+    return AgentCard(
+        name=spec.name,
+        description=spec.prompt,
+        url=f"{root}/a2a/{spec.name}",
+        capabilities=AgentCapabilities(streaming=capabilities.streaming),
+        security_schemes=schemes,
+        security=[{name: []} for name in (security or [])],
+    )

agentship_core-0.0.1/src/agentship/a2a/client.py

@@ -0,0 +1,86 @@
+"""The A2A client: send ``message/send`` to a remote agent over a pluggable transport (§C3/C6).
+
+:class:`RemoteA2aAgent` speaks the client side of A2A — it builds the JSON-RPC envelope, attaches
+the outbound credential + tenant/trace headers, hands the request to a :class:`A2ATransport`, and
+unwraps the agent's reply. The transport is an injection seam: production uses
+:class:`HttpxTransport` (a thin ``httpx.AsyncClient`` wrapper); tests pass a fake, so the client
+logic is exercised with no network. Any transport-level failure becomes a retryable
+:class:`~agentship.errors.A2AUnavailable` — the framework never silently swaps a remote for a local.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Protocol
+
+from ..context import RunContext
+from ..errors import A2AUnavailable, CapabilityError
+from .models import JsonRpcRequest, JsonRpcResponse, Message, RemoteSpec
+from .security import build_outbound_auth, propagation_headers
+
+
+class A2ATransport(Protocol):
+    """Carry one JSON-RPC call to ``url`` and return the parsed JSON response body."""
+
+    async def rpc(self, url: str, payload: dict, headers: dict) -> dict:  # noqa: D102 - stub
+        ...
+
+
+class HttpxTransport:
+    """The production transport: POST the JSON-RPC body with ``httpx`` (imported lazily)."""
+
+    def __init__(self, *, timeout_seconds: float = 60.0) -> None:
+        """Bind the per-call timeout; ``httpx`` is imported on first use so core stays light."""
+        self._timeout = timeout_seconds
+
+    async def rpc(self, url: str, payload: dict, headers: dict) -> dict:
+        """POST ``payload`` as JSON to ``url`` and return the decoded response body."""
+        import httpx
+
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            resp = await client.post(url, json=payload, headers=headers)
+            resp.raise_for_status()
+            return resp.json()
+
+
+class RemoteA2aAgent:
+    """A networked specialist reached over A2A, satisfying the same ``send`` port as a local one."""
+
+    def __init__(self, remote: RemoteSpec, *, transport: A2ATransport) -> None:
+        """Bind the remote's location/auth and the transport that carries calls to it."""
+        self._remote = remote
+        self._transport = transport
+        self._auth = build_outbound_auth(remote.auth)
+
+    async def send(self, text: str, ctx: RunContext) -> str:
+        """Send one ``message/send`` turn and return the remote agent's text reply.
+
+        Builds the JSON-RPC envelope, layers the credential over the tenant/trace headers, and
+        unwraps the result Message. A transport failure or a JSON-RPC error becomes
+        :class:`A2AUnavailable` (retryable) / :class:`CapabilityError` respectively.
+        """
+        request = JsonRpcRequest(
+            id=uuid.uuid4().hex,
+            method="message/send",
+            params={"message": Message.user(text).model_dump(by_alias=True)},
+        )
+        headers = {**propagation_headers(ctx), **self._auth.headers(ctx)}
+        try:
+            raw = await self._transport.rpc(
+                self._remote.url, request.model_dump(by_alias=True), headers
+            )
+        except Exception as exc:  # noqa: BLE001 — any transport failure is a retryable A2A outage
+            raise A2AUnavailable(f"A2A call to {self._remote.url!r} failed: {exc}") from exc
+        return _unwrap(raw)
+
+
+def _unwrap(raw: dict[str, Any]) -> str:
+    """Turn a JSON-RPC response body into the agent's reply text, or raise on a protocol error."""
+    response = JsonRpcResponse.model_validate(raw)
+    if response.error is not None:
+        raise CapabilityError(
+            f"remote A2A agent returned error {response.error.code}: {response.error.message}"
+        )
+    result = response.result or {}
+    parts = result.get("parts") or []
+    return "".join(part.get("text", "") for part in parts if part.get("kind", "text") == "text")