fakzed-server 0.1.0__py3-none-any.whl

fakzed_server/__init__.py

@@ -0,0 +1,26 @@
+"""Fakzed platform server: registry, REST/SSE API, auth, multi-tenancy."""
+
+from fakzed_server.app import FakzedServer
+from fakzed_server.auth import ApiKey, ApiKeyStore, Principal
+from fakzed_server.monitoring import MonitoringStore
+from fakzed_server.persistence import JsonStore
+from fakzed_server.registry import AgentRegistry, Registered
+from fakzed_server.runs import RunManager, RunRecord
+from fakzed_server.tenancy import Organization, Project, TenantStore, User
+
+__all__ = [
+    "FakzedServer",
+    "AgentRegistry",
+    "Registered",
+    "ApiKey",
+    "ApiKeyStore",
+    "Principal",
+    "MonitoringStore",
+    "JsonStore",
+    "RunManager",
+    "RunRecord",
+    "TenantStore",
+    "User",
+    "Organization",
+    "Project",
+]

fakzed_server/app.py

@@ -0,0 +1,427 @@
+"""The platform server: FastAPI app serving the shared agent registry.
+
+Endpoints:
+  - chat (REST + SSE streaming) against registered SDK objects
+  - HITL resume for paused runs
+  - background run management (create/query/cancel)
+  - monitoring (events/traces/metrics)
+  - tenancy (users/orgs/projects) and API-key issuance
+
+Auth: `X-API-Key` header; admin endpoints require an admin-role key.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from fastapi import Depends, FastAPI, Header, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+from fakzed import Agent
+from fakzed.storage import Storage
+from fakzed_server.auth import ApiKeyStore, Principal
+from fakzed_server.monitoring import MonitoringStore
+from fakzed_server.persistence import JsonStore
+from fakzed_server.registry import AgentRegistry, Registered
+from fakzed_server.runs import RunManager
+from fakzed_server.tenancy import TenantStore
+
+
+class ChatRequest(BaseModel):
+    """Body of a chat call: the message plus optional session context."""
+
+    message: str
+    session_id: str | None = None
+    context: dict[str, Any] | None = None
+    stop_after_tool_call: bool = False
+
+
+class RunRequest(BaseModel):
+    """Body of a background-run submission."""
+
+    agent: str
+    message: str
+    session_id: str | None = None
+
+
+class AgentPatch(BaseModel):
+    """Body of an agent-management update."""
+
+    enabled: bool | None = None
+
+
+class AgentCreate(BaseModel):
+    """Body of a platform-managed agent creation."""
+
+    name: str
+    model: str
+    description: str | None = None
+    instructions: str | None = None
+    project_id: str = "default"
+    api_key: str | None = None
+    base_url: str | None = None
+
+
+class TenantRequest(BaseModel):
+    """Body of a tenant create call."""
+
+    name: str
+    email: str | None = None
+    org_id: str | None = None
+
+
+class KeyRequest(BaseModel):
+    """Body of an API-key issuance call."""
+
+    name: str
+    user_id: str | None = None
+    role: str = "user"
+
+
+class FakzedServer:
+    """Wires registry/tenancy/auth/monitoring/persistence into a FastAPI app."""
+
+    def __init__(
+        self,
+        *,
+        title: str = "Fakzed Platform",
+        db_path: str | Path | None = None,
+        auth_enabled: bool = True,
+        admin_api_key: str | None = None,
+        storage: Storage | None = None,
+    ) -> None:
+        self.registry = AgentRegistry()
+        self.tenants = TenantStore()
+        self.auth = ApiKeyStore()
+        self.monitoring = MonitoringStore()
+        self.persistence = JsonStore(path=Path(db_path) if db_path else Path("fakzed_server.json"))
+        self.runs = RunManager(store=self.persistence)
+        self.runs.agent_factory = lambda name: self.registry.get(name).instance
+        self.auth_enabled = auth_enabled
+        self.storage = storage
+
+        if auth_enabled and admin_api_key:
+            self.auth.issue(name="bootstrap-admin", user_id="admin", role="admin")
+            # seed the caller-provided key with admin role (hash only)
+            self._seed_key(admin_api_key, "bootstrap-admin", "admin")
+
+        self.app = FastAPI(title=title)
+        self.app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],  # web UI runs on a different origin in dev
+            allow_credentials=False,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+        self._register_routes()
+
+    # -- setup helpers --------------------------------------------------------
+
+    def _seed_key(self, raw: str, name: str, user_id: str) -> None:
+        from fakzed_server.auth import ApiKey, hash_key
+
+        key_hash = hash_key(raw)
+        record = ApiKey(name=name, user_id=user_id, role="admin", key_hash=key_hash)
+        self.auth.keys[record.key_id] = record
+        self.auth._by_hash[key_hash] = record.key_id
+
+    def register(
+        self,
+        instance: Any,
+        *,
+        name: str | None = None,
+        project_id: str = "default",
+    ) -> Registered:
+        """Register an SDK object; attaches platform storage and observability."""
+        if self.storage is not None and getattr(instance, "storage", None) is None:
+            instance.storage = self.storage
+        if getattr(instance, "observer", None) is None:
+            instance.observer = self.monitoring.observer()
+        return self.registry.register(instance, name=name, project_id=project_id)
+
+    def create_app(self) -> FastAPI:
+        return self.app
+
+    # -- auth dependencies ----------------------------------------------------
+
+    def _require_api_key(self, x_api_key: str | None = Header(default=None)) -> Principal:
+        if not self.auth_enabled:
+            return Principal(user_id="anonymous", role="admin", key_id="none")
+        principal = self.auth.authenticate(x_api_key)
+        if principal is None:
+            raise HTTPException(status_code=401, detail="missing or invalid API key")
+        return principal
+
+    def _require_admin(self, x_api_key: str | None = Header(default=None)) -> Principal:
+        principal = self._require_api_key(x_api_key)
+        if principal.role != "admin":
+            raise HTTPException(status_code=403, detail="requires admin role")
+        return principal
+
+    # -- helpers ----------------------------------------------------------------
+
+    def _entry(self, name: str) -> Registered:
+        try:
+            return self.registry.get(name)
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc)) from exc
+
+    @staticmethod
+    def _response_payload(instance: Any, result: Any) -> dict[str, Any]:
+        payload = result.model_dump()
+        payload["session_id"] = getattr(instance, "session_id", None)
+        return payload
+
+    def _resolve_session(self, instance: Any, requested: str | None) -> None:
+        """Point the instance at a session (recovered from storage when set)."""
+        current = getattr(instance, "session_id", None)
+        if requested:
+            instance.session_id = requested
+        elif not current:
+            instance.session_id = uuid.uuid4().hex[:12]
+
+    # -- routes -----------------------------------------------------------------
+
+    def _register_routes(self) -> None:
+        app = self.app
+
+        @app.get("/healthz")
+        def healthz() -> dict[str, str]:
+            return {"status": "ok", "agents": str(len(self.registry.entries))}
+
+        # -- agents ------------------------------------------------------------
+
+        @app.post("/api/agents")
+        def create_agent(
+            request: AgentCreate,
+            principal: Principal = Depends(self._require_admin),
+        ) -> dict[str, Any]:
+            """Create and register a platform-managed agent from config."""
+            if request.name in self.registry.entries:
+                raise HTTPException(status_code=409, detail=f"agent '{request.name}' exists")
+            try:
+                from fakzed.model import create_model
+
+                extras: dict[str, Any] = {}
+                if request.api_key is not None:
+                    extras["api_key"] = request.api_key
+                if request.base_url is not None:
+                    extras["base_url"] = request.base_url
+                model = create_model(request.model, **extras)
+            except ValueError as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+            agent = Agent(
+                name=request.name,
+                description=request.description,
+                instructions=request.instructions,
+                model=model,
+            )
+            entry = self.register(agent, project_id=request.project_id)
+            return entry.model_dump(exclude={"instance"})
+
+        @app.get("/api/agents")
+        def list_agents(
+            principal: Principal = Depends(self._require_api_key),
+        ) -> list[dict[str, Any]]:
+            return [e.model_dump(exclude={"instance"}) for e in self.registry.list()]
+
+        @app.get("/api/agents/{name}")
+        def get_agent(
+            name: str, principal: Principal = Depends(self._require_api_key)
+        ) -> dict[str, Any]:
+            return self._entry(name).model_dump(exclude={"instance"})
+
+        @app.patch("/api/agents/{name}")
+        def patch_agent(
+            name: str,
+            patch: AgentPatch,
+            principal: Principal = Depends(self._require_admin),
+        ) -> dict[str, Any]:
+            entry = self._entry(name)
+            if patch.enabled is not None:
+                entry.enabled = patch.enabled
+            return entry.model_dump(exclude={"instance"})
+
+        @app.delete("/api/agents/{name}")
+        def delete_agent(
+            name: str, principal: Principal = Depends(self._require_admin)
+        ) -> dict[str, bool]:
+            return {"unregistered": self.registry.unregister(name)}
+
+        # -- chat --------------------------------------------------------------
+
+        @app.post("/api/agents/{name}/chat")
+        def chat(
+            name: str,
+            request: ChatRequest,
+            principal: Principal = Depends(self._require_api_key),
+        ) -> dict[str, Any]:
+            entry = self._entry(name)
+            with entry._lock:
+                instance = entry.instance
+                self._resolve_session(instance, request.session_id)
+                result = instance.run(
+                    request.message,
+                    context=request.context,
+                    stop_after_tool_call=request.stop_after_tool_call,
+                )
+            return self._response_payload(instance, result)
+
+        @app.post("/api/agents/{name}/chat/stream")
+        def chat_stream(
+            name: str, request: ChatRequest, principal: Principal = Depends(self._require_api_key)
+        ) -> StreamingResponse:
+            entry = self._entry(name)
+
+            def generate() -> Iterator[str]:
+                with entry._lock:
+                    instance = entry.instance
+                    self._resolve_session(instance, request.session_id)
+                    for event in instance.run_stream(request.message, context=request.context):
+                        data = self._response_payload(instance, event)
+                        yield f"data: {json.dumps(data, ensure_ascii=False, default=str)}\n\n"
+
+            return StreamingResponse(generate(), media_type="text/event-stream")
+
+        @app.post("/api/agents/{name}/resume")
+        def resume(
+            name: str, principal: Principal = Depends(self._require_api_key)
+        ) -> dict[str, Any]:
+            entry = self._entry(name)
+            with entry._lock:
+                result = entry.instance.resume()
+            return self._response_payload(entry.instance, result)
+
+        # -- sessions -----------------------------------------------------------
+
+        @app.get("/api/sessions/{session_id}")
+        def get_session(
+            session_id: str, principal: Principal = Depends(self._require_api_key)
+        ) -> dict[str, Any]:
+            for entry in self.registry.list():
+                storage = getattr(entry.instance, "storage", None)
+                if storage is None:
+                    continue
+                row = storage.read_session(session_id)
+                if row is not None:
+                    return row.model_dump()
+            raise HTTPException(status_code=404, detail="session not found")
+
+        # -- runs ----------------------------------------------------------------
+
+        @app.post("/api/runs")
+        def create_run(
+            request: RunRequest, principal: Principal = Depends(self._require_api_key)
+        ) -> dict[str, Any]:
+            self._entry(request.agent)  # 404 before submitting
+            record = self.runs.submit(request.agent, request.message, session_id=request.session_id)
+            return record.model_dump()
+
+        @app.get("/api/runs")
+        def list_runs(
+            principal: Principal = Depends(self._require_api_key),
+        ) -> list[dict[str, Any]]:
+            return [r.model_dump() for r in self.runs.list()]
+
+        @app.get("/api/runs/{run_id}")
+        def get_run(
+            run_id: str, principal: Principal = Depends(self._require_api_key)
+        ) -> dict[str, Any]:
+            record = self.runs.get(run_id)
+            if record is None:
+                raise HTTPException(status_code=404, detail="run not found")
+            return record.model_dump()
+
+        @app.post("/api/runs/{run_id}/cancel")
+        def cancel_run(
+            run_id: str, principal: Principal = Depends(self._require_api_key)
+        ) -> dict[str, bool]:
+            return {"cancelled": self.runs.cancel(run_id)}
+
+        # -- monitoring ------------------------------------------------------------
+
+        @app.get("/api/events")
+        def events(
+            principal: Principal = Depends(self._require_api_key),
+        ) -> list[dict[str, Any]]:
+            return [e.model_dump() for e in self.monitoring.recent_events()]
+
+        @app.get("/api/traces")
+        def traces(
+            principal: Principal = Depends(self._require_api_key),
+        ) -> list[dict[str, Any]]:
+            return [t.model_dump() for t in self.monitoring.traces()]
+
+        @app.get("/api/metrics/summary")
+        def metrics_summary(
+            principal: Principal = Depends(self._require_api_key),
+        ) -> dict:
+            return self.monitoring.summary()
+
+        # -- tenancy --------------------------------------------------------------
+
+        @app.post("/api/tenants/users")
+        def create_user(
+            request: TenantRequest,
+            principal: Principal = Depends(self._require_admin),
+        ) -> dict[str, Any]:
+            return self.tenants.create_user(request.name, email=request.email).model_dump()
+
+        @app.post("/api/tenants/orgs")
+        def create_org(
+            request: TenantRequest,
+            principal: Principal = Depends(self._require_admin),
+        ) -> dict[str, Any]:
+            return self.tenants.create_org(request.name, owner_id=principal.user_id).model_dump()
+
+        @app.get("/api/tenants/orgs")
+        def list_orgs(
+            principal: Principal = Depends(self._require_api_key),
+        ) -> list[dict[str, Any]]:
+            return [o.model_dump() for o in self.tenants.orgs.values()]
+
+        @app.post("/api/tenants/projects")
+        def create_project(
+            request: TenantRequest,
+            principal: Principal = Depends(self._require_admin),
+        ) -> dict[str, Any]:
+            org_id = request.org_id
+            if org_id is None:
+                orgs = self.tenants.orgs_of(principal.user_id)
+                if not orgs:
+                    raise HTTPException(status_code=400, detail="no organization; create one first")
+                org_id = orgs[0].org_id
+            return self.tenants.create_project(org_id, request.name).model_dump()
+
+        @app.get("/api/tenants/orgs/{org_id}/projects")
+        def list_projects(
+            org_id: str, principal: Principal = Depends(self._require_api_key)
+        ) -> list[dict[str, Any]]:
+            return [p.model_dump() for p in self.tenants.projects_of(org_id)]
+
+        # -- api keys ---------------------------------------------------------------
+
+        @app.post("/api/keys")
+        def issue_key(
+            request: KeyRequest,
+            principal: Principal = Depends(self._require_admin),
+        ) -> dict[str, Any]:
+            user_id = request.user_id or principal.user_id
+            raw, record = self.auth.issue(name=request.name, user_id=user_id, role=request.role)
+            payload = record.model_dump(exclude={"key_hash"})
+            payload["api_key"] = raw  # returned exactly once
+            return payload
+
+        @app.delete("/api/keys/{key_id}")
+        def revoke_key(
+            key_id: str, principal: Principal = Depends(self._require_admin)
+        ) -> dict[str, bool]:
+            return {"revoked": self.auth.revoke(key_id)}

fakzed_server/auth.py

@@ -0,0 +1,96 @@
+"""API key authentication and authorization for the platform API.
+
+Each API key belongs to a user and carries a role. Keys are verified via a
+FastAPI dependency that reads the `X-API-Key` header; endpoints opt into
+required roles with `require_role("admin")`-style guards.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import uuid
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field, PrivateAttr
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class ApiKey(BaseModel):
+    """A bearer credential: the raw key is issued once, then stored hashed."""
+
+    key_id: str = Field(default_factory=lambda: uuid.uuid4().hex[:12])
+    name: str
+    user_id: str
+    role: str = "user"  # user | admin
+    scopes: list[str] = Field(default_factory=list)
+    key_hash: str | None = None
+    created_at: datetime = Field(default_factory=_now)
+
+
+class Principal(BaseModel):
+    """The authenticated identity attached to a request."""
+
+    user_id: str
+    role: str
+    key_id: str
+    scopes: list[str] = Field(default_factory=list)
+
+
+def hash_key(raw: str) -> str:
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+class ApiKeyStore(BaseModel):
+    """Issues and verifies API keys; keys are only stored as hashes."""
+
+    keys: dict[str, ApiKey] = Field(default_factory=dict)
+    _by_hash: dict[str, str] = PrivateAttr(default_factory=dict)
+
+    def issue(
+        self,
+        *,
+        name: str,
+        user_id: str,
+        role: str = "user",
+        scopes: list[str] | None = None,
+    ) -> tuple[str, ApiKey]:
+        """Create a new key and return (raw_key, record). Store the hash only."""
+        raw = "fz_" + secrets.token_hex(24)
+        key_hash = hash_key(raw)
+        record = ApiKey(
+            name=name,
+            user_id=user_id,
+            role=role,
+            scopes=scopes or [],
+            key_hash=key_hash,
+        )
+        self.keys[record.key_id] = record
+        self._by_hash[key_hash] = record.key_id
+        return raw, record
+
+    def authenticate(self, raw: str | None) -> Principal | None:
+        """Resolve a raw key to a Principal, or None if invalid."""
+        if not raw:
+            return None
+        key_id = self._by_hash.get(hash_key(raw))
+        if key_id is None:
+            return None
+        record = self.keys[key_id]
+        return Principal(
+            user_id=record.user_id,
+            role=record.role,
+            key_id=record.key_id,
+            scopes=record.scopes,
+        )
+
+    def revoke(self, key_id: str) -> bool:
+        record = self.keys.pop(key_id, None)
+        if record is None:
+            return False
+        if record.key_hash is not None:
+            self._by_hash.pop(record.key_hash, None)
+        return True

fakzed_server/main.py

@@ -0,0 +1,31 @@
+"""CLI entry point: `uv run fakzed-server` starts the platform server."""
+
+from __future__ import annotations
+
+import argparse
+
+from fakzed_server.app import FakzedServer
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Fakzed platform server")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--db", default="fakzed_server.json", help="JSON persistence file")
+    parser.add_argument("--admin-key", default=None, help="bootstrap admin API key")
+    parser.add_argument("--no-auth", action="store_true", help="disable API-key auth")
+    args = parser.parse_args()
+
+    server = FakzedServer(
+        db_path=args.db,
+        auth_enabled=not args.no_auth,
+        admin_api_key=args.admin_key,
+    )
+
+    import uvicorn
+
+    uvicorn.run(server.app, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

fakzed_server/monitoring.py

@@ -0,0 +1,49 @@
+"""Tracing & monitoring: expose SDK observability backends over the API.
+
+The platform taps the same `EventBus`/`Tracer`/`MetricsCollector` the SDK
+uses, so one `RunObserver` shared with the served agents gives the server
+visibility into every run without a second instrumentation pass.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from fakzed.observability import (
+    EventBus,
+    MetricsCollector,
+    RunEvent,
+    RunObserver,
+    Trace,
+    Tracer,
+)
+
+
+class MonitoringStore(BaseModel):
+    """Aggregates platform-wide observability state and query helpers."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    event_bus: EventBus = Field(default_factory=EventBus)
+    tracer: Tracer = Field(default_factory=Tracer)
+    metrics: MetricsCollector = Field(default_factory=MetricsCollector)
+
+    def observer(self) -> RunObserver:
+        """A RunObserver wired to this store, attachable to served agents."""
+        return RunObserver(event_bus=self.event_bus, tracer=self.tracer, metrics=self.metrics)
+
+    def recent_events(self, limit: int = 200) -> list[RunEvent]:
+        return list(self.event_bus.history[-limit:])
+
+    def traces(self, limit: int = 20) -> list[Trace]:
+        return self.tracer.all_traces()[-limit:]
+
+    def summary(self) -> dict:
+        return self.metrics.summary().model_dump()
+
+    def cost_by_agent(self) -> dict[str, float]:
+        costs: dict[str, float] = {}
+        for run in self.metrics.all():
+            if run.agent_name:
+                costs[run.agent_name] = costs.get(run.agent_name, 0.0) + run.cost_usd
+        return costs

fakzed_server/persistence.py

@@ -0,0 +1,57 @@
+"""Platform-level persistence: run records and API keys survive restarts.
+
+A small JSON-file backend with a threading lock keeps the platform layer
+dependency-free while still restoring runs (status/results) and sessions
+across process restarts. Sessions themselves live in the SDK `Storage`
+backend the served agents are configured with.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, PrivateAttr
+
+
+class JsonStore(BaseModel):
+    """Append-friendly JSON persistence: a dict namespace on disk."""
+
+    path: Path
+    _lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)
+    _data: dict[str, Any] = PrivateAttr(default_factory=dict)
+
+    def model_post_init(self, _: Any) -> None:
+        if self.path.exists():
+            try:
+                with self.path.open(encoding="utf-8") as fh:
+                    self._data = json.load(fh)
+            except (json.JSONDecodeError, OSError):
+                self._data = {}
+
+    def put(self, key: str, value: Any) -> None:
+        with self._lock:
+            self._data[key] = value
+            self._flush()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        with self._lock:
+            return self._data.get(key, default)
+
+    def pop(self, key: str, default: Any = None) -> Any:
+        with self._lock:
+            value = self._data.pop(key, default)
+            self._flush()
+            return value
+
+    def all(self) -> dict[str, Any]:
+        with self._lock:
+            return dict(self._data)
+
+    def _flush(self) -> None:
+        tmp = self.path.with_suffix(self.path.suffix + ".tmp")
+        with tmp.open("w", encoding="utf-8") as fh:
+            json.dump(self._data, fh, ensure_ascii=False, default=str)
+        tmp.replace(self.path)

fakzed_server/registry.py

@@ -0,0 +1,90 @@
+"""Agent registry: a single place to register SDK objects on the platform.
+
+The same registration mechanism is shared between the SDK and the platform:
+an Agent (or Team/Workflow) created locally is `register`-ed here and then
+served over HTTP, while a `RemoteAgent` on the SDK side calls it back by name.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Protocol
+
+from pydantic import BaseModel, Field, PrivateAttr
+
+
+class Registered(BaseModel):
+    """Metadata for one registered SDK object."""
+
+    name: str
+    kind: str
+    description: str | None = None
+    project_id: str = "default"
+    enabled: bool = True
+    instance: Any = Field(exclude=True)
+
+    #: Serializes requests touching the instance (session state is mutable).
+    _lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)
+
+
+class RegistryEntry(Protocol):
+    """Minimal protocol any registrable SDK object must satisfy."""
+
+    name: str | None
+    description: str | None
+
+    def run(self, message: Any, **kwargs: Any) -> Any: ...
+    def arun(self, message: Any, **kwargs: Any) -> Any: ...
+    def resume(self) -> Any: ...
+    def aresume(self) -> Any: ...
+    def run_stream(self, message: Any, **kwargs: Any) -> Any: ...
+    def arun_stream(self, message: Any, **kwargs: Any) -> Any: ...
+
+
+class AgentRegistry(BaseModel):
+    """Name-addressed registry of SDK objects (Agent/Team/Workflow)."""
+
+    entries: dict[str, Registered] = Field(default_factory=dict)
+
+    def register(
+        self,
+        instance: Any,
+        *,
+        name: str | None = None,
+        project_id: str = "default",
+    ) -> Registered:
+        """Register an SDK object under `name` (defaults to instance.name).
+
+        Re-registering under the same name replaces the previous entry.
+        """
+        resolved = name or getattr(instance, "name", None)
+        if not resolved:
+            raise ValueError("register requires a name (set instance.name or pass name=)")
+        kind = type(instance).__name__
+        entry = Registered(
+            name=resolved,
+            kind=kind,
+            description=getattr(instance, "description", None),
+            project_id=project_id,
+            instance=instance,
+        )
+        self.entries[resolved] = entry
+        return entry
+
+    def get(self, name: str) -> Registered:
+        entry = self.entries.get(name)
+        if entry is None:
+            raise KeyError(f"no agent registered as '{name}'")
+        if not entry.enabled:
+            raise PermissionError(f"agent '{name}' is disabled")
+        return entry
+
+    def unregister(self, name: str) -> bool:
+        return self.entries.pop(name, None) is not None
+
+    def list(self, project_id: str | None = None) -> list[Registered]:
+        """List registered entries, optionally filtered by project."""
+        entries = list(self.entries.values())
+        if project_id is not None:
+            entries = [e for e in entries if e.project_id == project_id]
+        return entries

fakzed_server/runs.py

@@ -0,0 +1,109 @@
+"""Run management: long-running agent executions behind create/query/cancel.
+
+Reuses the SDK `BackgroundRunner` (thread pool + wait/cancel polling) so the
+platform inherits the same semantics as embedded usage. Run records are
+persisted via `JsonStore` and restored on restart.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from fakzed.runtime import BackgroundRunner
+
+
+class RunRecord(BaseModel):
+    """Persistable snapshot of a background run."""
+
+    run_id: str
+    agent: str
+    status: str
+    input: str | None = None
+    output: str | None = None
+    error: str | None = None
+
+
+class RunManager(BaseModel):
+    """Submits agent calls to a BackgroundRunner and persists the outcome."""
+
+    runner: BackgroundRunner = Field(default_factory=BackgroundRunner)
+    store: Any = Field(default=None, exclude=True)
+    agent_factory: Callable[[str], Any] | None = Field(default=None, exclude=True)
+
+    def submit(
+        self,
+        agent_name: str,
+        message: str,
+        *,
+        session_id: str | None = None,
+        stop_after_tool_call: bool = False,
+    ) -> RunRecord:
+        """Start a background run of a registered agent; returns the record."""
+        run_id = self.runner.submit(
+            lambda: self._call(agent_name, message, session_id, stop_after_tool_call)
+        )
+        record = RunRecord(run_id=run_id, agent=agent_name, status="pending", input=message)
+        self._persist(record)
+        return record
+
+    def _call(
+        self,
+        agent_name: str,
+        message: str,
+        session_id: str | None,
+        stop_after_tool_call: bool,
+    ) -> Any:
+        """Resolve the registered instance and run it in the worker thread."""
+        if self.agent_factory is None:
+            raise RuntimeError("RunManager.agent_factory is not wired")
+        instance = self.agent_factory(agent_name)
+        if session_id and getattr(instance, "session_id", None) is None:
+            instance.session_id = session_id
+        return instance.run(message, stop_after_tool_call=stop_after_tool_call)
+
+    def get(self, run_id: str) -> RunRecord | None:
+        """Return the current (in-memory) state of a run."""
+        run = self.runner.get(run_id)
+        record = self._persisted(run_id)
+        if run is None:
+            return record
+        if record is not None:
+            record.status = run.status.value
+            record.output = self._content_of(run.result)
+            record.error = run.error
+            self._persist(record)
+        return record
+
+    def wait(self, run_id: str, timeout: float = 300.0) -> RunRecord | None:
+        run = self.runner.wait(run_id, timeout=timeout)
+        if run is None:
+            return self._persisted(run_id)
+        record = self._persisted(run_id) or RunRecord(run_id=run_id, agent="?", status="running")
+        record.status = run.status.value
+        record.output = self._content_of(run.result)
+        record.error = run.error
+        self._persist(record)
+        return record
+
+    def cancel(self, run_id: str) -> bool:
+        return self.runner.cancel(run_id)
+
+    def list(self) -> list[RunRecord]:
+        records = [r for r in self.store.all().values() if isinstance(r, dict)]
+        return [RunRecord(**r) for r in records]
+
+    @staticmethod
+    def _content_of(result: Any) -> str | None:
+        content = getattr(result, "content", None)
+        return content if isinstance(content, str) else str(content) if content else None
+
+    def _persisted(self, run_id: str) -> RunRecord | None:
+        raw = self.store.get(run_id) if self.store is not None else None
+        return RunRecord(**raw) if isinstance(raw, dict) else None
+
+    def _persist(self, record: RunRecord) -> None:
+        if self.store is not None:
+            self.store.put(record.run_id, record.model_dump())

fakzed_server/tenancy.py

@@ -0,0 +1,99 @@
+"""Multi-tenancy: user / organization / project three-level data model.
+
+Tenant boundaries keep every registered agent, run, and API key scoped to a
+project owned by an organization; users get access through membership records.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class User(BaseModel):
+    """A platform user (identity holder for API keys)."""
+
+    user_id: str = Field(default_factory=_new_id)
+    name: str
+    email: str | None = None
+    created_at: datetime = Field(default_factory=_now)
+
+
+class Organization(BaseModel):
+    """An organization: a group of users with shared projects."""
+
+    org_id: str = Field(default_factory=_new_id)
+    name: str
+    created_at: datetime = Field(default_factory=_now)
+
+
+class Project(BaseModel):
+    """A project: the tenant scope agents, runs, and sessions belong to."""
+
+    project_id: str = Field(default_factory=_new_id)
+    org_id: str
+    name: str
+    created_at: datetime = Field(default_factory=_now)
+
+
+class Membership(BaseModel):
+    """A user's membership in an organization."""
+
+    user_id: str
+    org_id: str
+    role: str = "member"  # member | admin
+
+
+class TenantStore(BaseModel):
+    """In-memory tenant directory with create/list/join operations."""
+
+    users: dict[str, User] = Field(default_factory=dict)
+    orgs: dict[str, Organization] = Field(default_factory=dict)
+    projects: dict[str, Project] = Field(default_factory=dict)
+    memberships: list[Membership] = Field(default_factory=list)
+
+    def create_user(self, name: str, *, email: str | None = None) -> User:
+        user = User(name=name, email=email)
+        self.users[user.user_id] = user
+        return user
+
+    def create_org(self, name: str, *, owner_id: str) -> Organization:
+        org = Organization(name=name)
+        self.orgs[org.org_id] = org
+        self.memberships.append(Membership(user_id=owner_id, org_id=org.org_id, role="admin"))
+        return org
+
+    def create_project(self, org_id: str, name: str) -> Project:
+        if org_id not in self.orgs:
+            raise KeyError(f"unknown organization '{org_id}'")
+        project = Project(org_id=org_id, name=name)
+        self.projects[project.project_id] = project
+        return project
+
+    def add_member(self, org_id: str, user_id: str, role: str = "member") -> None:
+        if org_id not in self.orgs:
+            raise KeyError(f"unknown organization '{org_id}'")
+        self.memberships.append(Membership(user_id=user_id, org_id=org_id, role=role))
+
+    def projects_of(self, org_id: str) -> list[Project]:
+        return [p for p in self.projects.values() if p.org_id == org_id]
+
+    def orgs_of(self, user_id: str) -> list[Organization]:
+        ids = {m.org_id for m in self.memberships if m.user_id == user_id}
+        return [org for org in self.orgs.values() if org.org_id in ids]
+
+    def role_in(self, user_id: str, org_id: str) -> str | None:
+        for membership in self.memberships:
+            if membership.user_id == user_id and membership.org_id == org_id:
+                return membership.role
+        return None

fakzed_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: fakzed-server
+Version: 0.1.0
+Summary: Fakzed platform server: agent registry, REST/SSE API, auth, multi-tenancy, run management.
+Author: fakzed contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,framework,llm,platform,server
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: fakzed
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# fakzed-server
+
+The fakzed platform server: register agents once, call them from anywhere.
+
+- **Registry**: `register()` once, served over REST + SSE
+- **Auth**: API-key auth per agent, optional admin bootstrap key
+- **Multi-tenancy**: per-key tenancy with usage accounting
+- **Persistence**: JSON file or any `Storage` backend
+- **Observability**: `/health`, `/metrics` monitoring endpoints
+- **Remote SDK**: `RemoteAgent` mirrors the local `Agent` interface
+
+```bash
+uv add fakzed-server   # or: pip install fakzed-server
+
+fakzed-server --host 0.0.0.0 --port 8000 --admin-key <bootstrap-key>
+```
+
+```python
+import uvicorn
+
+from fakzed import Agent
+from fakzed_server import FakzedServer
+
+server = FakzedServer(admin_api_key="admin", db_path="agents.json")
+server.register(Agent(name="echo", model="deepseek:deepseek-chat"))
+uvicorn.run(server.app, host="127.0.0.1", port=8000)  # blocking
+```
+
+```python
+from fakzed import RemoteAgent
+
+remote = RemoteAgent(base_url="http://127.0.0.1:8000", agent_name="echo", api_key="admin")
+resp = remote.run("hello")
+print(resp.content)
+```
+
+See the monorepo [README](../../README.md) and [platform docs](../../docs/platform.md).

fakzed_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+fakzed_server/__init__.py,sha256=-9X3dr8G9D0zcReIgTBa4L1TDsWrjX-Y0PZs6w9S-ak,762
+fakzed_server/app.py,sha256=N_z-51Pp0ioGY5SAfMtWOmRuRYsGcBD01elPBeA-rC4,16724
+fakzed_server/auth.py,sha256=-QwPLqdFkuhPzTx2mqWGVQ_ZTw-3I0bF1W2AMuGGSpw,2866
+fakzed_server/main.py,sha256=n08Hp9gakyoFgpQPI9WowDSF42_rbmFlOMo5OJq4aJw,964
+fakzed_server/monitoring.py,sha256=kZ2JVwQ18JzHf8nAE7ssHcHSYa0TzjbAGcKSHGSCBXM,1672
+fakzed_server/persistence.py,sha256=K-4GrQDkT87AuHB8Wx5B7CTC9OJV9pJtyp_hJ9n1dck,1895
+fakzed_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fakzed_server/registry.py,sha256=sXl2QhTHhTnNjHRLThf7nRlwIQE54ozi723bzgBqnMo,3096
+fakzed_server/runs.py,sha256=n4zPNP_KUTp6bUWgguqhT9Hx6ZWrzog7gW1_q8A6ZPw,4012
+fakzed_server/tenancy.py,sha256=uc5KBmiGDo5yXACuPHOJ3Fdw5uODfVX8gY7jsLfR7sc,3369
+fakzed_server-0.1.0.dist-info/METADATA,sha256=w87Y4z3Iq8g9l7UbrDW1ee2Wtl6fElt8nA6azsIDdig,1838
+fakzed_server-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fakzed_server-0.1.0.dist-info/entry_points.txt,sha256=ZY0Ronq4gB0DAHJR82wSIWyMMspIf2GKREhCs1KCAp0,58
+fakzed_server-0.1.0.dist-info/licenses/LICENSE,sha256=gXW5og8O6NiiOnH4TJMiDbYB7GGwDHacdDEEmEEOZfY,1097
+fakzed_server-0.1.0.dist-info/RECORD,,

fakzed_server-0.1.0.dist-info/WHEEL

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

fakzed_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fakzed-server = fakzed_server.main:main

fakzed_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fakzed contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.