prismal-server 0.2.0__py3-none-any.whl

prismal_server/__init__.py

@@ -0,0 +1,15 @@
+"""prismal-server — reference host for the prismal engine.
+
+A thin FastAPI/ASGI process that boots the engine once and serves it over
+REST/SSE plus the inbound A2A endpoints. It orchestrates the engine through
+exactly four seams and reimplements none of its logic (see ``CLAUDE.md``).
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("prismal-server")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

prismal_server/app.py

@@ -0,0 +1,163 @@
+"""ASGI application factory and lifespan (RHB-01-03).
+
+``create_app()`` wires the ``RuntimeRegistry`` into the app, registers the
+centralized error mapping, and mounts the routers. The lifespan warms nothing by
+default (readiness composes on demand) and, on shutdown, ``aclose()``s every
+cached ``RuntimeContext`` (SPEC-RHB-LIF-001/002). The registry is injectable so
+tests can supply a fake built from ``build_test_runtime`` (SPEC-RHB-LIF-003).
+
+The module-level ``app = create_app()`` is the entry point for
+``uvicorn prismal_server.app:app``.
+
+Seam: composition — ``build_runtime`` (via ``deps.RuntimeRegistry``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+from fastapi import FastAPI
+from prismal.agents.graph import get_async_compiled_graph
+
+from prismal_server import __version__, openapi_examples
+from prismal_server.auth import AuthBackend, build_auth_backend
+from prismal_server.config import HostSettings, get_settings
+from prismal_server.deps import AgentCardBuilder, GraphFactory, RuntimeRegistry
+from prismal_server.errors import register_exception_handlers
+from prismal_server.fake import (
+    FakeGraph,
+    FakeHeaderMiddleware,
+    FakeSummaries,
+    fake_builder,
+)
+from prismal_server.routes import a2a, admin, agui, health, threads, usage, ws
+from prismal_server.usage.store import UsageStore, build_usage_store
+from prismal_server.usage.summary import RunSummaryLookup, default_run_summary
+
+
+async def _default_graph_factory(*, tool_provider: Any = None) -> Any:
+    """Obtain the compiled graph via the Execution seam."""
+    return await get_async_compiled_graph(tool_provider=tool_provider)
+
+
+def _default_agent_card_builder(
+    *,
+    org_id: str | None = None,
+    protocol_version: str | None = None,
+    settings: Any = None,
+) -> dict[str, Any]:
+    """Build the Agent Card via the A2A seam (camelCase wire form).
+
+    Imports are deferred and sourced only from ``prismal.a2a`` (the seam
+    re-exports the engine settings + capability map), so the host never reaches
+    past the A2A seam and module import stays independent of that re-export.
+    """
+    from prismal.a2a import (  # noqa: PLC0415 - deferred to keep import off the base path
+        DEFAULT_CAPABILITY_MAP,
+        build_agent_card,
+    )
+    from prismal.a2a import (
+        get_settings as get_engine_settings,
+    )
+
+    card = build_agent_card(
+        settings or get_engine_settings(),
+        DEFAULT_CAPABILITY_MAP,
+        org_id=org_id,
+        protocol_version=protocol_version,
+    )
+    return cast("dict[str, Any]", card.model_dump(by_alias=True))
+
+
+def _default_a2a_engine_settings() -> Any:
+    """Process engine settings for A2A routing (base URL, version, legacy)."""
+    from prismal.a2a import get_settings as get_engine_settings  # noqa: PLC0415
+
+    return get_engine_settings()
+
+
+def create_app(
+    *,
+    registry: RuntimeRegistry | None = None,
+    settings: HostSettings | None = None,
+    graph_factory: GraphFactory | None = None,
+    agent_card_builder: AgentCardBuilder | None = None,
+    auth_backend: AuthBackend | None = None,
+    usage_store: UsageStore | None = None,
+    run_summary: RunSummaryLookup | None = None,
+    a2a_engine_settings: Any = None,
+) -> FastAPI:
+    """Build the FastAPI app, optionally with injected seams (for tests)."""
+    settings = settings or get_settings()
+    if settings.host_fake_llm_mode:
+        # SPEC-RH2-FAK-001: engine test runtimes + the deterministic script.
+        summaries = FakeSummaries()
+
+        async def fake_graph_factory(*, tool_provider: Any = None) -> Any:
+            return FakeGraph(summaries)
+
+        registry = registry or RuntimeRegistry(settings, builder=fake_builder)
+        graph_factory = graph_factory or fake_graph_factory
+        run_summary = run_summary or summaries
+    registry = registry or RuntimeRegistry(settings)
+    graph_factory = graph_factory or _default_graph_factory
+    agent_card_builder = agent_card_builder or _default_agent_card_builder
+    auth_backend = auth_backend or build_auth_backend(settings)
+    usage_store = usage_store or build_usage_store(settings)
+    run_summary = run_summary or default_run_summary
+    a2a_engine_settings = a2a_engine_settings or _default_a2a_engine_settings()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        # Startup: registry is already on app.state (set below). Warming the
+        # default tenant is optional (SPEC-RHB-LIF-001 MAY) and left off so boot
+        # stays resilient; /readyz composes on demand.
+        try:
+            yield
+        finally:
+            # Shutdown: release every tenant runtime (SPEC-RHB-LIF-002).
+            await registry.aclose_all()
+            await usage_store.aclose()
+
+    app = FastAPI(
+        title="prismal-server",
+        version=__version__,
+        summary="Reference host for the prismal engine (REST · SSE · A2A).",
+        lifespan=lifespan,
+    )
+    # Eagerly available so ASGI clients that don't run lifespan still resolve it.
+    app.state.settings = settings
+    app.state.registry = registry
+    app.state.graph_factory = graph_factory
+    app.state.agent_card_builder = agent_card_builder
+    app.state.agent_card_cache = {}
+    app.state.auth_backend = auth_backend
+    app.state.usage_store = usage_store
+    app.state.run_summary = run_summary
+    app.state.a2a_engine_settings = a2a_engine_settings
+
+    register_exception_handlers(app)
+    openapi_examples.install(app)  # RH2-07-03: examples served verbatim
+    if settings.host_fake_llm_mode:
+        app.add_middleware(FakeHeaderMiddleware)  # SPEC-RH2-FAK-003
+    app.include_router(health.router)
+    app.include_router(threads.router)
+    app.include_router(a2a.router)
+    app.include_router(usage.router)
+    app.include_router(agui.router)
+    app.include_router(admin.router)  # 404 unless host_admin_enabled (ADM-001)
+    if settings.host_ws_enabled:  # SPEC-RH2-WSK-001
+        app.include_router(ws.router)
+    # Tenant-scoped A2A routes match `{base}/{tenant}`: registered last so every
+    # fixed route above wins (SPEC-RH2-A2A-003).
+    app.include_router(
+        a2a.tenant_router(
+            a2a.base_path(getattr(a2a_engine_settings, "a2a_base_url", None))
+        )
+    )
+    return app
+
+
+app = create_app()

prismal_server/auth/__init__.py

@@ -0,0 +1,125 @@
+"""Authentication seam (RHB-04-*).
+
+The host owns only *where the credential comes from on the wire*; the identity
+*mechanism* is engine-side. Backends implement :class:`AuthBackend` and resolve a
+request to an engine ``AgentIdentity`` (or ``None``). The backend is selected by
+``host_auth_backend`` (``none`` | ``bearer`` | ``oidc``) via
+:func:`build_auth_backend`, pluggable without touching the routes
+(SPEC-RHB-AUT-006).
+
+:func:`authenticate` applies the host's strict-mode policy (SPEC-RHB-AUT-005) and
+:func:`resolve_org_id` resolves the tenant (SPEC-RHB-TEN-001).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi import HTTPException, Request
+
+from prismal_server.auth.base import AuthBackend, extract_bearer_token
+from prismal_server.auth.bearer import BearerTokenBackend
+from prismal_server.auth.noauth import NoAuthBackend
+from prismal_server.auth.oidc import OidcAuthBackend
+from prismal_server.config import get_settings
+
+if TYPE_CHECKING:
+    from prismal.identity import AgentIdentity
+
+    from prismal_server.config import HostSettings
+
+__all__ = [
+    "AuthBackend",
+    "BearerTokenBackend",
+    "NoAuthBackend",
+    "OidcAuthBackend",
+    "authenticate",
+    "build_auth_backend",
+    "extract_bearer_token",
+    "resolve_org_id",
+]
+
+
+def build_auth_backend(settings: HostSettings) -> AuthBackend:
+    """Select the auth backend by config (SPEC-RHB-AUT-006).
+
+    The engine ``OidcIdentityProvider`` is constructed only when the ``oidc``
+    backend is chosen, so ``none``/``bearer`` hosts pay no OIDC setup cost.
+    """
+    if settings.host_auth_backend == "bearer":
+        return BearerTokenBackend(
+            static_tokens=settings.bearer_static_tokens,
+            agent_name=settings.dev_identity_agent_name,
+        )
+    if settings.host_auth_backend == "oidc":
+        return OidcAuthBackend()
+    return NoAuthBackend(
+        did=settings.dev_identity_did,
+        agent_name=settings.dev_identity_agent_name,
+    )
+
+
+async def authenticate(request: Request) -> AgentIdentity | None:
+    """Resolve the request identity, enforcing strict mode on protected routes.
+
+    Returns the resolved ``AgentIdentity`` (or ``None`` in non-strict mode). When
+    ``host_auth_strict`` and the request is unauthenticated, raises ``401``
+    (SPEC-RHB-AUT-005). Health routes never call this, so they stay public.
+    """
+    backend: AuthBackend = request.app.state.auth_backend
+    identity = await backend.resolve(request)
+    if identity is None and request.app.state.settings.host_auth_strict:
+        raise HTTPException(status_code=401, detail="authentication required")
+    return identity
+
+
+class ForbiddenTenant(Exception):
+    """The request names a tenant it may not use (HTTP 403 ``forbidden_tenant``)."""
+
+    def __init__(self) -> None:
+        super().__init__("the requested tenant is not available to this caller")
+
+
+def resolve_org_id(
+    request: Any, identity: AgentIdentity | None, *, for_read: bool = False
+) -> str | None:
+    """Resolve the tenant ``org_id`` (SPEC-RHB-TEN-001).
+
+    Order: the identity's ``org_id`` if present, else the ``X-Org-Id`` header,
+    else ``None`` (single-tenant).
+
+    WHERE per-tenant config is enabled (``host_tenant_config_dir``), tenants
+    carry their own gateway credentials, so tenant selection fails closed:
+
+    * an ``X-Org-Id`` that differs from the identity's ``org_id`` ⇒
+      :class:`ForbiddenTenant`;
+    * an ``X-Org-Id`` without an identity ``org_id`` is honoured only in local
+      development (``host_auth_backend="none"`` outside ``production``);
+      otherwise :class:`ForbiddenTenant` — never a silent fallback to the
+      process (operator) tenant.
+
+    ``for_read=True`` (usage, budget, admin reads) applies those fail-closed
+    rules even without tenant config: reading another org's records must never
+    be possible by just sending a header.
+    """
+    header: str | None = request.headers.get("X-Org-Id")
+    identity_org: str | None = identity.org_id if identity is not None else None
+    state = getattr(getattr(request, "app", None), "state", None)
+    settings = getattr(state, "settings", None) or get_settings()
+
+    if settings.host_tenant_config_dir is None and not for_read:
+        # v0.1 behaviour (SPEC-RHB-TEN-001).
+        return identity_org or header
+
+    if identity_org:
+        if header is not None and header != identity_org:
+            raise ForbiddenTenant()
+        return identity_org
+    if header is None:
+        return None
+    if (
+        settings.host_auth_backend == "none"
+        and settings.host_environment != "production"
+    ):
+        return header
+    raise ForbiddenTenant()

prismal_server/auth/base.py

@@ -0,0 +1,42 @@
+"""``AuthBackend`` protocol and shared credential parsing (RHB-04-01).
+
+A backend resolves an inbound request to an engine ``AgentIdentity`` (or ``None``
+when the request is unauthenticated). Per SPEC-RHB-AUT-001 ``resolve`` MUST NOT
+raise for an unauthenticated request — it returns ``None`` so the caller decides
+policy (public vs. strict).
+
+The host owns only *where the credential comes from on the wire*; the identity
+*mechanism* stays engine-side.
+
+Seam: identity — ``prismal.identity`` (``AgentIdentity`` / ``OidcIdentityProvider``).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from prismal.identity import AgentIdentity
+
+
+@runtime_checkable
+class AuthBackend(Protocol):
+    """Resolve a request to an ``AgentIdentity`` or ``None`` (never raising)."""
+
+    async def resolve(self, request: Any) -> AgentIdentity | None: ...
+
+
+def extract_bearer_token(request: Any) -> str | None:
+    """Return the ``Authorization: Bearer <token>`` value, or ``None``.
+
+    Tolerant by construction (SPEC-RHB-AUT-001): a missing header, a non-Bearer
+    scheme, or an empty token all yield ``None`` rather than raising.
+    """
+    header: str | None = request.headers.get("Authorization")
+    if not header:
+        return None
+    scheme, _, token = header.partition(" ")
+    token = token.strip()
+    if scheme.lower() != "bearer" or not token:
+        return None
+    return token

prismal_server/auth/bearer.py

@@ -0,0 +1,45 @@
+"""``BearerTokenBackend`` (RHB-04-03).
+
+Resolves an ``Authorization: Bearer <token>`` credential to an ``AgentIdentity``
+via a static token→DID map (SPEC-RHB-AUT-003). The configured tokens are
+``SecretStr`` so a raw token never surfaces in logs or responses; an unknown or
+absent token resolves to ``None`` (never raises, SPEC-RHB-AUT-001).
+
+The identity carries no ``org_id`` — tenant selection falls back to the
+``X-Org-Id`` header per SPEC-RHB-TEN-001.
+
+Seam: identity — ``prismal.identity.AgentIdentity``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from prismal.identity import DID, AgentIdentity
+from pydantic import SecretStr
+
+
+class BearerTokenBackend:
+    """Resolve a static bearer token to a fixed-DID identity."""
+
+    def __init__(
+        self,
+        *,
+        static_tokens: dict[str, SecretStr],
+        agent_name: str = "bearer-client",
+    ) -> None:
+        self._static_tokens = static_tokens
+        self._agent_name = agent_name
+
+    async def resolve(self, request: Any) -> AgentIdentity | None:
+        from prismal_server.auth.base import extract_bearer_token
+
+        token = extract_bearer_token(request)
+        if token is None:
+            return None
+        did = self._static_tokens.get(token)
+        if did is None:
+            return None
+        return AgentIdentity(
+            did=DID(did.get_secret_value()), agent_name=self._agent_name
+        )

prismal_server/auth/noauth.py

@@ -0,0 +1,24 @@
+"""``NoAuthBackend`` — dev default (RHB-04-02).
+
+Returns a fixed local ``AgentIdentity`` (configurable DID / agent_name) for every
+request, so a fresh clone boots usable with no credentials (SPEC-RHB-AUT-002).
+This is a development convenience; production hosts select ``bearer`` or ``oidc``.
+
+Seam: identity — ``prismal.identity.AgentIdentity``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from prismal.identity import DID, AgentIdentity
+
+
+class NoAuthBackend:
+    """Resolve every request to one fixed, configured identity."""
+
+    def __init__(self, *, did: str, agent_name: str) -> None:
+        self._identity = AgentIdentity(did=DID(did), agent_name=agent_name)
+
+    async def resolve(self, request: Any) -> AgentIdentity | None:
+        return self._identity

prismal_server/auth/oidc.py

@@ -0,0 +1,49 @@
+"""``OidcAuthBackend`` (RHB-04-04).
+
+Delegates token validation and identity resolution to the engine's
+``OidcIdentityProvider`` — the host performs no token crypto (SPEC-RHB-AUT-004).
+The bearer value is treated as the caller's DID; the engine provider verifies it
+and resolves the backing ``AgentIdentity``. Any provider error (or an
+unverifiable / unknown DID) resolves to ``None`` rather than raising
+(SPEC-RHB-AUT-001).
+
+The synchronous provider calls run in a worker thread so DID resolution never
+blocks the event loop.
+
+Seam: identity — ``prismal.identity.OidcIdentityProvider``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from prismal.identity import DID, AgentIdentity, OidcIdentityProvider
+
+logger = logging.getLogger(__name__)
+
+
+class OidcAuthBackend:
+    """Resolve a bearer DID via the engine OIDC identity provider."""
+
+    def __init__(self, *, provider: Any | None = None) -> None:
+        # Constructed lazily by the caller/factory; ``provider`` is injectable so
+        # tests supply a fake and never do real DID resolution.
+        self._provider = provider if provider is not None else OidcIdentityProvider()
+
+    async def resolve(self, request: Any) -> AgentIdentity | None:
+        from prismal_server.auth.base import extract_bearer_token
+
+        token = extract_bearer_token(request)
+        if token is None:
+            return None
+        did = DID(token)
+        try:
+            verified = await asyncio.to_thread(self._provider.verify, did)
+            if not verified:
+                return None
+            return await asyncio.to_thread(self._provider.resolve, did)
+        except Exception:  # never propagate — an auth failure is just ``None``
+            logger.warning("OIDC identity resolution failed", exc_info=True)
+            return None

prismal_server/config.py

@@ -0,0 +1,106 @@
+"""Host configuration (RHB-01-01).
+
+``HostSettings`` (pydantic-settings, prefix ``PRISMAL_SERVER_``) governs *host*
+concerns only — bind host/port, CORS, auth mode, SSE heartbeat, tenant cap.
+Engine configuration stays engine-side and is read by the engine via its own
+``ConfigSourcePort`` (SPEC-RHB-CFG-001); this class MUST NOT duplicate it.
+Secret-bearing values are ``SecretStr`` (SPEC-RHB-CFG-002).
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, SecretStr, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+AuthBackend = Literal["none", "bearer", "oidc"]
+HostEnvironment = Literal["development", "staging", "production"]
+SecretsBackend = Literal["file", "env"]
+UsageStoreKind = Literal["memory", "sqlite"]
+
+
+class HostSettings(BaseSettings):
+    """Host-only settings, populated from ``PRISMAL_SERVER_*`` env vars.
+
+    See ``SPEC.md`` §7 for the authoritative key table.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="PRISMAL_SERVER_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Bind
+    host: str = "0.0.0.0"
+    port: int = 8000
+    cors_origins: list[str] = []
+
+    # Auth seam (backends wired in Phase 4)
+    host_auth_backend: AuthBackend = "none"
+    host_auth_strict: bool = False
+    dev_identity_did: str = "did:key:zLocalDev"
+    dev_identity_agent_name: str = "local-dev"
+    # Static bearer tokens (token → DID) for the dev/bearer backend. Secret by
+    # construction so raw tokens never surface in logs or responses.
+    bearer_static_tokens: dict[str, SecretStr] = {}
+
+    # Streaming
+    sse_heartbeat_s: int = 15
+
+    # Multi-tenancy
+    host_max_tenants: int = 32
+
+    # Inbound A2A: gates route presence on the host (404 when off). The engine's
+    # own a2a_inbound_enabled / a2a_strict govern the handler and strictness.
+    a2a_enabled: bool = True
+
+    # ── Host v0.2 (SPEC-RH2 §10) ────────────────────────────────────────────
+    host_environment: HostEnvironment = "development"
+
+    # Per-tenant engine config (RH2-01): `<dir>/<org_id>/tenant.yaml` plus
+    # secrets from the selected backend. None ⇒ every tenant uses process config.
+    host_tenant_config_dir: Path | None = None
+    host_secrets_backend: SecretsBackend = "file"
+    # File backend root (`<dir>/<org_id>/<key>`). None ⇒
+    # `<host_tenant_config_dir>/<org_id>/secrets/<key>`.
+    host_secrets_dir: Path | None = None
+
+    # Usage persistence (RH2-02).
+    host_usage_store: UsageStoreKind = "memory"
+    host_usage_db_path: Path = Path("usage.db")
+    host_usage_retention_days: int = Field(default=90, ge=1)
+
+    # AG-UI host gate (RH2-03); the engine's agui_events_enabled is also required.
+    host_agui_enabled: bool = True
+
+    # WebSocket transport (RH2-05).
+    host_ws_enabled: bool = False
+    host_ws_max_message_bytes: int = Field(default=1_048_576, ge=1)
+
+    # Deterministic fake runtime for credential-free contract tests (RH2-06).
+    host_fake_llm_mode: bool = False
+
+    # Read-only admin endpoints (RH2-06).
+    host_admin_enabled: bool = False
+    host_admin_scope: str = Field(default="prismal:admin", min_length=1)
+
+    @model_validator(mode="after")
+    def _no_fake_llm_in_production(self) -> HostSettings:
+        # SPEC-RH2-FAK-001: a fake model must never answer production traffic.
+        if self.host_fake_llm_mode and self.host_environment == "production":
+            raise ValueError(
+                "host_fake_llm_mode cannot be enabled when "
+                "host_environment='production'"
+            )
+        return self
+
+
+@lru_cache
+def get_settings() -> HostSettings:
+    """Return a process-wide cached ``HostSettings`` instance."""
+    return HostSettings()