dynamic-subgraphs 0.1.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1 @@
+"""Dynamic Subgraphs — governed runtime for transient workflow graphs."""

app/api/__init__.py

@@ -0,0 +1,6 @@
+# app/api/__init__.py
+"""HTTP API (FastAPI) — thin layer over the supervisor."""
+
+from app.api.app import create_app
+
+__all__ = ["create_app"]

app/api/__main__.py

@@ -0,0 +1,18 @@
+# app/api/__main__.py
+"""`python -m app.api` -> run uvicorn."""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+
+def main() -> None:
+    host = os.environ.get("DS_HOST", "127.0.0.1")
+    port = int(os.environ.get("DS_PORT", "8000"))
+    uvicorn.run("app.api:create_app", host=host, port=port, factory=True)
+
+
+if __name__ == "__main__":
+    main()

app/api/app.py

@@ -0,0 +1,32 @@
+# app/api/app.py
+"""create_app() — wire settings, context, routers, error handlers."""
+
+from __future__ import annotations
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
+
+from app.api.deps import AppContext
+from app.api.errors import install_error_handlers
+from app.api.routers import chains, health, registry, runs
+from app.api.settings import ApiSettings
+
+
+def create_app(settings: ApiSettings | None = None) -> FastAPI:
+    load_dotenv()
+    settings = settings or ApiSettings.from_env()
+
+    app = FastAPI(title="Dynamic Subgraphs API", version="1.0.0")
+    app.state.context = AppContext.build(settings)
+
+    install_error_handlers(app)
+    app.include_router(health.router)
+    app.include_router(registry.router)
+    app.include_router(runs.router)
+    app.include_router(chains.router)
+
+    @app.on_event("shutdown")
+    def _shutdown() -> None:
+        app.state.context.jobs.shutdown()
+
+    return app

app/api/deps.py

@@ -0,0 +1,146 @@
+# app/api/deps.py
+"""App-wide context + per-request config resolution + auth."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fastapi import Request
+
+from app.api.errors import BadRequest, ServiceUnavailable, Unauthorized
+from app.api.jobs import JobStore
+from app.api.settings import ApiSettings
+from app.assembly import RunConfig, build_supervisor
+from app.recording import FileRecorder
+from app.runtime import (
+    MissingModelProviderCredential,
+    ProviderRegistry,
+    default_model_providers,
+)
+from app.supervisor import (
+    IterationDecider,
+    StatusIterationDecider,
+    Supervisor,
+    build_provider_iteration_decider,
+)
+
+
+@dataclass
+class AppContext:
+    settings: ApiSettings
+    recorder: FileRecorder
+    jobs: JobStore
+    checkpointer: object
+    model_providers: ProviderRegistry
+
+    @classmethod
+    def build(cls, settings: ApiSettings) -> AppContext:
+        from langgraph.checkpoint.memory import MemorySaver
+
+        return cls(
+            settings=settings,
+            recorder=FileRecorder(root_dir=settings.runs_dir, overwrite=True),
+            jobs=JobStore(max_workers=4),
+            checkpointer=MemorySaver(),
+            model_providers=default_model_providers(),
+        )
+
+    def supervisor_for(self, config: RunConfig) -> Supervisor:
+        return build_supervisor(
+            config,
+            recorder=self.recorder,
+            checkpointer=self.checkpointer,
+            model_providers=self.model_providers,
+        )
+
+
+def get_context(request: Request) -> AppContext:
+    return request.app.state.context
+
+
+def resolve_run_config(
+    ctx: AppContext,
+    *,
+    planner: str | None,
+    provider: str | None = None,
+    model: str | None,
+) -> RunConfig:
+    chosen_planner = planner or ctx.settings.planner
+    chosen_provider = (provider or ctx.settings.provider).strip().lower()
+    if chosen_planner == "openai":
+        chosen_planner = "llm"
+        chosen_provider = "openai"
+    chosen_model = model or ctx.settings.model
+
+    if not ctx.settings.is_model_allowed(chosen_model, provider=chosen_provider):
+        raise BadRequest(
+            f"Model {chosen_provider}:{chosen_model} is not in the allowlist "
+            f"{list(ctx.settings.model_allowlist)}"
+        )
+    config = RunConfig(
+        planner=chosen_planner,  # type: ignore[arg-type]
+        provider=chosen_provider,
+        model=chosen_model,
+        strict_runners=chosen_planner == "llm",
+    )
+    if config.planner == "llm":
+        try:
+            for provider_name in config.providers_in_use():
+                ctx.model_providers.require_credentials(provider_name)
+        except KeyError as exc:
+            raise BadRequest(str(exc)) from exc
+        except MissingModelProviderCredential as exc:
+            raise ServiceUnavailable(str(exc)) from exc
+    return config
+
+
+def resolve_chain_decider(
+    ctx: AppContext,
+    *,
+    config: RunConfig,
+    decider: str,
+    success_criteria: str | None,
+    judge_failed_runs: bool,
+) -> IterationDecider:
+    """Resolve the chain-level orchestration judge for `/chains`.
+
+    The status decider is token-free and remains the default. The LLM decider is
+    explicit because it makes an additional model call after each successful
+    iteration to decide whether to stop, replan, ask the user, or fail.
+    """
+
+    if decider == "status":
+        return StatusIterationDecider()
+
+    if decider == "llm":
+        if not ctx.settings.is_model_allowed(config.model, provider=config.provider):
+            raise BadRequest(
+                f"Model {config.provider}:{config.model} is not in the allowlist "
+                f"{list(ctx.settings.model_allowlist)}"
+            )
+        try:
+            ctx.model_providers.require_credentials(config.provider)
+            model_provider = ctx.model_providers.get(config.provider)
+        except KeyError as exc:
+            raise BadRequest(str(exc)) from exc
+        except MissingModelProviderCredential as exc:
+            raise ServiceUnavailable(str(exc)) from exc
+        return build_provider_iteration_decider(
+            model_provider,
+            config.model_ref,
+            success_criteria=success_criteria,
+            judge_failed_runs=judge_failed_runs,
+        )
+
+    raise BadRequest(f"Unknown chain decider {decider!r}")
+
+
+def require_auth(request: Request) -> None:
+    """Guard for POST endpoints. No-op when DS_API_KEY is unset."""
+    ctx: AppContext = request.app.state.context
+    expected = ctx.settings.api_key
+    if not expected:
+        return
+    header = request.headers.get("authorization", "")
+    if header != f"Bearer {expected}":
+        raise Unauthorized("Missing or invalid bearer token")

app/api/errors.py

@@ -0,0 +1,67 @@
+# app/api/errors.py
+"""API exceptions and JSON error-envelope handlers."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+
+class ApiError(Exception):
+    status_code = 500
+    error_type = "ApiError"
+
+    def __init__(self, message: str, *, detail: object = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+
+
+class NotFound(ApiError):
+    status_code = 404
+    error_type = "NotFound"
+
+
+class Conflict(ApiError):
+    status_code = 409
+    error_type = "Conflict"
+
+
+class Unauthorized(ApiError):
+    status_code = 401
+    error_type = "Unauthorized"
+
+
+class BadRequest(ApiError):
+    status_code = 400
+    error_type = "BadRequest"
+
+
+class ServiceUnavailable(ApiError):
+    status_code = 503
+    error_type = "ServiceUnavailable"
+
+
+def _envelope(error_type: str, message: str, detail: object = None) -> dict:
+    return {"error": {"type": error_type, "message": message, "detail": detail}}
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    @app.exception_handler(ApiError)
+    async def _handle_api_error(_: Request, exc: ApiError) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=_envelope(exc.error_type, exc.message, exc.detail),
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def _handle_validation(
+        _: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        return JSONResponse(
+            status_code=422,
+            content=_envelope(
+                "ValidationError", "Request validation failed", exc.errors()
+            ),
+        )

app/api/jobs.py

@@ -0,0 +1,136 @@
+# app/api/jobs.py
+"""In-process job store: background execution + subscribe bus.
+
+Every run/chain becomes a Job executed on a thread pool. The request handler
+decides how long to wait (sync/async/auto). The subscribe bus feeds SSE today;
+it is the seam where per-node events will publish later.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from datetime import UTC, datetime
+from enum import StrEnum
+from queue import Queue
+from typing import Any
+
+_TERMINAL: frozenset[str] = frozenset({"ok", "failed", "paused"})
+
+
+class JobState(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    OK = "ok"
+    FAILED = "failed"
+    PAUSED = "paused"
+
+
+class JobExistsError(Exception):
+    def __init__(self, run_id: str) -> None:
+        super().__init__(f"Job already exists: {run_id!r}")
+        self.run_id = run_id
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+class Job:
+    """Mutable, thread-safe handle for one background run/chain."""
+
+    def __init__(self, run_id: str, kind: str) -> None:
+        self.run_id = run_id
+        self.kind = kind
+        self.state: JobState = JobState.QUEUED
+        self.submitted_at: datetime = _now()
+        self.started_at: datetime | None = None
+        self.finished_at: datetime | None = None
+        self.result: Any = None
+        self.error: str | None = None
+        self.budget_wall_seconds: int | None = None
+        self._lock = threading.Lock()
+        self._done = threading.Event()
+        self._subscribers: list[Queue[dict[str, Any]]] = []
+
+    def _publish(self, msg: dict[str, Any]) -> None:
+        for q in self._subscribers:
+            q.put(msg)
+
+    def set_state(self, state: JobState) -> None:
+        with self._lock:
+            self.state = state
+            if state == JobState.RUNNING and self.started_at is None:
+                self.started_at = _now()
+            self._publish({"type": "status", "state": state.value})
+
+    def complete(self, *, result: Any, state: JobState) -> None:
+        with self._lock:
+            self.result = result
+            self.state = state
+            self.finished_at = _now()
+            self._publish({"type": "status", "state": state.value})
+            self._publish({"type": "__end__"})
+            self._subscribers.clear()
+            self._done.set()
+
+    def fail(self, message: str) -> None:
+        with self._lock:
+            self.error = message
+            self.state = JobState.FAILED
+            self.finished_at = _now()
+            self._publish({"type": "status", "state": JobState.FAILED.value})
+            self._publish({"type": "__end__"})
+            self._subscribers.clear()
+            self._done.set()
+
+    def wait(self, timeout: float | None = None) -> bool:
+        return self._done.wait(timeout=timeout)
+
+    def is_terminal(self) -> bool:
+        return self.state.value in _TERMINAL
+
+    def subscribe(self) -> Queue[dict[str, Any]]:
+        q: Queue[dict[str, Any]] = Queue()
+        with self._lock:
+            q.put({"type": "status", "state": self.state.value})
+            if self.is_terminal():
+                q.put({"type": "__end__"})
+            else:
+                self._subscribers.append(q)
+        return q
+
+
+class JobStore:
+    def __init__(self, max_workers: int = 4) -> None:
+        self._jobs: dict[str, Job] = {}
+        self._lock = threading.Lock()
+        self._executor = ThreadPoolExecutor(
+            max_workers=max_workers, thread_name_prefix="ds-job"
+        )
+
+    def create(self, run_id: str, *, kind: str) -> Job:
+        with self._lock:
+            if run_id in self._jobs:
+                raise JobExistsError(run_id)
+            job = Job(run_id=run_id, kind=kind)
+            self._jobs[run_id] = job
+            return job
+
+    def submit(self, job: Job, fn: Callable[[Job], None]) -> None:
+        self._executor.submit(self._wrap, job, fn)
+
+    @staticmethod
+    def _wrap(job: Job, fn: Callable[[Job], None]) -> None:
+        try:
+            fn(job)
+        except Exception as exc:
+            job.fail(f"{type(exc).__name__}: {exc}")
+
+    def get(self, run_id: str) -> Job | None:
+        with self._lock:
+            return self._jobs.get(run_id)
+
+    def shutdown(self) -> None:
+        self._executor.shutdown(wait=False)

app/api/routers/__init__.py

@@ -0,0 +1 @@
+# app/api/routers/__init__.py

app/api/routers/chains.py

@@ -0,0 +1,170 @@
+# app/api/routers/chains.py
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, Request, Response
+from fastapi.responses import JSONResponse
+
+from app.api.deps import (
+    AppContext,
+    get_context,
+    require_auth,
+    resolve_chain_decider,
+    resolve_run_config,
+)
+from app.api.errors import Conflict, NotFound
+from app.api.jobs import Job, JobState
+from app.api.schemas import ChainRequest
+from app.recording.recorder import _validate_run_id
+
+router = APIRouter(tags=["chains"])
+
+
+def _job_state_for_chain(status: str) -> JobState:
+    """Map an iterative-chain terminal status onto a job state.
+
+    `ask_user` is a *paused* outcome — the LLM judge needs the human before the
+    chain can continue — not a failure. Mirror how /runs maps a paused run, so a
+    legitimate clarification request isn't recorded as FAILED.
+    """
+    if status in {"ok", "stopped", "max_iterations"}:
+        return JobState.OK
+    if status == "ask_user":
+        return JobState.PAUSED
+    return JobState.FAILED
+
+
+def _decision_payload(decision: Any | None) -> dict[str, Any] | None:
+    if decision is None:
+        return None
+    return {
+        "action": decision.action,
+        "reason": decision.reason,
+        "success_criteria_met": decision.success_criteria_met,
+        "gaps": list(decision.gaps),
+        "next_prompt": decision.next_prompt,
+        "question_to_user": decision.question_to_user,
+    }
+
+
+def _chain_payload(result: Any) -> dict[str, Any]:
+    return {
+        "chain_id": result.chain_id,
+        "status": result.status,
+        "response": result.response,
+        "steps": [
+            {
+                "iteration": s.iteration,
+                "run_id": s.run_id,
+                "status": s.result.status,
+                "decision": s.decision.action,
+                "decision_detail": _decision_payload(s.decision),
+                "reason": s.decision.reason,
+            }
+            for s in result.steps
+        ],
+        "final_decision": _decision_payload(result.final_decision),
+    }
+
+
+def _make_chain_worker(
+    ctx: AppContext,
+    config,
+    prompt: str,
+    run_id: str,
+    max_iter: int,
+    decider,
+):
+    supervisor = ctx.supervisor_for(config)
+
+    def work(job: Job) -> None:
+        job.set_state(JobState.RUNNING)
+        result = supervisor.run_iteratively(
+            prompt,
+            run_id=run_id,
+            max_iterations=max_iter,
+            decider=decider,
+        )
+        job.complete(result=result, state=_job_state_for_chain(result.status))
+
+    return work
+
+
+@router.post("/chains")
+def create_chain(
+    request: Request,
+    body: ChainRequest,
+    _: None = Depends(require_auth),
+) -> Response:
+    ctx = get_context(request)
+    config = resolve_run_config(
+        ctx,
+        planner=body.planner,
+        provider=body.provider,
+        model=body.model,
+    )
+    decider = resolve_chain_decider(
+        ctx,
+        config=config,
+        decider=body.decider,
+        success_criteria=body.success_criteria,
+        judge_failed_runs=body.judge_failed_runs,
+    )
+    run_id = body.run_id or f"chain-{__import__('uuid').uuid4().hex[:12]}"
+    _validate_run_id(run_id)
+    if ctx.jobs.get(run_id) is not None or ctx.recorder.exists(run_id):
+        raise Conflict(f"chain id already exists: {run_id!r}")
+
+    job = ctx.jobs.create(run_id, kind="chain")
+    ctx.jobs.submit(
+        job,
+        _make_chain_worker(
+            ctx,
+            config,
+            body.prompt,
+            run_id,
+            body.max_iterations,
+            decider,
+        ),
+    )
+
+    if body.mode == "async":
+        return JSONResponse(
+            status_code=202,
+            content={
+                "chain_id": run_id,
+                "status": job.state.value,
+                "links": {"self": f"/chains/{run_id}"},
+            },
+        )
+
+    timeout = (
+        ctx.settings.max_sync_seconds
+        if body.mode == "sync"
+        else ctx.settings.auto_sync_seconds
+    )
+    finished = job.wait(timeout=timeout)
+    if finished and job.result is not None:
+        return JSONResponse(status_code=200, content=_chain_payload(job.result))
+    return JSONResponse(
+        status_code=202,
+        content={
+            "chain_id": run_id,
+            "status": job.state.value,
+            "links": {"self": f"/chains/{run_id}"},
+        },
+    )
+
+
+@router.get("/chains/{chain_id}")
+def get_chain(request: Request, chain_id: str) -> dict[str, Any]:
+    ctx = get_context(request)
+    _validate_run_id(chain_id)
+    job = ctx.jobs.get(chain_id)
+    if job is not None and job.result is not None:
+        return _chain_payload(job.result)
+    try:
+        return ctx.recorder.load_chain(chain_id)
+    except FileNotFoundError as exc:
+        raise NotFound(f"No chain {chain_id!r}") from exc

app/api/routers/health.py

@@ -0,0 +1,11 @@
+# app/api/routers/health.py
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+router = APIRouter(tags=["meta"])
+
+
+@router.get("/healthz")
+def healthz() -> dict[str, str]:
+    return {"status": "ok"}

app/api/routers/registry.py

@@ -0,0 +1,38 @@
+# app/api/routers/registry.py
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter
+
+from app.registry import (
+    DEFAULT_SUBAGENTS,
+    DEFAULT_TOOLS,
+    FORBIDDEN_KINDS,
+    default_kind_definitions,
+)
+
+router = APIRouter(tags=["registry"])
+
+
+@router.get("/registry")
+def get_registry() -> dict[str, Any]:
+    kinds: list[dict[str, Any]] = []
+    for kind, definition in default_kind_definitions().items():
+        kinds.append(
+            {
+                "kind": kind.value,
+                "description": definition.description,
+                "counts_as_llm_call": definition.counts_as_llm_call,
+                "has_side_effects": definition.has_side_effects,
+                "requires_tool_allowlist": definition.requires_tool_allowlist,
+                "requires_subagent_allowlist": definition.requires_subagent_allowlist,
+                "param_schema": definition.param_model.model_json_schema(),
+            }
+        )
+    return {
+        "node_kinds": kinds,
+        "tools": sorted(DEFAULT_TOOLS),
+        "subagents": sorted(DEFAULT_SUBAGENTS),
+        "forbidden_kinds": sorted(FORBIDDEN_KINDS),
+    }