agentplane-registry 0.0.1__py3-none-any.whl

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/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/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/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"]

agentplane_registry/db.py

@@ -0,0 +1,137 @@
+"""Persistence layer (SPEC §5.2): SQLAlchemy async, SQLite by default."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import JSON, DateTime, Float, String, UniqueConstraint, select
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from agentplane_core import (
+    EntryKind,
+    HealthStatus,
+    JsonObject,
+    RegistryEntry,
+    serialize_card,
+)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class EntryRow(Base):
+    __tablename__ = "entries"
+    __table_args__ = (UniqueConstraint("owner", "name", name="uq_entries_owner_name"),)
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    kind: Mapped[str] = mapped_column(String(16), index=True)
+    name: Mapped[str] = mapped_column(String(255), index=True)
+    owner: Mapped[str] = mapped_column(String(255), index=True)
+    url: Mapped[str] = mapped_column(String(2048))
+    card_json: Mapped[str] = mapped_column(String)
+    tags_json: Mapped[list[str]] = mapped_column(JSON, default=list)
+    status: Mapped[str] = mapped_column(String(16), default="starting", index=True)
+    last_seen: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=_utcnow, onupdate=_utcnow
+    )
+
+
+class EntryEmbeddingRow(Base):
+    """Entry embedding vector.
+
+    SPEC §5.2 requires this table only under [semantic]+Postgres; we persist
+    JSON vectors on every backend so SQLite restarts do not re-embed, and use
+    an in-process numpy brute-force search (fine <= a few thousand entries).
+    """
+
+    __tablename__ = "entry_embeddings"
+
+    entry_id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    vector: Mapped[list[float]] = mapped_column(JSON)
+    norm: Mapped[float] = mapped_column(Float, default=1.0)
+
+
+def row_to_entry(row: EntryRow) -> RegistryEntry:
+    card: JsonObject = json.loads(row.card_json)
+    return RegistryEntry.model_validate(
+        {
+            "id": uuid.UUID(row.id),
+            "kind": row.kind,
+            "card": card,
+            "url": row.url,
+            "tags": list(row.tags_json),
+            "owner": row.owner,
+            "status": row.status,
+            "last_seen": row.last_seen,
+            "created_at": row.created_at,
+            "updated_at": row.updated_at,
+        }
+    )
+
+
+def entry_kind(value: str) -> EntryKind:
+    if value not in ("agent", "mcp_server"):
+        raise ValueError(f"invalid entry kind {value!r}")
+    return "agent" if value == "agent" else "mcp_server"
+
+
+def health_status(value: str) -> HealthStatus:
+    if value not in ("starting", "healthy", "unhealthy", "unknown"):
+        raise ValueError(f"invalid health status {value!r}")
+    result: HealthStatus = value  # type: ignore[assignment]  # narrowed by the check above
+    return result
+
+
+def card_to_json_str(entry: RegistryEntry) -> str:
+    return json.dumps(serialize_card(entry.card), sort_keys=True)
+
+
+class Database:
+    """Engine + session factory wrapper."""
+
+    def __init__(self, db_url: str) -> None:
+        self.engine: AsyncEngine = create_async_engine(db_url)
+        self.session_factory = async_sessionmaker(self.engine, expire_on_commit=False)
+
+    async def create_all(self) -> None:
+        async with self.engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+
+    async def dispose(self) -> None:
+        await self.engine.dispose()
+
+    def session(self) -> AsyncSession:
+        return self.session_factory()
+
+
+async def get_row(session: AsyncSession, entry_id: str) -> EntryRow | None:
+    result = await session.execute(select(EntryRow).where(EntryRow.id == entry_id))
+    return result.scalar_one_or_none()
+
+
+__all__ = [
+    "Base",
+    "Database",
+    "EntryEmbeddingRow",
+    "EntryRow",
+    "card_to_json_str",
+    "entry_kind",
+    "get_row",
+    "health_status",
+    "row_to_entry",
+]

agentplane_registry/embeddings.py

@@ -0,0 +1,42 @@
+"""Entry embeddings via an OpenAI-compatible /embeddings endpoint (SPEC §5.4)."""
+
+from __future__ import annotations
+
+import httpx
+
+from agentplane_core import RegistryEntry, ToolCard
+
+
+def embedding_text(entry: RegistryEntry) -> str:
+    """``f"{name}\\n{description}\\n" + skill descriptions`` (SPEC §5.4)."""
+    card = entry.card
+    if isinstance(card, ToolCard):
+        skills = [f"{tool.name} {tool.description}".strip() for tool in card.tools]
+        name, description = card.name, card.description
+    else:
+        skills = [f"{skill.name} {skill.description}".strip() for skill in card.skills]
+        name, description = card.name, card.description
+    return f"{name}\n{description}\n" + "\n".join(skills)
+
+
+class EmbeddingsClient:
+    """Minimal OpenAI-compatible embeddings client, pointed at the gateway."""
+
+    def __init__(self, base_url: str, model: str, *, timeout: float = 30.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self.model = model
+        self._timeout = timeout
+
+    async def embed(self, text: str) -> list[float]:
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            response = await client.post(
+                f"{self._base_url}/embeddings",
+                json={"model": self.model, "input": text},
+            )
+            response.raise_for_status()
+        data = response.json()["data"]
+        vector = data[0]["embedding"]
+        return [float(v) for v in vector]
+
+
+__all__ = ["EmbeddingsClient", "embedding_text"]

agentplane_registry/health.py

@@ -0,0 +1,158 @@
+"""Background health job (SPEC §5.3).
+
+Transitions ``starting -> healthy <-> unhealthy`` are made only here.
+Agents: fetch the agent card THROUGH the gateway (the stored URL *is* the
+gateway URL). MCP servers: ``tools/list`` via streamable HTTP when
+``HEALTH_MCP=true``, else ``unknown``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import random
+from datetime import UTC, datetime
+
+import httpx
+from sqlalchemy import select
+
+from agentplane_core import agent_card_from_dict
+from agentplane_registry.db import Database, EntryRow
+from agentplane_registry.settings import RegistrySettings
+
+logger = logging.getLogger(__name__)
+
+FAILURES_BEFORE_UNHEALTHY = 3
+STARTING_RETRY_DELAY_S = 5.0
+STARTING_RETRY_ATTEMPTS = 6
+
+
+async def check_agent(url: str, *, timeout: float) -> bool:
+    """2xx + parseable agent card -> healthy."""
+    card_url = url.rstrip("/") + "/.well-known/agent-card.json"
+    try:
+        async with httpx.AsyncClient(timeout=timeout, follow_redirects=True) as client:
+            response = await client.get(card_url)
+        if not response.is_success:
+            return False
+        agent_card_from_dict(response.json())
+    except Exception:
+        return False
+    return True
+
+
+async def check_mcp_server(url: str, *, timeout: float) -> bool:
+    """Initialize + tools/list via streamable HTTP (FastMCP client)."""
+    from fastmcp import Client  # noqa: PLC0415 - deferred: heavy import
+
+    try:
+        async with asyncio.timeout(timeout):
+            client = Client(url)
+            async with client:
+                await client.list_tools()
+    except Exception:
+        return False
+    return True
+
+
+class HealthJob:
+    """Periodic checker with fast retry for fresh ``starting`` entries."""
+
+    def __init__(self, db: Database, settings: RegistrySettings) -> None:
+        self._db = db
+        self._settings = settings
+        self._failures: dict[str, int] = {}
+        self._task: asyncio.Task[None] | None = None
+
+    def start(self) -> None:
+        self._task = asyncio.create_task(self._loop(), name="registry-health-job")
+
+    async def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+
+    async def _loop(self) -> None:
+        while True:
+            try:
+                await self.run_once()
+            except Exception:
+                logger.exception("health job pass failed")
+            interval = self._settings.health_interval_s
+            await asyncio.sleep(interval + random.uniform(0, interval * 0.1))
+
+    async def _check(self, row: EntryRow) -> bool | None:
+        """True/False = healthy/unhealthy signal; None = unknown (not checkable)."""
+        if row.kind == "agent":
+            return await check_agent(row.url, timeout=self._settings.health_timeout_s)
+        if self._settings.health_mcp:
+            return await check_mcp_server(row.url, timeout=self._settings.health_timeout_s)
+        return None
+
+    async def run_once(self) -> None:
+        """One health pass over all entries (checks run concurrently)."""
+        async with self._db.session() as session:
+            rows = (await session.execute(select(EntryRow))).scalars().all()
+        tasks = [
+            self._check_starting(row.id)
+            if row.status == "starting"
+            else self._check_and_apply(row.id)
+            for row in rows
+        ]
+        if tasks:
+            await asyncio.gather(*tasks)
+
+    async def _check_and_apply(self, entry_id: str) -> None:
+        await self._apply(entry_id, await self._check_row(entry_id))
+
+    async def _check_row(self, entry_id: str) -> bool | None:
+        async with self._db.session() as session:
+            row = await session.get(EntryRow, entry_id)
+        if row is None:
+            return None
+        return await self._check(row)
+
+    async def _check_starting(self, entry_id: str) -> None:
+        """Fast retry (5s x6) so fresh deployments turn healthy quickly."""
+        for attempt in range(STARTING_RETRY_ATTEMPTS):
+            healthy = await self._check_row(entry_id)
+            if healthy is None:
+                await self._set_status(entry_id, "unknown")
+                return
+            if healthy:
+                await self._set_status(entry_id, "healthy", touch_last_seen=True)
+                return
+            if attempt < STARTING_RETRY_ATTEMPTS - 1:
+                await asyncio.sleep(STARTING_RETRY_DELAY_S)
+        await self._set_status(entry_id, "unhealthy")
+
+    async def _apply(self, entry_id: str, healthy: bool | None) -> None:
+        if healthy is None:
+            await self._set_status(entry_id, "unknown")
+            self._failures.pop(entry_id, None)
+            return
+        if healthy:
+            self._failures.pop(entry_id, None)
+            await self._set_status(entry_id, "healthy", touch_last_seen=True)
+            return
+        failures = self._failures.get(entry_id, 0) + 1
+        self._failures[entry_id] = failures
+        if failures >= FAILURES_BEFORE_UNHEALTHY:
+            await self._set_status(entry_id, "unhealthy")
+
+    async def _set_status(
+        self, entry_id: str, status: str, *, touch_last_seen: bool = False
+    ) -> None:
+        async with self._db.session() as session, session.begin():
+            row = await session.get(EntryRow, entry_id)
+            if row is None:
+                return
+            row.status = status
+            if touch_last_seen:
+                row.last_seen = datetime.now(UTC)
+
+
+__all__ = ["HealthJob", "check_agent", "check_mcp_server"]

agentplane_registry/search.py

@@ -0,0 +1,159 @@
+"""Search backend (SPEC §5.1): text match + optional semantic with RRF merge.
+
+Text search: case-insensitive match over name, description and skill
+names/descriptions plus AND tag filter. Semantic search: cosine top-k over
+the entry embedding, merged with the text hits via reciprocal rank fusion.
+Without the ``[semantic]`` extra (numpy) or embeddings config, semantic
+requests silently degrade to text search (the API adds ``X-Degraded``).
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from importlib.util import find_spec
+from uuid import UUID
+
+from sqlalchemy import delete, select
+
+from agentplane_core import (
+    Page,
+    RegistryEntry,
+    SearchBackend,
+    SearchQuery,
+    ToolCard,
+)
+from agentplane_registry.db import Database, EntryEmbeddingRow, EntryRow, row_to_entry
+from agentplane_registry.embeddings import EmbeddingsClient, embedding_text
+
+logger = logging.getLogger(__name__)
+
+_RRF_K = 60  # standard reciprocal-rank-fusion constant
+
+
+def semantic_available() -> bool:
+    """The [semantic] extra is installed when numpy imports."""
+    return find_spec("numpy") is not None
+
+
+def _haystack(entry: RegistryEntry) -> str:
+    card = entry.card
+    parts = [card.name, card.description]
+    if isinstance(card, ToolCard):
+        parts += [f"{tool.name} {tool.description}" for tool in card.tools]
+    else:
+        parts += [f"{skill.name} {skill.description}" for skill in card.skills]
+    return "\n".join(parts).lower()
+
+
+def _matches(entry: RegistryEntry, query: SearchQuery) -> bool:
+    if query.tags and not set(query.tags) <= set(entry.tags):
+        return False
+    return not query.q or query.q.lower() in _haystack(entry)
+
+
+class RegistrySearch(SearchBackend):
+    """SQL-filtered text search with optional in-process semantic ranking."""
+
+    def __init__(self, db: Database, embeddings: EmbeddingsClient | None) -> None:
+        self._db = db
+        self._embeddings = embeddings
+
+    @property
+    def semantic_enabled(self) -> bool:
+        return self._embeddings is not None and semantic_available()
+
+    async def index(self, entry: RegistryEntry) -> None:
+        """(Re-)embed an entry; no-op without semantic support."""
+        if self._embeddings is None or not semantic_available():
+            return
+        try:
+            vector = await self._embeddings.embed(embedding_text(entry))
+        except Exception:
+            logger.warning("embedding failed for entry %s", entry.id, exc_info=True)
+            return
+        norm = math.sqrt(sum(v * v for v in vector)) or 1.0
+        async with self._db.session() as session, session.begin():
+            existing = await session.get(EntryEmbeddingRow, str(entry.id))
+            if existing is None:
+                session.add(EntryEmbeddingRow(entry_id=str(entry.id), vector=vector, norm=norm))
+            else:
+                existing.vector = vector
+                existing.norm = norm
+
+    async def remove(self, entry_id: UUID) -> None:
+        async with self._db.session() as session, session.begin():
+            await session.execute(
+                delete(EntryEmbeddingRow).where(EntryEmbeddingRow.entry_id == str(entry_id))
+            )
+
+    async def _load_candidates(self, query: SearchQuery) -> list[RegistryEntry]:
+        stmt = select(EntryRow).order_by(EntryRow.created_at.desc())
+        if query.kind is not None:
+            stmt = stmt.where(EntryRow.kind == query.kind)
+        if query.status is not None:
+            stmt = stmt.where(EntryRow.status == query.status)
+        if query.owner is not None:
+            stmt = stmt.where(EntryRow.owner == query.owner)
+        async with self._db.session() as session:
+            rows = (await session.execute(stmt)).scalars().all()
+        return [row_to_entry(row) for row in rows]
+
+    async def _semantic_ranking(self, query: SearchQuery) -> list[UUID]:
+        """Entry ids ranked by cosine similarity to the query embedding."""
+        if self._embeddings is None:
+            return []
+        query_vector = await self._embeddings.embed(query.q)
+        query_norm = math.sqrt(sum(v * v for v in query_vector)) or 1.0
+        async with self._db.session() as session:
+            rows = (await session.execute(select(EntryEmbeddingRow))).scalars().all()
+        if not rows:
+            return []
+        import numpy as np  # noqa: PLC0415 - [semantic] extra, imported only when present
+
+        matrix = np.array([row.vector for row in rows], dtype=np.float64)
+        norms = np.array([row.norm for row in rows], dtype=np.float64)
+        scores = (matrix @ np.array(query_vector)) / (norms * query_norm)
+        order = np.argsort(-scores)
+        return [UUID(rows[int(i)].entry_id) for i in order]
+
+    async def search(self, q: SearchQuery) -> Page:
+        candidates = await self._load_candidates(q)
+        text_hits = [entry for entry in candidates if _matches(entry, q)]
+
+        use_semantic = q.semantic and self.semantic_enabled and bool(q.q)
+        if use_semantic:
+            try:
+                semantic_ids = await self._semantic_ranking(q)
+            except Exception:
+                logger.warning("semantic search failed; degrading to text", exc_info=True)
+                semantic_ids = []
+            by_id = {entry.id: entry for entry in candidates if _matches_filters(entry, q)}
+            ranked = _rrf_merge(
+                [entry.id for entry in text_hits],
+                [entry_id for entry_id in semantic_ids if entry_id in by_id],
+            )
+            hits = [by_id[entry_id] for entry_id in ranked if entry_id in by_id]
+        else:
+            hits = text_hits
+
+        total = len(hits)
+        page_items = hits[q.offset : q.offset + q.limit]
+        return Page(items=page_items, total=total, limit=q.limit, offset=q.offset)
+
+
+def _matches_filters(entry: RegistryEntry, query: SearchQuery) -> bool:
+    """Tag filter only (semantic hits skip the text match but not the filters)."""
+    return not query.tags or set(query.tags) <= set(entry.tags)
+
+
+def _rrf_merge(first: list[UUID], second: list[UUID]) -> list[UUID]:
+    """Reciprocal rank fusion of two rankings."""
+    scores: dict[UUID, float] = {}
+    for ranking in (first, second):
+        for rank, entry_id in enumerate(ranking):
+            scores[entry_id] = scores.get(entry_id, 0.0) + 1.0 / (_RRF_K + rank + 1)
+    return sorted(scores, key=lambda entry_id: -scores[entry_id])
+
+
+__all__ = ["RegistrySearch", "semantic_available"]

agentplane_registry/settings.py

@@ -0,0 +1,29 @@
+"""Registry configuration (SPEC §7.2), env prefix ``AGENTPLANE_REGISTRY_``."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+REGISTRY_VERSION = "0.0.1"
+
+
+class RegistrySettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="AGENTPLANE_REGISTRY_", extra="ignore")
+
+    db_url: str = "sqlite+aiosqlite:///registry.db"
+    auth_mode: Literal["none", "oidc"] = "none"
+    oidc_issuer: str = ""
+    oidc_audience: str = ""
+    roles_claim: str = "realm_access.roles"
+    admin_role: str = "admin"
+    health_interval_s: float = 60.0
+    health_mcp: bool = True
+    health_timeout_s: float = 10.0
+    embeddings_base_url: str = ""
+    embeddings_model: str = ""
+    allow_private_urls: bool = False
+
+
+__all__ = ["REGISTRY_VERSION", "RegistrySettings"]

agentplane_registry/tracing.py

@@ -0,0 +1,52 @@
+"""OpenTelemetry wiring — OTLP endpoint is configuration, never a vendor SDK.
+
+Uses the standard ``OTEL_EXPORTER_OTLP_ENDPOINT`` variable; without it the
+no-op tracer provider stays active and nothing is exported.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Awaitable, Callable
+
+from fastapi import FastAPI, Request, Response
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace import Status, StatusCode
+
+
+def setup_tracing(app: FastAPI, *, service_name: str) -> None:
+    """Install an OTLP exporter (when configured) and a request span middleware."""
+    endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "")
+    if endpoint:
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import (  # noqa: PLC0415
+            OTLPSpanExporter,
+        )
+
+        provider = TracerProvider(resource=Resource.create({"service.name": service_name}))
+        provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+        trace.set_tracer_provider(provider)
+
+    tracer = trace.get_tracer(service_name)
+
+    @app.middleware("http")
+    async def _trace_requests(
+        request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        with tracer.start_as_current_span(
+            f"{request.method} {request.url.path}",
+            attributes={
+                "http.request.method": request.method,
+                "url.path": request.url.path,
+            },
+        ) as span:
+            response = await call_next(request)
+            span.set_attribute("http.response.status_code", response.status_code)
+            if response.status_code >= 500:  # noqa: PLR2004
+                span.set_status(Status(StatusCode.ERROR))
+            return response
+
+
+__all__ = ["setup_tracing"]

agentplane_registry/urlcheck.py

@@ -0,0 +1,32 @@
+"""Gateway-URL guard: reject private/internal hosts (SPEC §3.4).
+
+The registry stores gateway URLs only. Unless ``ALLOW_PRIVATE_URLS`` is set,
+URLs resolving to loopback/private/link-local hosts are refused so internal
+service addresses can never leak into the registry.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from urllib.parse import urlparse
+
+_PRIVATE_HOSTNAMES = {"localhost", "host.docker.internal"}
+_PRIVATE_SUFFIXES = (".local", ".internal", ".localdomain")
+
+
+def is_private_url(url: str) -> bool:
+    """True when the URL's host looks private/internal (best-effort, no DNS)."""
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        return True
+    host = parsed.hostname.lower()
+    if host in _PRIVATE_HOSTNAMES or host.endswith(_PRIVATE_SUFFIXES):
+        return True
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        return "." not in host  # bare docker-compose service names etc.
+    return address.is_private or address.is_loopback or address.is_link_local
+
+
+__all__ = ["is_private_url"]

agentplane_registry-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+agentplane_registry/__init__.py,sha256=Hpwnkn63lmalMkL94XP5zPfZu8SPJCP6A3bvmk2aaF0,287
+agentplane_registry/api.py,sha256=1m7TPwfrSU9BJUAeW9YhPdqcCDy0zKSb57oSQlkf9R0,8977
+agentplane_registry/app.py,sha256=lbp-NTiFm0vzwYXEKWZCgE0utysU8PU-If4QcHRgZSo,2170
+agentplane_registry/auth.py,sha256=5rz7721MyT_hGQNFgExc30Zd7CuonWbS5S2CjXnNQF8,4956
+agentplane_registry/db.py,sha256=OhsCa6XHO5ZbbncoghpKTEaJC8gxV5jQnbbtBzZZcrY,4226
+agentplane_registry/embeddings.py,sha256=X3LovdGR99D9-QC6hH_sSl0Nh7-BMEDBiUMDfF_9GRg,1518
+agentplane_registry/health.py,sha256=Z5AlbkVchtv_9kh18-yhiW2Ds6pY-4RTCCqH-NVgviM,5678
+agentplane_registry/search.py,sha256=72XuXui6Z6OIZLHp5BfBjns4QCg_w1c48bqLuuj8se4,6455
+agentplane_registry/settings.py,sha256=sZlIAPduAul5hwgxiA8GsLhkHfpD6gwL30lPrMnfvgY,848
+agentplane_registry/tracing.py,sha256=8Wzse1Se3U4m80W7OWuMB84MVaDuk43mci1dDf5OPmA,1949
+agentplane_registry/urlcheck.py,sha256=W4RxEid9pB1aGOZ0O1TPDCK01kwOCjq4gLUZWXfEwKs,1107
+agentplane_registry-0.0.1.dist-info/METADATA,sha256=levYmtG_9hyqrsiT5DHYlT0rjPuodc-RGFK3aYDV7E4,1555
+agentplane_registry-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agentplane_registry-0.0.1.dist-info/RECORD,,

agentplane_registry-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any