roborean-api-fastapi 0.1.2__py3-none-any.whl

roborean_api_fastapi/__init__.py

@@ -0,0 +1,7 @@
+"""Roborean FastAPI HTTP API."""
+
+from .app import create_app
+
+__version__ = "0.4.0"
+
+__all__ = ["create_app", "__version__"]

roborean_api_fastapi/app.py

@@ -0,0 +1,48 @@
+"""FastAPI application factory."""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.openapi.utils import get_openapi
+
+from .deps import attach_app_state
+from .errors import install_exception_handlers
+from .openapi.customize import customize_openapi
+from .routers import artifacts, compile, health, previews, projects, runs
+from .settings import Settings
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Build the Roborean HTTP API."""
+    app = FastAPI(title="Roborean API", version="0.4.0")
+    resolved = attach_app_state(app, settings)
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=resolved.cors_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    install_exception_handlers(app)
+
+    app.include_router(health.router)
+    app.include_router(projects.router)
+    app.include_router(compile.router)
+    app.include_router(runs.router)
+    app.include_router(artifacts.router)
+    app.include_router(previews.router)
+
+    def custom_openapi() -> dict:
+        if app.openapi_schema:
+            return app.openapi_schema
+        schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            routes=app.routes,
+        )
+        app.openapi_schema = customize_openapi(schema)
+        return app.openapi_schema
+
+    app.openapi = custom_openapi
+    _ = resolved
+    return app

roborean_api_fastapi/deps.py

@@ -0,0 +1,122 @@
+"""FastAPI dependency wiring."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from fastapi import Depends, Request
+from roborean_engine import RunService
+from roborean_engine.bits.registry import BitTypeRegistry, builtin_registry
+from roborean_engine.documents import default_driver_registry
+from roborean_storage_base import (
+    ArtifactStore,
+    ProjectRepository,
+    RunRepository,
+)
+from roborean_storage_dict import (
+    DictArtifactStore,
+    DictProjectRepository,
+    DictRunRepository,
+)
+
+from .security import Principal, resolve_principal
+from .settings import Settings, load_settings
+
+
+@dataclass
+class AppState:
+    """Shared repositories and services."""
+
+    settings: Settings
+    projects: ProjectRepository
+    runs: RunRepository
+    artifacts: ArtifactStore
+    run_service: RunService
+
+
+def build_app_state(settings: Settings) -> AppState:
+    """Construct repositories from settings."""
+    if settings.storage_backend == "dict":
+        root = settings.store_path.expanduser().resolve()
+        root.mkdir(parents=True, exist_ok=True)
+        projects = DictProjectRepository(root)
+        runs = DictRunRepository(root)
+        artifacts = DictArtifactStore(settings.artifact_root.resolve())
+    else:
+        from roborean_storage_sqlalchemy import (
+            SqlAlchemyProjectRepository,
+            SqlAlchemyRunRepository,
+            make_engine,
+            make_session_factory,
+            upgrade,
+        )
+
+        if not settings.database_url:
+            raise ValueError("database_url required for sqlalchemy backend")
+        engine = make_engine(settings.database_url)
+        upgrade(engine)
+        factory = make_session_factory(engine)
+        projects = SqlAlchemyProjectRepository(factory)
+        runs = SqlAlchemyRunRepository(factory)
+        artifacts = DictArtifactStore(settings.artifact_root.resolve())
+
+    def package_dir(project_id: str) -> Path | None:
+        if isinstance(projects, DictProjectRepository):
+            path = projects._project_dir(project_id)
+            return path if path.is_dir() else None
+        return None
+
+    run_service = RunService(
+        projects=projects,
+        runs=runs,
+        artifacts=artifacts,
+        registry=builtin_registry(),
+        package_dir_for_project=package_dir,
+    )
+    return AppState(
+        settings=settings,
+        projects=projects,
+        runs=runs,
+        artifacts=artifacts,
+        run_service=run_service,
+    )
+
+
+def get_settings(request: Request) -> Settings:
+    """Settings attached to the app instance."""
+    return request.app.state.roborean_settings
+
+
+def get_state(request: Request) -> AppState:
+    """Repositories attached to the app instance."""
+    return request.app.state.roborean_app_state
+
+
+def get_principal(
+    request: Request,
+    settings: Settings = Depends(get_settings),
+) -> Principal:
+    """Resolve caller identity."""
+    return resolve_principal(request, settings)
+
+
+def get_bit_registry() -> BitTypeRegistry:
+    """Built-in bit registry."""
+    return builtin_registry()
+
+
+def get_document_registry():
+    """Installed document drivers."""
+    return default_driver_registry()
+
+
+def attach_app_state(app, settings: Settings | None = None) -> Settings:
+    """Bind settings and repositories to a FastAPI app."""
+    resolved = settings or load_settings()
+    app.state.roborean_settings = resolved
+    app.state.roborean_app_state = build_app_state(resolved)
+    return resolved
+
+
+def reset_state() -> None:
+    """No-op placeholder for tests (state lives on app)."""
+    return None

roborean_api_fastapi/errors.py

@@ -0,0 +1,81 @@
+"""HTTP error mapping."""
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from roborean_engine.compiler import CompileError
+from roborean_storage_base import ConflictError, NotFoundError
+
+from .schemas.common import DiagnosticDto, ErrorBody
+
+
+class ApiError(Exception):
+    """Structured API failure."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        diagnostics: list[DiagnosticDto] | None = None,
+    ) -> None:
+        """Store HTTP metadata for handlers."""
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.diagnostics = diagnostics or []
+        super().__init__(message)
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    """Register domain → HTTP mappings."""
+
+    @app.exception_handler(ApiError)
+    async def _api_error(_request: Request, error: ApiError) -> JSONResponse:
+        body = ErrorBody(
+            code=error.code,
+            message=error.message,
+            diagnostics=error.diagnostics,
+        )
+        return JSONResponse(
+            status_code=error.status_code,
+            content=body.model_dump(mode="json", by_alias=True),
+        )
+
+    @app.exception_handler(NotFoundError)
+    async def _not_found(
+        _request: Request, error: NotFoundError
+    ) -> JSONResponse:
+        body = ErrorBody(code="E_NOT_FOUND", message=str(error))
+        return JSONResponse(
+            status_code=404, content=body.model_dump(by_alias=True)
+        )
+
+    @app.exception_handler(ConflictError)
+    async def _conflict(
+        _request: Request, error: ConflictError
+    ) -> JSONResponse:
+        body = ErrorBody(code="E_CONFLICT", message=str(error))
+        return JSONResponse(
+            status_code=409, content=body.model_dump(by_alias=True)
+        )
+
+    @app.exception_handler(CompileError)
+    async def _compile(_request: Request, error: CompileError) -> JSONResponse:
+        diagnostics = [
+            DiagnosticDto(
+                severity=item.severity,
+                code=item.code,
+                message=item.message,
+                path=item.path,
+            )
+            for item in error.diagnostics
+        ]
+        body = ErrorBody(
+            code="E_COMPILE",
+            message=str(error),
+            diagnostics=diagnostics,
+        )
+        return JSONResponse(
+            status_code=400, content=body.model_dump(by_alias=True)
+        )

roborean_api_fastapi/openapi/customize.py

@@ -0,0 +1,11 @@
+"""OpenAPI post-processing."""
+
+from typing import Any
+
+
+def customize_openapi(schema: dict[str, Any]) -> dict[str, Any]:
+    """Apply stable metadata for generated clients."""
+    info = schema.setdefault("info", {})
+    info["title"] = info.get("title") or "Roborean API"
+    info["version"] = info.get("version") or "0.4.0"
+    return schema

roborean_api_fastapi/redaction.py

@@ -0,0 +1,101 @@
+"""Redact workspace values for client responses."""
+
+from typing import Any
+
+from roborean_spec import (
+    Exposure,
+    Project,
+    PublicLiteral,
+    Redacted,
+    RunResults,
+    SecretRefValue,
+    Variable,
+    WorkspaceValue,
+)
+
+
+def redact_workspace_value(
+    value: WorkspaceValue,
+    *,
+    exposure: Exposure | None = None,
+) -> WorkspaceValue:
+    """Replace secret-bearing values according to exposure."""
+    if exposure in (Exposure.BACKEND_ONLY, Exposure.REDACTED_TO_CLIENT):
+        return Redacted(kind="redacted", reason="secret")
+    if isinstance(value, SecretRefValue):
+        return Redacted(kind="redacted", reason="secret")
+    if isinstance(value, PublicLiteral):
+        return value
+    return Redacted(kind="redacted", reason="policy")
+
+
+def redact_project_for_client(project: Project) -> dict[str, Any]:
+    """Return a JSON-serializable project safe for browsers."""
+    if isinstance(project, dict):
+        project = Project.model_validate(project)
+
+    # Omit null optional fields so Draft 2020-12 schemas stay valid.
+    data = project.model_dump(mode="json", by_alias=True, exclude_none=True)
+    variables = []
+    for variable in project.workspace.get("variables", []):
+        if isinstance(variable, dict):
+            variable = Variable.model_validate(variable)
+        item = variable.model_dump(
+            mode="json", by_alias=True, exclude_none=True
+        )
+        item["defaultValue"] = redact_workspace_value(
+            variable.default_value,
+            exposure=variable.exposure,
+        ).model_dump(mode="json", by_alias=True, exclude_none=True)
+        variables.append(item)
+    data["workspace"]["variables"] = variables
+    return data
+
+
+def _redact_patch_ops(payload: dict[str, Any]) -> dict[str, Any]:
+    """Redact workspace patch operations in run results."""
+    bit_results = []
+    for item in payload.get("bitResults", []):
+        patch = item.get("workspacePatch") or {}
+        ops = []
+        for op in patch.get("ops", []):
+            if op.get("op") == "set" and "value" in op:
+                value = op["value"]
+                if (
+                    isinstance(value, dict)
+                    and value.get("kind") == "secret_ref"
+                ):
+                    op = {
+                        **op,
+                        "value": {"kind": "redacted", "reason": "secret"},
+                    }
+            ops.append(op)
+        item = {**item, "workspacePatch": {**patch, "ops": ops}}
+        bit_results.append(item)
+    payload["bitResults"] = bit_results
+    return payload
+
+
+def redact_run_results_for_client(results: RunResults) -> dict[str, Any]:
+    """Return run results without resolved secret literals."""
+    payload = results.model_dump(mode="json", by_alias=True, exclude_none=True)
+    return _redact_patch_ops(payload)
+
+
+def assert_no_backend_only_literals(payload: dict[str, Any]) -> None:
+    """Fail tests when raw secret literals leak to clients."""
+    stack = [payload]
+    while stack:
+        current = stack.pop()
+        if isinstance(current, dict):
+            kind = current.get("kind")
+            if kind == "public_literal" and current.get("value") not in (
+                None,
+                "",
+            ):
+                exposure = current.get("exposure")
+                if exposure == "backendOnly":
+                    raise AssertionError("backendOnly literal leaked")
+            stack.extend(current.values())
+        elif isinstance(current, list):
+            stack.extend(current)

roborean_api_fastapi/routers/__init__.py

@@ -0,0 +1,5 @@
+"""Router exports."""
+
+from . import artifacts, compile, health, previews, projects, runs
+
+__all__ = ["artifacts", "compile", "health", "previews", "projects", "runs"]

roborean_api_fastapi/routers/artifacts.py

@@ -0,0 +1,45 @@
+"""Artifact download."""
+
+from fastapi import APIRouter, Depends, Response
+from roborean_storage_base import NotFoundError
+
+from ..deps import AppState, get_principal, get_state
+from ..errors import ApiError
+from ..security import Principal
+
+router = APIRouter(prefix="/v1/runs", tags=["artifacts"])
+
+
+@router.get("/{run_id}/artifacts/{artifact_id}")
+def download_artifact(
+    run_id: str,
+    artifact_id: str,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> Response:
+    """Stream one stored artifact (document id)."""
+    record = state.run_service.get(run_id)
+    media_type = "application/octet-stream"
+    for item in record.results.artifacts if record.results else []:
+        doc_id = (
+            item.get("documentId")
+            if isinstance(item, dict)
+            else item.document_id
+        )
+        if doc_id == artifact_id:
+            media_type = (
+                item.get("mediaType")
+                if isinstance(item, dict)
+                else item.media_type
+            )
+            break
+    key = f"{run_id}/{artifact_id}"
+    try:
+        payload = state.artifacts.get_bytes(key)
+    except (NotFoundError, FileNotFoundError, KeyError) as error:
+        raise ApiError(
+            status_code=404,
+            code="E_NOT_FOUND",
+            message=f"artifact not found: {artifact_id}",
+        ) from error
+    return Response(content=payload, media_type=media_type)

roborean_api_fastapi/routers/compile.py

@@ -0,0 +1,32 @@
+"""Compile route."""
+
+from fastapi import APIRouter, Depends
+
+from ..deps import AppState, get_bit_registry, get_principal, get_state
+from ..schemas.runs import CompileRequest, CompileResponse
+from ..security import Principal
+from ..services import compile_service
+
+router = APIRouter(prefix="/v1/projects", tags=["compile"])
+
+
+@router.post("/{project_id}/compile", response_model=CompileResponse)
+def compile_project(
+    project_id: str,
+    body: CompileRequest | None = None,
+    state: AppState = Depends(get_state),
+    registry=Depends(get_bit_registry),
+    _principal: Principal = Depends(get_principal),
+) -> CompileResponse:
+    """Compile a stored project."""
+    request = body or CompileRequest()
+    package_dir = None
+    if state.run_service.package_dir_for_project:
+        package_dir = state.run_service.package_dir_for_project(project_id)
+    return compile_service.compile_stored_project(
+        state.projects,
+        project_id,
+        body=request,
+        registry=registry,
+        package_dir=package_dir,
+    )

roborean_api_fastapi/routers/health.py

@@ -0,0 +1,12 @@
+"""Health probe."""
+
+from fastapi import APIRouter
+from roborean_engine.version import ENGINE_VERSION
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    """Return liveness and engine version."""
+    return {"status": "ok", "engineVersion": ENGINE_VERSION}

roborean_api_fastapi/routers/previews.py

@@ -0,0 +1,29 @@
+"""Preview route."""
+
+from fastapi import APIRouter, Depends
+
+from ..deps import AppState, get_principal, get_state
+from ..schemas.previews import PreviewRequest, PreviewResponse
+from ..security import Principal
+from ..services import preview_service
+
+router = APIRouter(prefix="/v1/projects", tags=["previews"])
+
+
+@router.post("/{project_id}/preview", response_model=PreviewResponse)
+def preview_document(
+    project_id: str,
+    body: PreviewRequest,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> PreviewResponse:
+    """Return a browser-safe document preview."""
+    package_dir = None
+    if state.run_service.package_dir_for_project:
+        package_dir = state.run_service.package_dir_for_project(project_id)
+    return preview_service.build_preview(
+        state.projects,
+        project_id,
+        body,
+        package_dir=package_dir,
+    )

roborean_api_fastapi/routers/projects.py

@@ -0,0 +1,76 @@
+"""Project CRUD routes."""
+
+from fastapi import APIRouter, Depends, Response, status
+
+from ..deps import AppState, get_principal, get_state
+from ..errors import ApiError
+from ..schemas.projects import (
+    ProjectCreate,
+    ProjectDetail,
+    ProjectSummary,
+    ProjectUpdate,
+)
+from ..security import Principal
+from ..services import project_service
+
+router = APIRouter(prefix="/v1/projects", tags=["projects"])
+
+
+@router.get("", response_model=list[ProjectSummary])
+def list_projects(
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> list[ProjectSummary]:
+    """List project summaries."""
+    return project_service.list_projects(state.projects)
+
+
+@router.post(
+    "", response_model=ProjectDetail, status_code=status.HTTP_201_CREATED
+)
+def create_project(
+    body: ProjectCreate,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> ProjectDetail:
+    """Create a stored project."""
+    return project_service.create_project(state.projects, body)
+
+
+@router.get("/{project_id}", response_model=ProjectDetail)
+def get_project(
+    project_id: str,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> ProjectDetail:
+    """Fetch one project."""
+    return project_service.get_project(state.projects, project_id)
+
+
+@router.put("/{project_id}", response_model=ProjectDetail)
+def update_project(
+    project_id: str,
+    body: ProjectUpdate,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> ProjectDetail:
+    """Replace a project."""
+    try:
+        return project_service.update_project(state.projects, project_id, body)
+    except ValueError as error:
+        raise ApiError(
+            status_code=400,
+            code="E_SCHEMA",
+            message=str(error),
+        ) from error
+
+
+@router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_project(
+    project_id: str,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> Response:
+    """Delete a project."""
+    project_service.delete_project(state.projects, project_id)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

roborean_api_fastapi/routers/runs.py

@@ -0,0 +1,61 @@
+"""Run routes."""
+
+from fastapi import APIRouter, Depends, Header
+
+from ..deps import AppState, get_principal, get_state
+from ..errors import ApiError
+from ..schemas.runs import RunCreate, RunDetail, RunSummary
+from ..security import Principal
+from ..services import run_service
+
+router = APIRouter(tags=["runs"])
+
+
+@router.post(
+    "/v1/projects/{project_id}/runs",
+    response_model=RunDetail,
+    status_code=201,
+)
+def create_run(
+    project_id: str,
+    body: RunCreate,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+    idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
+) -> RunDetail:
+    """Execute a durable run."""
+    if not idempotency_key:
+        raise ApiError(
+            status_code=400,
+            code="E_IDEMPOTENCY",
+            message="Idempotency-Key header is required",
+        )
+    return run_service.create_run(
+        state.run_service,
+        project_id,
+        body,
+        idempotency_key=idempotency_key,
+    )
+
+
+@router.get(
+    "/v1/projects/{project_id}/runs",
+    response_model=list[RunSummary],
+)
+def list_runs(
+    project_id: str,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> list[RunSummary]:
+    """List runs for a project."""
+    return run_service.list_runs(state.run_service, project_id)
+
+
+@router.get("/v1/runs/{run_id}", response_model=RunDetail)
+def get_run(
+    run_id: str,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> RunDetail:
+    """Fetch one run."""
+    return run_service.get_run(state.run_service, run_id)

roborean_api_fastapi/schemas/__init__.py

@@ -0,0 +1,33 @@
+"""Schema package exports."""
+
+from .common import DiagnosticDto, ErrorBody
+from .previews import PreviewRequest, PreviewResponse
+from .projects import (
+    ProjectCreate,
+    ProjectDetail,
+    ProjectSummary,
+    ProjectUpdate,
+)
+from .runs import (
+    CompileRequest,
+    CompileResponse,
+    RunCreate,
+    RunDetail,
+    RunSummary,
+)
+
+__all__ = [
+    "CompileRequest",
+    "CompileResponse",
+    "DiagnosticDto",
+    "ErrorBody",
+    "PreviewRequest",
+    "PreviewResponse",
+    "ProjectCreate",
+    "ProjectDetail",
+    "ProjectSummary",
+    "ProjectUpdate",
+    "RunCreate",
+    "RunDetail",
+    "RunSummary",
+]

roborean_api_fastapi/schemas/common.py

@@ -0,0 +1,34 @@
+"""Shared API DTOs."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApiModel(BaseModel):
+    """Base model with alias support."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class DiagnosticDto(ApiModel):
+    """One compile or validation diagnostic."""
+
+    severity: Literal["error", "warning", "info"]
+    code: str
+    message: str
+    path: str | None = None
+
+
+class ErrorBody(ApiModel):
+    """Standard error envelope."""
+
+    code: str
+    message: str
+    diagnostics: list[DiagnosticDto] = Field(default_factory=list)
+
+
+class IdempotencyKey(ApiModel):
+    """Document idempotency header usage."""
+
+    key: str = Field(alias="idempotencyKey")

roborean_api_fastapi/schemas/previews.py

@@ -0,0 +1,25 @@
+"""Preview API models."""
+
+from typing import Any, Literal
+
+from pydantic import Field
+
+from .common import ApiModel, DiagnosticDto
+
+
+class PreviewRequest(ApiModel):
+    """Preview one document definition."""
+
+    document_id: str = Field(alias="documentId")
+    workspace_overrides: dict[str, Any] = Field(
+        default_factory=dict, alias="workspaceOverrides"
+    )
+
+
+class PreviewResponse(ApiModel):
+    """Browser-safe preview payload."""
+
+    document_id: str = Field(alias="documentId")
+    kind: Literal["html", "text", "sheet-json", "drawing-json", "unsupported"]
+    body: Any
+    warnings: list[DiagnosticDto] = Field(default_factory=list)

roborean_api_fastapi/schemas/projects.py

@@ -0,0 +1,34 @@
+"""Project API models."""
+
+from typing import Any
+
+from pydantic import Field
+from roborean_spec import Project
+
+from .common import ApiModel
+
+
+class ProjectCreate(ApiModel):
+    """Create one stored project."""
+
+    project: Project
+
+
+class ProjectUpdate(ApiModel):
+    """Replace a stored project."""
+
+    project: Project
+
+
+class ProjectSummary(ApiModel):
+    """List row for projects."""
+
+    id: str
+    name: str
+    schema_version: str = Field(alias="schemaVersion")
+
+
+class ProjectDetail(ApiModel):
+    """Redacted project payload."""
+
+    project: dict[str, Any]

roborean_api_fastapi/schemas/runs.py

@@ -0,0 +1,55 @@
+"""Run and compile API models."""
+
+from typing import Any
+
+from pydantic import Field
+
+from .common import ApiModel
+
+
+class CompileRequest(ApiModel):
+    """Optional compile flags."""
+
+    strict_undeclared_access: bool = Field(
+        default=True, alias="strictUndeclaredAccess"
+    )
+
+
+class CompileResponse(ApiModel):
+    """Compiled project snapshot."""
+
+    compiled: dict[str, Any]
+
+
+class RunCreate(ApiModel):
+    """Body for POST /runs."""
+
+    dry_run: bool = Field(default=False, alias="dryRun")
+    stop_on_bit_error: bool = Field(default=True, alias="stopOnBitError")
+    workspace_overrides: dict[str, Any] = Field(
+        default_factory=dict, alias="workspaceOverrides"
+    )
+    strict_workspace_access: bool = Field(
+        default=True, alias="strictWorkspaceAccess"
+    )
+
+
+class RunSummary(ApiModel):
+    """Run list item."""
+
+    run_id: str = Field(alias="runId")
+    project_id: str = Field(alias="projectId")
+    status: str
+    created_at: str = Field(alias="createdAt")
+    finished_at: str | None = Field(default=None, alias="finishedAt")
+
+
+class RunDetail(ApiModel):
+    """Redacted durable run."""
+
+    run_id: str = Field(alias="runId")
+    project_id: str = Field(alias="projectId")
+    status: str
+    results: dict[str, Any] | None = None
+    diff: dict[str, Any] | None = None
+    error: dict[str, Any] | None = None

roborean_api_fastapi/security.py

@@ -0,0 +1,30 @@
+"""Auth stub for Phase 4."""
+
+from dataclasses import dataclass
+
+from fastapi import Request
+
+from .errors import ApiError
+from .settings import Settings
+
+
+@dataclass(frozen=True)
+class Principal:
+    """Caller identity (stub)."""
+
+    subject: str
+    roles: frozenset[str]
+
+
+def resolve_principal(request: Request, settings: Settings) -> Principal:
+    """Resolve the caller from headers or allow anonymous local use."""
+    if not settings.require_auth:
+        return Principal(subject="anonymous", roles=frozenset({"local"}))
+    raw = request.headers.get("X-Roborean-Principal")
+    if not raw:
+        raise ApiError(
+            status_code=401,
+            code="E_AUTH",
+            message="missing principal",
+        )
+    return Principal(subject=raw, roles=frozenset({"user"}))

roborean_api_fastapi/services/__init__.py

@@ -0,0 +1,25 @@
+"""Service exports."""
+
+from .compile_service import compile_stored_project
+from .preview_service import build_preview
+from .project_service import (
+    create_project,
+    delete_project,
+    get_project,
+    list_projects,
+    update_project,
+)
+from .run_service import create_run, get_run, list_runs
+
+__all__ = [
+    "build_preview",
+    "compile_stored_project",
+    "create_project",
+    "create_run",
+    "delete_project",
+    "get_project",
+    "get_run",
+    "list_projects",
+    "list_runs",
+    "update_project",
+]

roborean_api_fastapi/services/compile_service.py

@@ -0,0 +1,32 @@
+"""Compile service."""
+
+from pathlib import Path
+
+from roborean_engine.bits.registry import BitTypeRegistry
+from roborean_engine.compiler import CompileOptions, compile_project
+from roborean_storage_base import ProjectRepository
+
+from ..schemas.runs import CompileRequest, CompileResponse
+
+
+def compile_stored_project(
+    repo: ProjectRepository,
+    project_id: str,
+    *,
+    body: CompileRequest,
+    registry: BitTypeRegistry,
+    package_dir: Path | None,
+) -> CompileResponse:
+    """Compile a stored project package."""
+    project = repo.get(project_id)
+    compiled = compile_project(
+        project,
+        bit_registry=registry,
+        options=CompileOptions(
+            strict_undeclared_access=body.strict_undeclared_access,
+            package_dir=package_dir,
+        ),
+    )
+    return CompileResponse(
+        compiled=compiled.model_dump(mode="json", by_alias=True)
+    )

roborean_api_fastapi/services/preview_service.py

@@ -0,0 +1,71 @@
+"""Document preview service."""
+
+from pathlib import Path
+
+from pydantic import TypeAdapter
+from roborean_engine.bits.registry import builtin_registry
+from roborean_engine.compiler import CompileOptions, compile_project
+from roborean_engine.runner import RunOptions, run_project_detailed
+from roborean_spec import WorkspaceValue
+from roborean_storage_base import ProjectRepository
+
+from ..schemas.common import DiagnosticDto
+from ..schemas.previews import PreviewRequest, PreviewResponse
+
+
+def build_preview(
+    repo: ProjectRepository,
+    project_id: str,
+    body: PreviewRequest,
+    *,
+    package_dir: Path | None,
+) -> PreviewResponse:
+    """Run the project and return a browser-safe preview."""
+    project = repo.get(project_id)
+    registry = builtin_registry()
+    compiled = compile_project(
+        project,
+        bit_registry=registry,
+        options=CompileOptions(package_dir=package_dir),
+    )
+    adapter = TypeAdapter(WorkspaceValue)
+    overrides = {
+        key: adapter.validate_python(value)
+        for key, value in body.workspace_overrides.items()
+    }
+    outcome = run_project_detailed(
+        compiled,
+        project,
+        registry=registry,
+        options=RunOptions(
+            workspace_overrides=overrides,
+            package_dir=package_dir,
+        ),
+    )
+    preview = outcome.previews.get(body.document_id)
+    if preview is None:
+        return PreviewResponse(
+            documentId=body.document_id,
+            kind="unsupported",
+            body="",
+            warnings=[
+                DiagnosticDto(
+                    severity="warning",
+                    code="W_PREVIEW_MISSING",
+                    message="No preview produced for document",
+                )
+            ],
+        )
+    mode = str(preview.get("mode", "unsupported"))
+    kind = "unsupported"
+    if mode in ("text", "html", "drawing-json"):
+        kind = "html" if mode == "html" else mode
+    if mode == "html":
+        kind = "html"
+    body_value = preview.get("body", "")
+    return PreviewResponse(
+        documentId=body.document_id,
+        kind=kind,
+        body=body_value,
+        warnings=[],
+    )

roborean_api_fastapi/services/project_service.py

@@ -0,0 +1,67 @@
+"""Project persistence service."""
+
+from roborean_spec import Project
+from roborean_storage_base import ProjectRepository
+
+from ..redaction import redact_project_for_client
+from ..schemas.projects import (
+    ProjectCreate,
+    ProjectDetail,
+    ProjectSummary,
+    ProjectUpdate,
+)
+
+
+def list_projects(repo: ProjectRepository) -> list[ProjectSummary]:
+    """List stored project ids."""
+    rows = []
+    for project_id in repo.list_ids():
+        project = repo.get(project_id)
+        rows.append(
+            ProjectSummary(
+                id=project.id,
+                name=project.name,
+                schemaVersion=project.schema_version,
+            )
+        )
+    return rows
+
+
+def _coerce_project(value: Project | dict) -> Project:
+    """Ensure a project model instance."""
+    if isinstance(value, Project):
+        return value
+    return Project.model_validate(value)
+
+
+def create_project(
+    repo: ProjectRepository, body: ProjectCreate
+) -> ProjectDetail:
+    """Validate and store a new project."""
+    project = _coerce_project(body.project)
+    repo.save(project, revision="1")
+    return ProjectDetail(project=redact_project_for_client(project))
+
+
+def get_project(repo: ProjectRepository, project_id: str) -> ProjectDetail:
+    """Load one redacted project."""
+    project = repo.get(project_id)
+    return ProjectDetail(project=redact_project_for_client(project))
+
+
+def update_project(
+    repo: ProjectRepository,
+    project_id: str,
+    body: ProjectUpdate,
+) -> ProjectDetail:
+    """Replace a stored project."""
+    project = _coerce_project(body.project)
+    if project.id != project_id:
+        raise ValueError("project.id must match URL project_id")
+    repo.save(project, revision="1")
+    return ProjectDetail(project=redact_project_for_client(project))
+
+
+def delete_project(repo: ProjectRepository, project_id: str) -> None:
+    """Remove a project package."""
+    repo.delete(project_id)

roborean_api_fastapi/services/run_service.py

@@ -0,0 +1,75 @@
+"""Run orchestration for the API."""
+
+from pydantic import TypeAdapter
+from roborean_engine import RunService
+from roborean_spec import RunRequest, RunTrigger, WorkspaceValue
+
+from ..redaction import redact_run_results_for_client
+from ..schemas.runs import RunCreate, RunDetail, RunSummary
+
+
+def _to_detail(record) -> RunDetail:
+    """Map a durable record to a client DTO."""
+    results = None
+    if record.results is not None:
+        results = redact_run_results_for_client(record.results)
+    diff = None
+    if record.diff is not None:
+        diff = record.diff.model_dump(mode="json", by_alias=True)
+    error = None
+    if record.error is not None:
+        error = record.error.model_dump(mode="json", by_alias=True)
+    return RunDetail(
+        runId=record.run_id,
+        projectId=record.project_id,
+        status=record.status.value,
+        results=results,
+        diff=diff,
+        error=error,
+    )
+
+
+def create_run(
+    service: RunService,
+    project_id: str,
+    body: RunCreate,
+    *,
+    idempotency_key: str,
+) -> RunDetail:
+    """Create an idempotent durable run."""
+    adapter = TypeAdapter(WorkspaceValue)
+    overrides = {
+        key: adapter.validate_python(value)
+        for key, value in body.workspace_overrides.items()
+    }
+    request = RunRequest(
+        projectId=project_id,
+        projectRevision="1",
+        idempotencyKey=idempotency_key,
+        trigger=RunTrigger.API,
+        workspaceOverrides=overrides,
+        strictWorkspaceAccess=body.strict_workspace_access,
+    )
+    record = service.create_and_execute(request)
+    return _to_detail(record)
+
+
+def get_run(service: RunService, run_id: str) -> RunDetail:
+    """Load one run."""
+    return _to_detail(service.get(run_id))
+
+
+def list_runs(service: RunService, project_id: str) -> list[RunSummary]:
+    """List runs for a project."""
+    rows = []
+    for record in service.list_for_project(project_id):
+        rows.append(
+            RunSummary(
+                runId=record.run_id,
+                projectId=record.project_id,
+                status=record.status.value,
+                createdAt=record.created_at,
+                finishedAt=record.finished_at,
+            )
+        )
+    return rows

roborean_api_fastapi/settings.py

@@ -0,0 +1,24 @@
+"""Application settings."""
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime configuration for the Roborean API."""
+
+    model_config = SettingsConfigDict(env_prefix="ROBOREAN_")
+
+    storage_backend: Literal["dict", "sqlalchemy"] = "dict"
+    store_path: Path = Path("playground/api-store")
+    database_url: str | None = None
+    artifact_root: Path = Path("playground/api-artifacts")
+    cors_origins: list[str] = ["http://localhost:5173"]
+    require_auth: bool = False
+
+
+def load_settings() -> Settings:
+    """Load settings from environment."""
+    return Settings()

roborean_api_fastapi-0.1.2.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: roborean-api-fastapi
+Version: 0.1.2
+Summary: FastAPI HTTP surface for Roborean projects, runs, and previews
+Project-URL: Homepage, https://github.com/TNick/roborean
+Project-URL: Repository, https://github.com/TNick/roborean
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: roborean-engine>=0.1.1
+Requires-Dist: roborean-storage-base>=0.1.1
+Requires-Dist: roborean-storage-dict>=0.1.1
+Requires-Dist: roborean-storage-sqlalchemy>=0.1.1
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: flake8>=7.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: isort>=5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

roborean_api_fastapi-0.1.2.dist-info/RECORD

@@ -0,0 +1,28 @@
+roborean_api_fastapi/__init__.py,sha256=-pxfaVsLV7M5ZEUtqNc2h5eAUmn-9oo5fSKdBBGDwuM,126
+roborean_api_fastapi/app.py,sha256=l002xHIBqCr7leW-Czfn3FV0nbBmoxeNQ22WTw4Ygfg,1457
+roborean_api_fastapi/deps.py,sha256=83Nug4hbu2LmdHEd0AW4sAKvekVFqhyHslC4StmrElM,3573
+roborean_api_fastapi/errors.py,sha256=lygczjriEF2zm2BC-0xkJHoFsULQjDSbc9fkD7G0E6Q,2493
+roborean_api_fastapi/redaction.py,sha256=enNbnty3icIwkXG1z9EE_wypxTkRwnP_-pvxoJ2m6Co,3534
+roborean_api_fastapi/security.py,sha256=CCv1e6YgZ6zyQDqxPO6UKa-2lAaQCm9fj5e-Q9DmheQ,793
+roborean_api_fastapi/settings.py,sha256=7kZmo-6A7CxqlsQfbPYH2U56GUhOs4-JiGD0yzI7lfU,688
+roborean_api_fastapi/openapi/customize.py,sha256=HcrMxGpUPuWS5ulnOFbUYT83ObBvQGHWfhwkS1EwFwE,345
+roborean_api_fastapi/routers/__init__.py,sha256=wQxFhCu-JM5hwFlhzN1G7-m-or1ZqPAm07Uh6YUxzgE,168
+roborean_api_fastapi/routers/artifacts.py,sha256=SdD56t3SMvr3UR_zUPKT5po1Cu41ymz4Kw9XX2_Rg5U,1459
+roborean_api_fastapi/routers/compile.py,sha256=eggA9ECpyLBUZEII-67z-2sOeLcEKBMbE4ypCIMukEc,1043
+roborean_api_fastapi/routers/health.py,sha256=FZIvuLwD9KcY3eu5wXEaS5hZ7T7HNWupn5as0z8tkb0,303
+roborean_api_fastapi/routers/previews.py,sha256=6YFNbVMacphZxThSD8nx6oCPkB-PxUMuedlOPG1qmUM,908
+roborean_api_fastapi/routers/projects.py,sha256=tu7VPuz4g6pVWGm0h9cEspnl4de2OdnsdQfkBrYyvc8,2262
+roborean_api_fastapi/routers/runs.py,sha256=2TKAA8Bi-pP4yn0hf2n-2KRI9aW69EvpsjIG3_BjDv4,1657
+roborean_api_fastapi/schemas/__init__.py,sha256=7skI91nUqyXfThn1xfhG-y38tjW4EbQ0COr3VnXIYUs,622
+roborean_api_fastapi/schemas/common.py,sha256=UTkRtt4Lm8W_aHG4pzUztQWjcO9_6uTRg7MpQBDHU3U,721
+roborean_api_fastapi/schemas/previews.py,sha256=Zn18pbJgx2IZbe5FL35A-nqmvimwxpeMT6kOK3Nu5II,653
+roborean_api_fastapi/schemas/projects.py,sha256=tJL79T3rFkxoINWi_nrnYMbFDS6h3G8yildOvrsQqPo,572
+roborean_api_fastapi/schemas/runs.py,sha256=tz_na0NwxJvRYVHh2fYJ2ZYqAKzbtxFgYMof8CNTRhU,1355
+roborean_api_fastapi/services/__init__.py,sha256=nD4ziTuAdNUFBJFd5jcXLezL3e7ejDaKd0BtJ2AQKMU,526
+roborean_api_fastapi/services/compile_service.py,sha256=aJJQw5eRo3rDaF-vb1rpH8jgQ3NP88jJkW8pkvz65gU,897
+roborean_api_fastapi/services/preview_service.py,sha256=a60_5b74PSowbz5Fk0MuZuXC-a9I9zo_XNSWBGYdHHc,2156
+roborean_api_fastapi/services/project_service.py,sha256=cpOya_PmqBnBCGDBRpIwry6zidXY6OB7Xi1C8glymKc,1929
+roborean_api_fastapi/services/run_service.py,sha256=iBENGAbwyByOKvZMYa6XJvcan9tFq3wlFvXZIvM-0Lw,2221
+roborean_api_fastapi-0.1.2.dist-info/METADATA,sha256=xcGAnjGYAzKcTL1mkjMx0rS9XyaEK6ErSIYC8qmaxjo,838
+roborean_api_fastapi-0.1.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+roborean_api_fastapi-0.1.2.dist-info/RECORD,,

roborean_api_fastapi-0.1.2.dist-info/WHEEL

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