agentplane-registry 0.0.1__tar.gz

agentplane_registry-0.0.1/.gitignore

@@ -0,0 +1,34 @@
+# internal working documents — not part of the public repo
+CLAUDE.md
+SPEC.md
+.claude/
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# local databases and state
+*.db
+registry.db
+runtime.db
+
+# environments / secrets
+.env
+.env.*
+
+# editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

agentplane_registry-0.0.1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: agentplane-registry
+Version: 0.0.1
+Summary: agentplane discovery service (standalone-capable)
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: agentplane-core<0.1.0,>=0.0.1
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp==3.4.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
+Requires-Dist: opentelemetry-sdk>=1.27
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pyjwt[crypto]>=2.9
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Requires-Dist: pgvector>=0.3; extra == 'postgres'
+Provides-Extra: semantic
+Requires-Dist: numpy>=1.26; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# agentplane-registry
+
+Standalone-capable discovery service for A2A agents and MCP servers:
+register, tag, search (text + optional semantic), health-check.
+
+- Runs alone: SQLite by default, auth optional (generic OIDC, any issuer),
+  no calls to other agentplane services.
+- Extras: `agentplane-registry[semantic]` (numpy + embeddings via an
+  OpenAI-compatible endpoint), `[postgres]` (asyncpg). Without extras the
+  service degrades gracefully and announces features via `GET /capabilities`.
+- Stores **gateway URLs only**; private/internal hosts are rejected unless
+  `AGENTPLANE_REGISTRY_ALLOW_PRIVATE_URLS=true`.
+
+Run it:
+
+```
+uvicorn --factory agentplane_registry.app:create_app --port 8100
+```

agentplane_registry-0.0.1/README.md

@@ -0,0 +1,18 @@
+# agentplane-registry
+
+Standalone-capable discovery service for A2A agents and MCP servers:
+register, tag, search (text + optional semantic), health-check.
+
+- Runs alone: SQLite by default, auth optional (generic OIDC, any issuer),
+  no calls to other agentplane services.
+- Extras: `agentplane-registry[semantic]` (numpy + embeddings via an
+  OpenAI-compatible endpoint), `[postgres]` (asyncpg). Without extras the
+  service degrades gracefully and announces features via `GET /capabilities`.
+- Stores **gateway URLs only**; private/internal hosts are rejected unless
+  `AGENTPLANE_REGISTRY_ALLOW_PRIVATE_URLS=true`.
+
+Run it:
+
+```
+uvicorn --factory agentplane_registry.app:create_app --port 8100
+```

agentplane_registry-0.0.1/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "agentplane-registry"
+version = "0.0.1"
+description = "agentplane discovery service (standalone-capable)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "agentplane-core>=0.0.1,<0.1.0",
+    "fastapi>=0.115",
+    "sqlalchemy[asyncio]>=2.0.30",
+    "aiosqlite>=0.20",
+    "httpx>=0.27",
+    "pydantic-settings>=2.4",
+    "pyjwt[crypto]>=2.9",
+    # exact pin — fastmcp ships breaking changes in minor releases (CLAUDE.md)
+    "fastmcp==3.4.4",
+    "opentelemetry-api>=1.27",
+    "opentelemetry-sdk>=1.27",
+    "opentelemetry-exporter-otlp-proto-http>=1.27",
+    "uvicorn>=0.30",
+]
+
+[project.optional-dependencies]
+semantic = ["numpy>=1.26"]
+postgres = ["asyncpg>=0.29", "pgvector>=0.3"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentplane_registry"]
+
+[tool.uv.sources]
+agentplane-core = { workspace = true }

agentplane_registry-0.0.1/src/agentplane_registry/__init__.py

@@ -0,0 +1,8 @@
+"""agentplane-registry: standalone-capable discovery service."""
+
+from agentplane_registry.app import create_app
+from agentplane_registry.settings import REGISTRY_VERSION, RegistrySettings
+
+__version__ = REGISTRY_VERSION
+
+__all__ = ["REGISTRY_VERSION", "RegistrySettings", "create_app"]

agentplane_registry-0.0.1/src/agentplane_registry/api.py

@@ -0,0 +1,252 @@
+"""Registry REST API (SPEC §5.1), prefix ``/api/v1``."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response, status
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+
+from agentplane_core import (
+    Capabilities,
+    EntryKind,
+    HealthStatus,
+    Page,
+    RegistryEntry,
+    RegistryEntryCreate,
+    RegistryEntryPatch,
+    SearchQuery,
+    serialize_card,
+)
+from agentplane_registry.auth import Principal
+from agentplane_registry.db import Database, EntryRow, row_to_entry
+from agentplane_registry.search import RegistrySearch
+from agentplane_registry.settings import REGISTRY_VERSION, RegistrySettings
+from agentplane_registry.urlcheck import is_private_url
+
+
+@dataclass
+class RegistryState:
+    """Shared service state stored on the FastAPI app."""
+
+    db: Database
+    settings: RegistrySettings
+    search: RegistrySearch
+
+
+def _state(request: Request) -> RegistryState:
+    state: RegistryState = request.app.state.registry
+    return state
+
+
+async def _principal(request: Request) -> Principal:
+    principal: Principal = await request.app.state.authenticator.authenticate(request)
+    return principal
+
+
+State = Annotated[RegistryState, Depends(_state)]
+Caller = Annotated[Principal, Depends(_principal)]
+
+router = APIRouter(prefix="/api/v1")
+health_router = APIRouter()
+
+
+def _visible(row: EntryRow, caller: Principal, auth_mode: str) -> bool:
+    if auth_mode == "none" or caller.is_admin:
+        return True
+    return row.owner == caller.sub
+
+
+def _check_url(url: str, settings: RegistrySettings) -> None:
+    if not settings.allow_private_urls and is_private_url(url):
+        raise HTTPException(
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="url must be a public gateway URL (set ALLOW_PRIVATE_URLS to override)",
+        )
+
+
+@router.post("/agents", status_code=status.HTTP_201_CREATED, response_model=RegistryEntry)
+async def register_entry(body: RegistryEntryCreate, state: State, caller: Caller) -> RegistryEntry:
+    _check_url(body.url, state.settings)
+    now = datetime.now(UTC)
+    row = EntryRow(
+        id=str(uuid.uuid4()),
+        kind=body.kind,
+        name=body.card.name,
+        owner=caller.sub,
+        url=body.url,
+        card_json=_dump_card(body),
+        tags_json=list(body.tags),
+        status="starting",
+        created_at=now,
+        updated_at=now,
+    )
+    try:
+        async with state.db.session() as session, session.begin():
+            session.add(row)
+    except IntegrityError:
+        raise HTTPException(
+            status.HTTP_409_CONFLICT,
+            detail=f"entry named {body.card.name!r} already exists for this owner",
+        ) from None
+    entry = row_to_entry(row)
+    await state.search.index(entry)
+    return entry
+
+
+def _dump_card(body: RegistryEntryCreate | RegistryEntryPatch) -> str:
+    return json.dumps(serialize_card(body.card), sort_keys=True)
+
+
+@router.get("/agents", response_model=Page)
+async def list_entries(
+    state: State,
+    caller: Caller,
+    kind: Annotated[EntryKind | None, Query()] = None,
+    status_filter: Annotated[HealthStatus | None, Query(alias="status")] = None,
+    tags: Annotated[str, Query(description="comma-separated, AND semantics")] = "",
+    owner: Annotated[Literal["me", "all"], Query()] = "me",
+    limit: Annotated[int, Query(ge=1, le=200)] = 50,
+    offset: Annotated[int, Query(ge=0)] = 0,
+) -> Page:
+    if owner == "all" and state.settings.auth_mode == "oidc" and not caller.is_admin:
+        raise HTTPException(status.HTTP_403_FORBIDDEN, detail="owner=all requires admin")
+    stmt = select(EntryRow).order_by(EntryRow.created_at.desc())
+    count_stmt = select(func.count()).select_from(EntryRow)
+    if state.settings.auth_mode == "oidc" and owner == "me" and not caller.is_admin:
+        stmt = stmt.where(EntryRow.owner == caller.sub)
+        count_stmt = count_stmt.where(EntryRow.owner == caller.sub)
+    if kind is not None:
+        stmt = stmt.where(EntryRow.kind == kind)
+        count_stmt = count_stmt.where(EntryRow.kind == kind)
+    if status_filter is not None:
+        stmt = stmt.where(EntryRow.status == status_filter)
+        count_stmt = count_stmt.where(EntryRow.status == status_filter)
+
+    async with state.db.session() as session:
+        rows = (await session.execute(stmt)).scalars().all()
+
+    wanted_tags = {t.strip() for t in tags.split(",") if t.strip()}
+    entries = [
+        row_to_entry(row) for row in rows if not wanted_tags or wanted_tags <= set(row.tags_json)
+    ]
+    total = len(entries)
+    return Page(items=entries[offset : offset + limit], total=total, limit=limit, offset=offset)
+
+
+@router.get("/agents/search", response_model=Page)
+async def search_entries(
+    state: State,
+    caller: Caller,
+    response: Response,
+    q: Annotated[str, Query()] = "",
+    tags: Annotated[str, Query()] = "",
+    kind: Annotated[EntryKind | None, Query()] = None,
+    status_filter: Annotated[HealthStatus | None, Query(alias="status")] = None,
+    semantic: Annotated[bool, Query()] = False,
+    limit: Annotated[int, Query(ge=1, le=200)] = 50,
+    offset: Annotated[int, Query(ge=0)] = 0,
+) -> Page:
+    owner_filter: str | None = None
+    if state.settings.auth_mode == "oidc" and not caller.is_admin:
+        owner_filter = caller.sub
+    if semantic and not state.search.semantic_enabled:
+        response.headers["X-Degraded"] = "semantic"
+        semantic = False
+    query = SearchQuery(
+        q=q,
+        tags=[t.strip() for t in tags.split(",") if t.strip()],
+        kind=kind,
+        status=status_filter,
+        semantic=semantic,
+        owner=owner_filter,
+        limit=limit,
+        offset=offset,
+    )
+    return await state.search.search(query)
+
+
+@router.get("/agents/{entry_id}", response_model=RegistryEntry)
+async def get_entry(entry_id: uuid.UUID, state: State, caller: Caller) -> RegistryEntry:
+    row = await _load_visible(entry_id, state, caller)
+    return row_to_entry(row)
+
+
+async def _load_visible(entry_id: uuid.UUID, state: RegistryState, caller: Principal) -> EntryRow:
+    async with state.db.session() as session:
+        row = await session.get(EntryRow, str(entry_id))
+    if row is None or not _visible(row, caller, state.settings.auth_mode):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail="entry not found")
+    return row
+
+
+def _require_owner(row: EntryRow, caller: Principal, auth_mode: str) -> None:
+    if auth_mode == "oidc" and not caller.is_admin and row.owner != caller.sub:
+        raise HTTPException(status.HTTP_403_FORBIDDEN, detail="owner or admin required")
+
+
+@router.put("/agents/{entry_id}", response_model=RegistryEntry)
+async def update_entry(
+    entry_id: uuid.UUID, body: RegistryEntryPatch, state: State, caller: Caller
+) -> RegistryEntry:
+    row = await _load_visible(entry_id, state, caller)
+    _require_owner(row, caller, state.settings.auth_mode)
+    if body.url is not None:
+        _check_url(body.url, state.settings)
+    async with state.db.session() as session, session.begin():
+        fresh = await session.get(EntryRow, str(entry_id))
+        if fresh is None:
+            raise HTTPException(status.HTTP_404_NOT_FOUND, detail="entry not found")
+        if body.card is not None:
+            fresh.card_json = _dump_card(body)
+            fresh.name = body.card.name
+        if body.url is not None:
+            fresh.url = body.url
+        if body.tags is not None:
+            fresh.tags_json = list(body.tags)
+        fresh.updated_at = datetime.now(UTC)
+        row = fresh
+    entry = row_to_entry(row)
+    await state.search.index(entry)
+    return entry
+
+
+@router.delete("/agents/{entry_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_entry(entry_id: uuid.UUID, state: State, caller: Caller) -> None:
+    row = await _load_visible(entry_id, state, caller)
+    _require_owner(row, caller, state.settings.auth_mode)
+    async with state.db.session() as session, session.begin():
+        fresh = await session.get(EntryRow, str(entry_id))
+        if fresh is not None:
+            await session.delete(fresh)
+    await state.search.remove(entry_id)
+
+
+@router.get("/capabilities", response_model=Capabilities)
+async def capabilities(state: State) -> Capabilities:
+    return Capabilities(
+        semantic_search=state.search.semantic_enabled,
+        auth=state.settings.auth_mode,
+        version=REGISTRY_VERSION,
+    )
+
+
+@health_router.get("/healthz")
+async def healthz() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@health_router.get("/readyz")
+async def readyz(request: Request) -> dict[str, str]:
+    state: RegistryState = request.app.state.registry
+    async with state.db.session() as session:
+        await session.execute(select(1))
+    return {"status": "ready"}
+
+
+__all__ = ["RegistryState", "health_router", "router"]

agentplane_registry-0.0.1/src/agentplane_registry/app.py

@@ -0,0 +1,60 @@
+"""Registry app factory: standalone-capable, SQLite by default, auth optional."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from agentplane_registry.api import RegistryState, health_router, router
+from agentplane_registry.auth import Authenticator
+from agentplane_registry.db import Database
+from agentplane_registry.embeddings import EmbeddingsClient
+from agentplane_registry.health import HealthJob
+from agentplane_registry.search import RegistrySearch
+from agentplane_registry.settings import REGISTRY_VERSION, RegistrySettings
+from agentplane_registry.tracing import setup_tracing
+
+
+def create_app(settings: RegistrySettings | None = None, *, run_health_job: bool = True) -> FastAPI:
+    """Build the registry service; everything optional degrades gracefully."""
+    cfg = settings or RegistrySettings()
+    db = Database(cfg.db_url)
+    embeddings = (
+        EmbeddingsClient(cfg.embeddings_base_url, cfg.embeddings_model)
+        if cfg.embeddings_base_url and cfg.embeddings_model
+        else None
+    )
+    search = RegistrySearch(db, embeddings)
+    health_job = HealthJob(db, cfg)
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        await db.create_all()
+        if run_health_job:
+            health_job.start()
+        try:
+            yield
+        finally:
+            if run_health_job:
+                await health_job.stop()
+            await db.dispose()
+
+    app = FastAPI(title="agentplane-registry", version=REGISTRY_VERSION, lifespan=lifespan)
+    app.state.registry = RegistryState(db=db, settings=cfg, search=search)
+    app.state.authenticator = Authenticator(cfg)
+    app.state.health_job = health_job
+    app.include_router(router)
+    app.include_router(health_router)
+    setup_tracing(app, service_name="agentplane-registry")
+    return app
+
+
+def main() -> None:  # pragma: no cover - process entrypoint
+    import uvicorn  # noqa: PLC0415 - optional server dep, only needed for the entrypoint
+
+    uvicorn.run(create_app(), host="0.0.0.0", port=8100)
+
+
+__all__ = ["create_app", "main"]

agentplane_registry-0.0.1/src/agentplane_registry/auth.py

@@ -0,0 +1,139 @@
+"""Optional OIDC auth (SPEC §5.5): any issuer, JWKS cache, role mapping."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+import httpx
+import jwt
+from fastapi import HTTPException, Request, status
+from jwt.types import Options
+
+from agentplane_registry.settings import RegistrySettings
+
+
+@dataclass(frozen=True)
+class Principal:
+    """Authenticated caller."""
+
+    sub: str
+    roles: frozenset[str] = field(default_factory=frozenset)
+    is_admin: bool = False
+
+
+ANONYMOUS = Principal(sub="anonymous", roles=frozenset(), is_admin=False)
+
+
+def _claim_path(claims: dict[str, object], path: str) -> object:
+    value: object = claims
+    for part in path.split("."):
+        if not isinstance(value, dict):
+            return None
+        value = value.get(part)
+    return value
+
+
+class OidcValidator:
+    """Validates JWTs against a generic OIDC issuer (discovery + JWKS cache)."""
+
+    def __init__(
+        self,
+        issuer: str,
+        audience: str,
+        roles_claim: str,
+        admin_role: str,
+        *,
+        jwks_ttl_s: float = 300.0,
+    ) -> None:
+        self._issuer = issuer.rstrip("/")
+        self._audience = audience
+        self._roles_claim = roles_claim
+        self._admin_role = admin_role
+        self._jwks_ttl_s = jwks_ttl_s
+        self._jwks: dict[str, jwt.PyJWK] = {}
+        self._jwks_fetched_at = 0.0
+
+    async def _refresh_jwks(self) -> None:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            discovery = await client.get(f"{self._issuer}/.well-known/openid-configuration")
+            discovery.raise_for_status()
+            jwks_uri = discovery.json().get("jwks_uri")
+            if not isinstance(jwks_uri, str):
+                raise RuntimeError("issuer discovery returned no jwks_uri")
+            jwks_response = await client.get(jwks_uri)
+            jwks_response.raise_for_status()
+        keys = jwt.PyJWKSet.from_dict(jwks_response.json()).keys
+        self._jwks = {key.key_id: key for key in keys if key.key_id}
+        self._jwks_fetched_at = time.monotonic()
+
+    async def _key_for(self, kid: str) -> jwt.PyJWK:
+        stale = time.monotonic() - self._jwks_fetched_at > self._jwks_ttl_s
+        if kid not in self._jwks or stale:
+            await self._refresh_jwks()
+        key = self._jwks.get(kid)
+        if key is None:
+            raise jwt.InvalidTokenError(f"unknown key id {kid!r}")
+        return key
+
+    async def validate(self, token: str) -> Principal:
+        header = jwt.get_unverified_header(token)
+        kid = header.get("kid")
+        if not isinstance(kid, str):
+            raise jwt.InvalidTokenError("token has no kid header")
+        key = await self._key_for(kid)
+        options: Options = {"verify_aud": bool(self._audience)}
+        claims = jwt.decode(
+            token,
+            key=key.key,
+            algorithms=["RS256", "ES256"],
+            audience=self._audience or None,
+            issuer=self._issuer,
+            options=options,
+        )
+        roles_value = _claim_path(claims, self._roles_claim)
+        roles = (
+            frozenset(str(role) for role in roles_value)
+            if isinstance(roles_value, list)
+            else frozenset()
+        )
+        sub = claims.get("sub")
+        if not isinstance(sub, str) or not sub:
+            raise jwt.InvalidTokenError("token has no sub")
+        return Principal(sub=sub, roles=roles, is_admin=self._admin_role in roles)
+
+
+class Authenticator:
+    """Resolves the request principal according to AUTH_MODE."""
+
+    def __init__(self, settings: RegistrySettings) -> None:
+        self.mode = settings.auth_mode
+        self._validator: OidcValidator | None = None
+        if self.mode == "oidc":
+            if not settings.oidc_issuer:
+                raise RuntimeError("AUTH_MODE=oidc requires AGENTPLANE_REGISTRY_OIDC_ISSUER")
+            self._validator = OidcValidator(
+                settings.oidc_issuer,
+                settings.oidc_audience,
+                settings.roles_claim,
+                settings.admin_role,
+            )
+
+    async def authenticate(self, request: Request) -> Principal:
+        if self.mode == "none" or self._validator is None:
+            return ANONYMOUS
+        header = request.headers.get("Authorization", "")
+        scheme, _, token = header.partition(" ")
+        if scheme.lower() != "bearer" or not token:
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED, detail="missing bearer token")
+        try:
+            return await self._validator.validate(token)
+        except jwt.InvalidTokenError as exc:
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED, detail=str(exc)) from exc
+        except httpx.HTTPError as exc:
+            raise HTTPException(
+                status.HTTP_503_SERVICE_UNAVAILABLE, detail=f"issuer unreachable: {exc}"
+            ) from exc
+
+
+__all__ = ["ANONYMOUS", "Authenticator", "OidcValidator", "Principal"]