agentplane-runtime 0.0.1__py3-none-any.whl

agentplane_runtime/llm.py

@@ -0,0 +1,121 @@
+"""OpenAI-compatible LLM access — always through a configured base URL (the gateway)."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+
+import httpx
+
+from agentplane_core import JsonSchema
+
+
+class LlmError(RuntimeError):
+    """Chat completion or embedding request failed."""
+
+
+class OpenAICompatibleClient:
+    """Minimal chat-completions + embeddings client (httpx, async, SSE streaming)."""
+
+    def __init__(self, base_url: str, api_key: str = "", *, timeout: float = 60.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+    def _chat_body(
+        self,
+        model: str,
+        prompt: str,
+        system_prompt: str,
+        structured_output: JsonSchema | None,
+        *,
+        stream: bool,
+    ) -> dict[str, object]:
+        messages: list[dict[str, object]] = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+        body: dict[str, object] = {"model": model, "messages": messages, "stream": stream}
+        if structured_output is not None:
+            body["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {"name": "structured_output", "schema": structured_output},
+            }
+        return body
+
+    async def complete(
+        self,
+        model: str,
+        prompt: str,
+        system_prompt: str = "",
+        structured_output: JsonSchema | None = None,
+    ) -> str:
+        body = self._chat_body(model, prompt, system_prompt, structured_output, stream=False)
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            response = await client.post(
+                f"{self._base_url}/chat/completions", json=body, headers=self._headers()
+            )
+        if response.status_code != httpx.codes.OK:
+            raise LlmError(f"chat completion failed: HTTP {response.status_code}")
+        try:
+            content = response.json()["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, ValueError) as exc:
+            raise LlmError(f"malformed chat completion response: {exc}") from exc
+        return str(content or "")
+
+    async def stream(
+        self,
+        model: str,
+        prompt: str,
+        system_prompt: str = "",
+        structured_output: JsonSchema | None = None,
+    ) -> AsyncIterator[str]:
+        """Yield content deltas from an SSE chat-completions stream."""
+        body = self._chat_body(model, prompt, system_prompt, structured_output, stream=True)
+        async with (
+            httpx.AsyncClient(timeout=self._timeout) as client,
+            client.stream(
+                "POST",
+                f"{self._base_url}/chat/completions",
+                json=body,
+                headers=self._headers(),
+            ) as response,
+        ):
+            if response.status_code != httpx.codes.OK:
+                raise LlmError(f"chat completion stream failed: HTTP {response.status_code}")
+            async for line in response.aiter_lines():
+                if not line.startswith("data:"):
+                    continue
+                data = line.removeprefix("data:").strip()
+                if data == "[DONE]":
+                    break
+                try:
+                    delta = json.loads(data)["choices"][0]["delta"].get("content")
+                except (KeyError, IndexError, ValueError):
+                    continue
+                if delta:
+                    yield str(delta)
+
+    async def embed(self, model: str, text: str) -> list[float]:
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            response = await client.post(
+                f"{self._base_url}/embeddings",
+                json={"model": model, "input": text},
+                headers=self._headers(),
+            )
+        if response.status_code != httpx.codes.OK:
+            raise LlmError(f"embedding failed: HTTP {response.status_code}")
+        try:
+            vector = response.json()["data"][0]["embedding"]
+        except (KeyError, IndexError, ValueError) as exc:
+            raise LlmError(f"malformed embeddings response: {exc}") from exc
+        return [float(v) for v in vector]
+
+
+__all__ = ["LlmError", "OpenAICompatibleClient"]

agentplane_runtime/registration.py

@@ -0,0 +1,145 @@
+"""Self-registration with the registry (SPEC §6.5).
+
+Registry unreachable -> log + retry with backoff; serving is NOT blocked by
+registry availability.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Coroutine
+from typing import Any
+from uuid import UUID
+
+from agentplane_core import (
+    FlowDefinition,
+    RegistryEntryCreate,
+    RegistryEntryPatch,
+    ToolCard,
+    ToolCardTool,
+)
+from agentplane_core.registry import Card
+from agentplane_runtime.serving import build_agent_card
+from agentplane_runtime.settings import RuntimeSettings
+from agentplane_sdk import AgentplaneError, ConflictError, RegistryClient
+
+logger = logging.getLogger(__name__)
+
+_RETRY_DELAYS_S = (1.0, 5.0, 15.0, 60.0)
+
+
+def build_card(defn: FlowDefinition, public_url: str) -> Card:
+    if defn.expose.kind == "mcp":
+        return ToolCard(
+            name=defn.name,
+            description=defn.description,
+            url=public_url,
+            tools=[
+                ToolCardTool(
+                    name=defn.expose.tool_name or defn.name.replace("-", "_"),
+                    description=defn.expose.tool_description or defn.description,
+                )
+            ],
+        )
+    return build_agent_card(defn, public_url)
+
+
+class RegistryRegistrar:
+    """Registers/deregisters deployed flows, with background retry."""
+
+    def __init__(self, settings: RuntimeSettings) -> None:
+        self._settings = settings
+        self._tasks: set[asyncio.Task[None]] = set()
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self._settings.registry_url)
+
+    def _client(self) -> RegistryClient:
+        token = self._settings.registry_token or None
+        return RegistryClient(self._settings.registry_url, token)
+
+    async def register(
+        self, defn: FlowDefinition, public_url: str, existing_id: UUID | None
+    ) -> UUID | None:
+        """One immediate attempt; on failure, retries continue in the background."""
+        if not self.enabled:
+            return None
+        try:
+            return await self._register_once(defn, public_url, existing_id)
+        except AgentplaneError as exc:
+            logger.warning("registry registration failed (%s); retrying in background", exc)
+            self._spawn(self._retry_register(defn, public_url, existing_id))
+            return existing_id
+
+    async def _register_once(
+        self, defn: FlowDefinition, public_url: str, existing_id: UUID | None
+    ) -> UUID:
+        card = build_card(defn, public_url)
+        kind = "mcp_server" if defn.expose.kind == "mcp" else "agent"
+        async with self._client() as client:
+            if existing_id is not None:
+                try:
+                    entry = await client.update(
+                        existing_id,
+                        RegistryEntryPatch(card=card, url=public_url, tags=list(defn.tags)),
+                    )
+                except AgentplaneError:
+                    entry = await client.register(
+                        RegistryEntryCreate(
+                            kind=kind, card=card, url=public_url, tags=list(defn.tags)
+                        )
+                    )
+                return entry.id
+            try:
+                entry = await client.register(
+                    RegistryEntryCreate(kind=kind, card=card, url=public_url, tags=list(defn.tags))
+                )
+            except ConflictError:
+                # entry exists from a previous run we lost track of; find + update
+                page = await client.search(defn.name, kind=kind, limit=200)
+                for candidate in page.items:
+                    if candidate.card_name == defn.name:
+                        return (
+                            await client.update(
+                                candidate.id,
+                                RegistryEntryPatch(card=card, url=public_url, tags=list(defn.tags)),
+                            )
+                        ).id
+                raise
+            return entry.id
+
+    async def _retry_register(
+        self, defn: FlowDefinition, public_url: str, existing_id: UUID | None
+    ) -> None:
+        for delay in _RETRY_DELAYS_S:
+            await asyncio.sleep(delay)
+            try:
+                await self._register_once(defn, public_url, existing_id)
+            except AgentplaneError as exc:
+                logger.warning("registry retry failed (%s)", exc)
+                continue
+            return
+        logger.error("giving up registering %s with the registry", defn.name)
+
+    async def deregister(self, registry_id: UUID | None) -> None:
+        if not self.enabled or registry_id is None:
+            return
+        try:
+            async with self._client() as client:
+                await client.delete(registry_id)
+        except AgentplaneError as exc:
+            logger.warning("registry deregistration failed (%s)", exc)
+
+    def _spawn(self, coro: Coroutine[Any, Any, None]) -> None:
+        task: asyncio.Task[None] = asyncio.create_task(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    async def shutdown(self) -> None:
+        for task in self._tasks:
+            task.cancel()
+
+
+__all__ = ["RegistryRegistrar", "build_card"]

agentplane_runtime/resources.py

@@ -0,0 +1,237 @@
+"""Resource service (SPEC §6.3): CRUD, write-only secrets, E022 dimension check."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+
+from pydantic import ValidationError
+from sqlalchemy import select
+
+from agentplane_core import (
+    FlowDefinition,
+    LlmCallNode,
+    McpToolNode,
+    Resource,
+    RetrievalNode,
+    SecretsProvider,
+    ValidationIssue,
+    ValidationResult,
+    VectorDBResource,
+)
+from agentplane_runtime.db import (
+    RESOURCE_ADAPTER,
+    Database,
+    DefinitionRow,
+    ResourceRow,
+    VersionRow,
+    load_definition,
+    load_resource,
+)
+from agentplane_runtime.vector import VectorDBError, reader_for
+
+_SECRET_FIELDS = ("api_key_secret", "dsn_secret", "auth_secret")
+
+
+class ResourceConflictError(Exception):
+    """Resource exists (create) or is still referenced (delete)."""
+
+
+class ResourceNotFoundError(Exception):
+    """No resource with that name."""
+
+
+class ResourceValidationError(Exception):
+    """Resource failed a stateful check (e.g. E022)."""
+
+    def __init__(self, result: ValidationResult) -> None:
+        super().__init__("resource validation failed")
+        self.result = result
+
+
+def secret_ref(resource_name: str, field: str) -> str:
+    return f"resource/{resource_name}/{field}"
+
+
+class ResourceService:
+    """Owns resource rows; secret values live only in the SecretsProvider."""
+
+    def __init__(self, db: Database, secrets: SecretsProvider) -> None:
+        self._db = db
+        self._secrets = secrets
+
+    async def _store_secrets(self, resource: Resource) -> Resource:
+        """Move secret values into the provider; keep placeholder refs in the row."""
+        data = RESOURCE_ADAPTER.dump_python(resource, mode="json", context={"reveal_secrets": True})
+        for field in _SECRET_FIELDS:
+            value = data.get(field)
+            if isinstance(value, str) and value:
+                await self._secrets.put(secret_ref(resource.name, field), value)
+                data[field] = secret_ref(resource.name, field)
+        return RESOURCE_ADAPTER.validate_python(data)
+
+    async def secret_value(self, resource_name: str, field: str) -> str:
+        return await self._secrets.get(secret_ref(resource_name, field))
+
+    async def check_collection_dimension(
+        self, resource: VectorDBResource, collection: str
+    ) -> ValidationIssue | None:
+        """E022 for a concrete collection (used by definition validation and create)."""
+        api_key, dsn = "", ""
+        try:
+            if resource.api_key_secret:
+                api_key = await self.secret_value(resource.name, "api_key_secret")
+            if resource.dsn_secret:
+                dsn = await self.secret_value(resource.name, "dsn_secret")
+        except KeyError:
+            pass
+        try:
+            reader = await reader_for(resource, api_key=api_key, dsn=dsn)
+            actual = await reader.collection_dimension(collection)
+        except VectorDBError:
+            return None  # unreachable — runtime errors surface at execution time
+        if actual != resource.embedding.dimension:
+            return ValidationIssue(
+                code="E022",
+                severity="error",
+                path=f"resources/{resource.name}/embedding/dimension",
+                message=(
+                    f"embedding dimension {resource.embedding.dimension} does not match "
+                    f"collection {collection!r} dimension {actual}"
+                ),
+            )
+        return None
+
+    async def create(self, resource: Resource, owner: str) -> Resource:
+        async with self._db.session() as session:
+            existing = await session.get(ResourceRow, resource.name)
+        if existing is not None:
+            raise ResourceConflictError(f"resource {resource.name!r} already exists")
+        stored = await self._store_secrets(resource)
+        now = datetime.now(UTC)
+        row = ResourceRow(
+            name=resource.name,
+            kind=resource.kind,
+            owner=owner,
+            config_json=json.dumps(
+                RESOURCE_ADAPTER.dump_python(stored, mode="json", context={"reveal_secrets": True})
+            ),
+            created_at=now,
+            updated_at=now,
+        )
+        async with self._db.session() as session, session.begin():
+            session.add(row)
+        return self._redacted(stored)
+
+    async def update(self, name: str, resource: Resource, owner: str) -> Resource:
+        if resource.name != name:
+            raise ResourceValidationError(
+                ValidationResult(
+                    valid=False,
+                    issues=[
+                        ValidationIssue(
+                            code="E011",
+                            severity="error",
+                            path="name",
+                            message="resource name cannot be changed",
+                        )
+                    ],
+                )
+            )
+        async with self._db.session() as session:
+            row = await session.get(ResourceRow, name)
+        if row is None:
+            raise ResourceNotFoundError(name)
+        stored = await self._store_secrets(resource)
+        async with self._db.session() as session, session.begin():
+            fresh = await session.get(ResourceRow, name)
+            if fresh is None:
+                raise ResourceNotFoundError(name)
+            fresh.config_json = json.dumps(
+                RESOURCE_ADAPTER.dump_python(stored, mode="json", context={"reveal_secrets": True})
+            )
+            fresh.updated_at = datetime.now(UTC)
+        return self._redacted(stored)
+
+    async def get(self, name: str) -> Resource:
+        async with self._db.session() as session:
+            row = await session.get(ResourceRow, name)
+        if row is None:
+            raise ResourceNotFoundError(name)
+        return self._redacted(load_resource(row))
+
+    async def get_raw(self, name: str) -> Resource:
+        """Resource with secret *refs* intact — engine-internal use only."""
+        async with self._db.session() as session:
+            row = await session.get(ResourceRow, name)
+        if row is None:
+            raise ResourceNotFoundError(name)
+        return load_resource(row)
+
+    async def list(self, kind: str | None = None) -> list[Resource]:
+        stmt = select(ResourceRow).order_by(ResourceRow.name)
+        if kind is not None:
+            stmt = stmt.where(ResourceRow.kind == kind)
+        async with self._db.session() as session:
+            rows = (await session.execute(stmt)).scalars().all()
+        return [self._redacted(load_resource(row)) for row in rows]
+
+    async def delete(self, name: str) -> None:
+        referencing = await self._referencing_definitions(name)
+        if referencing:
+            raise ResourceConflictError(
+                f"resource {name!r} is referenced by: {', '.join(sorted(referencing))}"
+            )
+        async with self._db.session() as session, session.begin():
+            row = await session.get(ResourceRow, name)
+            if row is None:
+                raise ResourceNotFoundError(name)
+            await session.delete(row)
+        for field in _SECRET_FIELDS:
+            await self._secrets.delete(secret_ref(name, field))
+
+    async def _referencing_definitions(self, resource_name: str) -> set[str]:
+        names: set[str] = set()
+        async with self._db.session() as session:
+            drafts = (await session.execute(select(DefinitionRow))).scalars().all()
+            versions = (await session.execute(select(VersionRow))).scalars().all()
+        for row in drafts:
+            if _references(load_definition(row.draft_json), resource_name):
+                names.add(row.name)
+        for version in versions:
+            if _references(load_definition(version.definition_json), resource_name):
+                names.add(version.name)
+        return names
+
+    @staticmethod
+    def _redacted(resource: Resource) -> Resource:
+        """Round-trip through the redacting serializer -> placeholders only."""
+        try:
+            return RESOURCE_ADAPTER.validate_python(
+                RESOURCE_ADAPTER.dump_python(resource, mode="json")
+            )
+        except ValidationError:  # pragma: no cover - placeholder always validates
+            return resource
+
+
+def _references(defn: FlowDefinition, resource_name: str) -> bool:
+    for node in defn.nodes:
+        match node:
+            case LlmCallNode() | RetrievalNode():
+                if node.config.resource == resource_name:
+                    return True
+            case McpToolNode():
+                if node.config.resource == resource_name:
+                    return True
+            case _:
+                pass
+    return False
+
+
+__all__ = [
+    "ResourceConflictError",
+    "ResourceNotFoundError",
+    "ResourceService",
+    "ResourceValidationError",
+    "secret_ref",
+]

agentplane_runtime/secrets.py

@@ -0,0 +1,45 @@
+"""Default SecretsProvider: Fernet-encrypted DB column (SPEC §3.3)."""
+
+from __future__ import annotations
+
+from cryptography.fernet import Fernet
+
+from agentplane_core import SecretsProvider
+from agentplane_runtime.db import Database, SecretRow
+
+
+class SecretNotFoundError(KeyError):
+    """No secret stored under the given ref."""
+
+
+class FernetSecretsProvider(SecretsProvider):
+    """Encrypts values with ``AGENTPLANE_RUNTIME_SECRET_KEY`` at rest."""
+
+    def __init__(self, db: Database, secret_key: str) -> None:
+        self._db = db
+        self._fernet = Fernet(secret_key.encode("ascii"))
+
+    async def put(self, ref: str, value: str) -> None:
+        ciphertext = self._fernet.encrypt(value.encode("utf-8")).decode("ascii")
+        async with self._db.session() as session, session.begin():
+            row = await session.get(SecretRow, ref)
+            if row is None:
+                session.add(SecretRow(ref=ref, ciphertext=ciphertext))
+            else:
+                row.ciphertext = ciphertext
+
+    async def get(self, ref: str) -> str:
+        async with self._db.session() as session:
+            row = await session.get(SecretRow, ref)
+        if row is None:
+            raise SecretNotFoundError(ref)
+        return self._fernet.decrypt(row.ciphertext.encode("ascii")).decode("utf-8")
+
+    async def delete(self, ref: str) -> None:
+        async with self._db.session() as session, session.begin():
+            row = await session.get(SecretRow, ref)
+            if row is not None:
+                await session.delete(row)
+
+
+__all__ = ["FernetSecretsProvider", "SecretNotFoundError"]