function-api-builder 0.1.0__tar.gz

function_api_builder-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: function-api-builder
+Version: 0.1.0
+Summary: Generate complete FastAPI applications from decorated Python business functions.
+Author: Sushruth Samson
+License-Expression: MIT
+Keywords: api-builder,api-generator,backend,code-generation,fastapi,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: pydantic>=2.7
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# API Builder
+
+Generate a FastAPI application from decorated Python business functions.
+
+## Install
+
+```bash
+pip install function-api-builder
+```
+
+## Use
+
+Create `functions/example.py` in your project:
+
+```python
+from pydantic import BaseModel
+from api_builder_runtime import function
+
+
+class Input(BaseModel):
+    value: str
+
+
+class Output(BaseModel):
+    result: str
+
+
+@function(service="example", step=1)
+def run(payload: Input, deps, context) -> Output:
+    return Output(result=payload.value)
+```
+
+Then run:
+
+```bash
+api-builder
+```
+
+The builder writes a complete `app/` FastAPI application with a public service route, optional local development routes, health checks, OpenAPI, and generated tests.
+
+The function signature must be `(payload, deps, context)`, with Pydantic models for the payload and return value. See `examples/basic/functions/pdf_summary.py` for a multi-step service.

function_api_builder-0.1.0/README.md

@@ -0,0 +1,41 @@
+# API Builder
+
+Generate a FastAPI application from decorated Python business functions.
+
+## Install
+
+```bash
+pip install function-api-builder
+```
+
+## Use
+
+Create `functions/example.py` in your project:
+
+```python
+from pydantic import BaseModel
+from api_builder_runtime import function
+
+
+class Input(BaseModel):
+    value: str
+
+
+class Output(BaseModel):
+    result: str
+
+
+@function(service="example", step=1)
+def run(payload: Input, deps, context) -> Output:
+    return Output(result=payload.value)
+```
+
+Then run:
+
+```bash
+api-builder
+```
+
+The builder writes a complete `app/` FastAPI application with a public service route, optional local development routes, health checks, OpenAPI, and generated tests.
+
+The function signature must be `(payload, deps, context)`, with Pydantic models for the payload and return value. See `examples/basic/functions/pdf_summary.py` for a multi-step service.

function_api_builder-0.1.0/examples/basic/functions/__init__.py

@@ -0,0 +1 @@
+

function_api_builder-0.1.0/examples/basic/functions/pdf_summary.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from api_builder_runtime import FunctionError, function
+
+
+class ExtractPdfInput(BaseModel):
+    file_reference: str
+
+
+class ExtractPdfOutput(BaseModel):
+    text: str
+    page_count: int
+    source_filename: str
+
+
+class GenerateSummaryInput(BaseModel):
+    text: str
+    page_count: int
+    source_filename: str
+
+
+class GenerateSummaryOutput(BaseModel):
+    summary: str
+    key_points: list[str]
+
+
+@function(service="pdf_summary", step=1, dependencies=["pdf_extractor"])
+async def extract_pdf_text(
+    payload: ExtractPdfInput,
+    deps,
+    context,
+) -> ExtractPdfOutput:
+    return ExtractPdfOutput(
+        text="Quarterly revenue increased by twelve percent.",
+        page_count=1,
+        source_filename=payload.file_reference,
+    )
+
+
+@function(
+    service="pdf_summary",
+    step=2,
+    errors={"EMPTY_DOCUMENT": 422},
+)
+async def generate_document_summary(
+    payload: GenerateSummaryInput,
+    deps,
+    context,
+) -> GenerateSummaryOutput:
+    if not payload.text.strip():
+        raise FunctionError("EMPTY_DOCUMENT", "The document contains no readable text.")
+    return GenerateSummaryOutput(
+        summary=payload.text,
+        key_points=["Revenue increased by twelve percent."],
+    )

function_api_builder-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "function-api-builder"
+version = "0.1.0"
+description = "Generate complete FastAPI applications from decorated Python business functions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+
+authors = [
+  { name = "Sushruth Samson" }
+]
+
+keywords = [
+  "fastapi",
+  "api-builder",
+  "api-generator",
+  "backend",
+  "code-generation",
+  "pydantic"
+]
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Code Generators"
+]
+
+dependencies = [
+  "fastapi>=0.115",
+  "pydantic>=2.7",
+  "uvicorn>=0.30"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "twine>=6",
+  "pytest>=8",
+  "httpx>=0.27",
+  "ruff>=0.8",
+  "mypy>=1.13"
+]
+
+[project.scripts]
+api-builder = "api_builder.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = [
+  "src/api_builder",
+  "src/api_builder_runtime"
+]

function_api_builder-0.1.0/src/api_builder/__init__.py

@@ -0,0 +1,5 @@
+"""Generate a FastAPI app from decorated business functions."""
+
+__all__ = ["build"]
+
+from .generator import build

function_api_builder-0.1.0/src/api_builder/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

function_api_builder-0.1.0/src/api_builder/cli.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .generator import build
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="api-builder")
+    parser.add_argument("--project-root", type=Path, default=Path("."))
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument("--service")
+    parser.add_argument("--no-dev-routes", action="store_true")
+    args = parser.parse_args()
+
+    result = build(
+        args.project_root,
+        service=args.service,
+        dev_routes=not args.no_dev_routes,
+        check=args.check,
+        force=args.force,
+    )
+    print(f"generated {len(result.files)} files")
+    for route in result.routes:
+        print(f"{route.method} {route.path} {route.operation_id}")
+
+
+if __name__ == "__main__":
+    main()

function_api_builder-0.1.0/src/api_builder/generator.py

@@ -0,0 +1,868 @@
+from __future__ import annotations
+
+import compileall
+import importlib
+import inspect
+import json
+import re
+import sys
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, get_type_hints
+
+from pydantic import BaseModel
+
+GENERATOR_VERSION = "0.3.0"
+IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class BuilderError(ValueError):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionInfo:
+    name: str
+    module: str
+    service: str
+    step: int
+    description: str
+    dependencies: tuple[str, ...]
+    errors: dict[str, int]
+    input_model: type[BaseModel]
+    output_model: type[BaseModel]
+    is_async: bool
+
+
+@dataclass(frozen=True, slots=True)
+class RouteInfo:
+    method: str
+    path: str
+    operation_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class BuildResult:
+    files: tuple[Path, ...]
+    routes: tuple[RouteInfo, ...]
+
+
+def build(
+    project_root: Path = Path("."),
+    *,
+    service: str | None = None,
+    dev_routes: bool = True,
+    check: bool = False,
+    force: bool = False,
+) -> BuildResult:
+    project_root = project_root.resolve()
+    functions = discover_functions(project_root)
+    if service:
+        functions = [info for info in functions if info.service == service]
+    services = _group_services(functions)
+    _validate_services(services)
+    routes = _routes(services, dev_routes)
+    if check:
+        return BuildResult(files=(), routes=routes)
+
+    app_dir = project_root / "app"
+    files = _generate_app(app_dir, services, dev_routes, force)
+    if not compileall.compile_dir(app_dir, quiet=1):
+        raise BuilderError("GENERATED_CODE_COMPILE_FAILED", str(app_dir))
+    _validate_openapi(project_root)
+    return BuildResult(files=tuple(files), routes=routes)
+
+
+def discover_functions(project_root: Path) -> list[FunctionInfo]:
+    functions_dir = project_root / "functions"
+    if not functions_dir.exists():
+        raise BuilderError(
+            "FUNCTION_DISCOVERY_FAILED", "functions/ directory not found"
+        )
+    sys.path.insert(0, str(project_root))
+    importlib.invalidate_caches()
+    discovered: list[FunctionInfo] = []
+    for path in sorted(functions_dir.rglob("*.py")):
+        if path.name == "__init__.py":
+            continue
+        module_name = ".".join(path.relative_to(project_root).with_suffix("").parts)
+        module = importlib.import_module(module_name)
+        for _, obj in sorted(vars(module).items()):
+            metadata = getattr(obj, "__api_builder_function__", None)
+            if metadata:
+                discovered.append(_function_info(module_name, obj, metadata))
+    if not discovered:
+        raise BuilderError("FUNCTION_DISCOVERY_FAILED", "no @function functions found")
+    return discovered
+
+
+def _function_info(module_name: str, fn: Any, metadata: dict[str, Any]) -> FunctionInfo:
+    signature = inspect.signature(fn)
+    params = list(signature.parameters.values())
+    if len(params) != 3 or [param.name for param in params] != [
+        "payload",
+        "deps",
+        "context",
+    ]:
+        raise BuilderError("INVALID_FUNCTION_SIGNATURE", f"{module_name}.{fn.__name__}")
+    hints = get_type_hints(fn)
+    input_model = hints.get("payload")
+    output_model = hints.get("return")
+    if not isinstance(input_model, type) or not issubclass(input_model, BaseModel):
+        raise BuilderError(
+            "FUNCTION_INPUT_MODEL_MISSING", f"{module_name}.{fn.__name__}"
+        )
+    if not isinstance(output_model, type) or not issubclass(output_model, BaseModel):
+        raise BuilderError(
+            "FUNCTION_OUTPUT_MODEL_MISSING", f"{module_name}.{fn.__name__}"
+        )
+    service = str(metadata["service"])
+    if not IDENT.match(service):
+        raise BuilderError("FUNCTION_FORMAT_INVALID", f"invalid service: {service}")
+    dependencies = tuple(str(dep) for dep in metadata.get("dependencies", ()))
+    for dep in dependencies:
+        if not IDENT.match(dep):
+            raise BuilderError(
+                "DEPENDENCY_NOT_REGISTERED", f"invalid dependency name: {dep}"
+            )
+    return FunctionInfo(
+        name=fn.__name__,
+        module=module_name,
+        service=service,
+        step=int(metadata["step"]),
+        description=str(metadata.get("description", "")),
+        dependencies=dependencies,
+        errors={
+            str(code): int(status)
+            for code, status in metadata.get("errors", {}).items()
+        },
+        input_model=input_model,
+        output_model=output_model,
+        is_async=inspect.iscoroutinefunction(fn),
+    )
+
+
+def _group_services(functions: list[FunctionInfo]) -> dict[str, list[FunctionInfo]]:
+    services: dict[str, list[FunctionInfo]] = defaultdict(list)
+    for info in functions:
+        services[info.service].append(info)
+    return {
+        name: sorted(items, key=lambda item: item.step)
+        for name, items in sorted(services.items())
+    }
+
+
+def _validate_services(services: dict[str, list[FunctionInfo]]) -> None:
+    for service, functions in services.items():
+        steps = [info.step for info in functions]
+        if len(steps) != len(set(steps)):
+            raise BuilderError("DUPLICATE_SERVICE_STEP", service)
+        expected = list(range(1, len(steps) + 1))
+        if steps != expected:
+            raise BuilderError(
+                "MISSING_SERVICE_STEP", f"{service}: expected {expected}, got {steps}"
+            )
+        for previous, current in zip(functions, functions[1:]):
+            missing = _required_fields(current.input_model) - set(
+                previous.output_model.model_fields
+            )
+            if missing:
+                raise BuilderError(
+                    "SERVICE_SEQUENCE_INPUT_MISMATCH",
+                    f"{service}: {previous.name} -> {current.name} missing {sorted(missing)}",
+                )
+
+
+def _required_fields(model: type[BaseModel]) -> set[str]:
+    return {name for name, field in model.model_fields.items() if field.is_required()}
+
+
+def _routes(
+    services: dict[str, list[FunctionInfo]], dev_routes: bool
+) -> tuple[RouteInfo, ...]:
+    routes: list[RouteInfo] = []
+    seen: set[tuple[str, str]] = set()
+    operations: set[str] = set()
+    for service, functions in services.items():
+        public = RouteInfo(
+            "POST", f"/api/v1/{_kebab(service)}", f"run_{service}_service"
+        )
+        _add_route(public, seen, operations)
+        routes.append(public)
+        if dev_routes:
+            for info in functions:
+                route = RouteInfo(
+                    "POST",
+                    f"/__dev/functions/{_kebab(service)}/{_kebab(info.name)}",
+                    f"dev_{info.name}",
+                )
+                _add_route(route, seen, operations)
+                routes.append(route)
+    return tuple(routes)
+
+
+def _add_route(
+    route: RouteInfo, seen: set[tuple[str, str]], operations: set[str]
+) -> None:
+    key = (route.method, route.path)
+    if key in seen:
+        raise BuilderError("DUPLICATE_ROUTE", f"{route.method} {route.path}")
+    if route.operation_id in operations:
+        raise BuilderError("DUPLICATE_OPERATION_ID", route.operation_id)
+    seen.add(key)
+    operations.add(route.operation_id)
+
+
+def _generate_app(
+    app_dir: Path,
+    services: dict[str, list[FunctionInfo]],
+    dev_routes: bool,
+    force: bool,
+) -> list[Path]:
+    files: list[Path] = []
+    dirs = [
+        app_dir,
+        app_dir / "routers",
+        app_dir / "services",
+        app_dir / "generated",
+        app_dir / "tests",
+    ]
+    for directory in dirs:
+        directory.mkdir(parents=True, exist_ok=True)
+        files.append(_write_generated(directory / "__init__.py", "", force))
+    files.extend(
+        [
+            _write_generated(app_dir / "config.py", _config_py(), force),
+            _write_generated(app_dir / "context.py", _context_py(), force),
+            _write_generated(app_dir / "dependencies.py", _dependencies_py(), force),
+            _write_generated(app_dir / "errors.py", _errors_py(), force),
+            _write_generated(app_dir / "responses.py", _responses_py(), force),
+            _write_generated(app_dir / "middleware.py", _middleware_py(), force),
+            _write_generated(app_dir / "health.py", _health_py(), force),
+            _write_generated(app_dir / "main.py", _main_py(dev_routes), force),
+            _write_generated(
+                app_dir / "routers" / "public.py", _public_router_py(services), force
+            ),
+            _write_generated(
+                app_dir / "routers" / "dev.py",
+                _dev_router_py(services, dev_routes),
+                force,
+            ),
+            _write_generated(
+                app_dir / "generated" / "function_registry.py",
+                _function_registry_py(services),
+                force,
+            ),
+            _write_generated(
+                app_dir / "generated" / "service_registry.py",
+                _service_registry_py(services),
+                force,
+            ),
+            _write_generated(
+                app_dir / "generated" / "manifest.py",
+                _manifest_py(services, dev_routes),
+                force,
+            ),
+            _write_generated(
+                app_dir / "generated" / "manifest.json",
+                _manifest_json(services, dev_routes),
+                force,
+            ),
+            _write_generated(
+                app_dir / "tests" / "test_health.py", _test_health_py(), force
+            ),
+            _write_generated(
+                app_dir / "tests" / "test_openapi.py", _test_openapi_py(), force
+            ),
+        ]
+    )
+    for service, functions in services.items():
+        files.append(
+            _write_generated(
+                app_dir / "services" / f"{service}.py",
+                _service_py(service, functions),
+                force,
+            )
+        )
+    return files
+
+
+def _config_py() -> str:
+    return _py(
+        "config.py",
+        """
+from __future__ import annotations
+
+from dataclasses import dataclass
+from os import getenv
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    environment: str = getenv("ENVIRONMENT", "local")
+    internal_dev_token: str = getenv("INTERNAL_DEV_TOKEN", "dev-token")
+""",
+    )
+
+
+def _context_py() -> str:
+    return _py(
+        "context.py",
+        """
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Mapping
+from uuid import uuid4
+
+from fastapi import Request
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionContext:
+    request_id: str
+    correlation_id: str | None = None
+    actor_id: str | None = None
+    tenant_id: str | None = None
+    deadline: datetime | None = None
+    idempotency_key: str | None = None
+    metadata: Mapping[str, str] = field(default_factory=dict)
+
+
+def resolve_context(request: Request) -> ExecutionContext:
+    request_id = request.headers.get("X-Request-ID") or f"req_{uuid4().hex}"
+    request.state.request_id = request_id
+    return ExecutionContext(
+        request_id=request_id,
+        correlation_id=request.headers.get("X-Correlation-ID"),
+        idempotency_key=request.headers.get("Idempotency-Key"),
+    )
+""",
+    )
+
+
+def _dependencies_py() -> str:
+    return _py(
+        "dependencies.py",
+        """
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionDependencies:
+    function_name: str
+    resources: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceDependencies:
+    resources: dict[str, Any] = field(default_factory=dict)
+
+    def for_function(self, function_name: str) -> FunctionDependencies:
+        return FunctionDependencies(function_name=function_name, resources=self.resources)
+
+
+def get_dependencies() -> ServiceDependencies:
+    return ServiceDependencies()
+""",
+    )
+
+
+def _errors_py() -> str:
+    return _py(
+        "errors.py",
+        """
+from __future__ import annotations
+
+import logging
+
+from api_builder_runtime import FunctionError
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from .responses import ErrorEnvelope
+
+logger = logging.getLogger(__name__)
+
+
+class OutputValidationError(Exception):
+    pass
+
+
+class DevAuthenticationError(Exception):
+    pass
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    @app.exception_handler(RequestValidationError)
+    async def request_validation_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+        return _error(request, 422, "REQUEST_VALIDATION_FAILED", "Request validation failed.")
+
+    @app.exception_handler(HTTPException)
+    async def http_handler(request: Request, exc: HTTPException) -> JSONResponse:
+        return _error(request, exc.status_code, "HTTP_ERROR", "Request failed.", headers=exc.headers)
+
+    @app.exception_handler(FunctionError)
+    async def function_error_handler(request: Request, exc: FunctionError) -> JSONResponse:
+        status = getattr(request.app.state, "error_statuses", {}).get(exc.code, 500)
+        return _error(request, status, exc.code, exc.message)
+
+    @app.exception_handler(OutputValidationError)
+    async def output_handler(request: Request, exc: OutputValidationError) -> JSONResponse:
+        logger.exception("generated API output validation failed")
+        return _error(request, 500, "OUTPUT_VALIDATION_FAILED", "Generated API output validation failed.")
+
+    @app.exception_handler(DevAuthenticationError)
+    async def dev_auth_handler(request: Request, exc: DevAuthenticationError) -> JSONResponse:
+        return _error(request, 401, "DEV_AUTHENTICATION_FAILED", "Development route authentication failed.")
+
+    @app.exception_handler(Exception)
+    async def unexpected_handler(request: Request, exc: Exception) -> JSONResponse:
+        logger.exception("unexpected API failure")
+        return _error(request, 500, "UNEXPECTED_RUNTIME_FAILURE", "An unexpected internal error occurred.")
+
+
+def _error(
+    request: Request,
+    status_code: int,
+    code: str,
+    message: str,
+    *,
+    headers: dict[str, str] | None = None,
+) -> JSONResponse:
+    request_id = getattr(request.state, "request_id", "req_unknown")
+    body = ErrorEnvelope(error_code=code, message=message, request_id=request_id).model_dump()
+    return JSONResponse(status_code=status_code, content=body, headers=headers)
+""",
+    )
+
+
+def _responses_py() -> str:
+    return _py(
+        "responses.py",
+        """
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+class SuccessEnvelope(BaseModel, Generic[T]):
+    ok: bool = True
+    data: T
+    request_id: str
+
+
+class ErrorItem(BaseModel):
+    field: str | None = None
+    reason: str
+
+
+class ErrorEnvelope(BaseModel):
+    ok: bool = False
+    error_code: str
+    message: str
+    request_id: str
+    details: list[ErrorItem] = Field(default_factory=list)
+""",
+    )
+
+
+def _middleware_py() -> str:
+    return _py(
+        "middleware.py",
+        """
+from __future__ import annotations
+
+from uuid import uuid4
+
+from fastapi import FastAPI, Request
+
+
+def install_middleware(app: FastAPI) -> None:
+    @app.middleware("http")
+    async def request_id_middleware(request: Request, call_next):
+        request.state.request_id = request.headers.get("X-Request-ID") or f"req_{uuid4().hex}"
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request.state.request_id
+        return response
+""",
+    )
+
+
+def _health_py() -> str:
+    return _py(
+        "health.py",
+        """
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/healthz")
+async def healthz() -> dict[str, bool]:
+    return {"ok": True}
+
+
+@router.get("/readyz")
+async def readyz() -> dict[str, bool]:
+    return {"ok": True}
+""",
+    )
+
+
+def _main_py(dev_routes: bool) -> str:
+    include_dev = (
+        "settings.environment in {'local', 'development', 'test'}"
+        if dev_routes
+        else "False"
+    )
+    return _py(
+        "main.py",
+        f"""
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from .config import Settings
+from .errors import install_exception_handlers
+from .generated.manifest import ERROR_STATUSES
+from .health import router as health_router
+from .middleware import install_middleware
+from .routers.public import router as public_router
+from .routers.dev import router as dev_router
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or Settings()
+    app = FastAPI(title="Generated API", version="{GENERATOR_VERSION}")
+    app.state.settings = settings
+    app.state.error_statuses = ERROR_STATUSES
+    install_middleware(app)
+    install_exception_handlers(app)
+    app.include_router(health_router)
+    app.include_router(public_router)
+    if {include_dev}:
+        app.include_router(dev_router)
+    return app
+
+
+app = create_app()
+""",
+    )
+
+
+def _public_router_py(services: dict[str, list[FunctionInfo]]) -> str:
+    lines = [
+        _header("routers/public.py"),
+        "from __future__ import annotations",
+        "",
+        "from fastapi import APIRouter, Depends",
+        "",
+        "from app.context import ExecutionContext, resolve_context",
+        "from app.dependencies import ServiceDependencies, get_dependencies",
+        "from app.responses import SuccessEnvelope",
+        "",
+    ]
+    for service, functions in services.items():
+        first = functions[0]
+        last = functions[-1]
+        lines.extend(
+            [
+                f"from app.services.{service} import run_{service}_service",
+                f"from {first.module} import {first.input_model.__name__}",
+                f"from {last.module} import {last.output_model.__name__}",
+            ]
+        )
+    lines.extend(["", "router = APIRouter()", ""])
+    for service, functions in services.items():
+        first = functions[0]
+        last = functions[-1]
+        lines.extend(
+            [
+                "@router.post(",
+                f'    "/api/v1/{_kebab(service)}",',
+                f'    operation_id="run_{service}_service",',
+                f"    response_model=SuccessEnvelope[{last.output_model.__name__}],",
+                ")",
+                f"async def run_{service}_route(",
+                f"    payload: {first.input_model.__name__},",
+                "    deps: ServiceDependencies = Depends(get_dependencies),",
+                "    context: ExecutionContext = Depends(resolve_context),",
+                f") -> SuccessEnvelope[{last.output_model.__name__}]:",
+                f"    result = await run_{service}_service(payload, deps, context)",
+                "    return SuccessEnvelope(data=result, request_id=context.request_id)",
+                "",
+            ]
+        )
+    return "\n".join(lines)
+
+
+def _dev_router_py(services: dict[str, list[FunctionInfo]], dev_routes: bool) -> str:
+    lines = [
+        _header("routers/dev.py"),
+        "from __future__ import annotations",
+        "",
+        "from fastapi import APIRouter, Depends, Header, Request",
+        "from pydantic import ValidationError",
+        "",
+        "from app.context import ExecutionContext, resolve_context",
+        "from app.dependencies import ServiceDependencies, get_dependencies",
+        "from app.errors import DevAuthenticationError, OutputValidationError",
+        "from app.responses import SuccessEnvelope",
+        "",
+    ]
+    if not dev_routes:
+        lines.extend(["router = APIRouter()", ""])
+        return "\n".join(lines)
+    for functions in services.values():
+        for info in functions:
+            lines.extend(
+                [
+                    f"from {info.module} import {info.name}, {info.input_model.__name__}, {info.output_model.__name__}",
+                ]
+            )
+    lines.extend(
+        [
+            "",
+            "router = APIRouter()",
+            "",
+            'def require_dev_token(request: Request, x_internal_dev_token: str | None = Header(default=None, alias="X-Internal-Dev-Token")) -> None:',
+            "    if x_internal_dev_token != request.app.state.settings.internal_dev_token:",
+            "        raise DevAuthenticationError()",
+            "",
+        ]
+    )
+    for service, functions in services.items():
+        for info in functions:
+            call = (
+                f"await {info.name}(payload, deps.for_function({info.name!r}), context)"
+                if info.is_async
+                else f"{info.name}(payload, deps.for_function({info.name!r}), context)"
+            )
+            lines.extend(
+                [
+                    "@router.post(",
+                    f'    "/__dev/functions/{_kebab(service)}/{_kebab(info.name)}",',
+                    f'    operation_id="dev_{info.name}",',
+                    f"    response_model=SuccessEnvelope[{info.output_model.__name__}],",
+                    ")",
+                    f"async def dev_{info.name}_route(",
+                    f"    payload: {info.input_model.__name__},",
+                    "    _auth: None = Depends(require_dev_token),",
+                    "    deps: ServiceDependencies = Depends(get_dependencies),",
+                    "    context: ExecutionContext = Depends(resolve_context),",
+                    f") -> SuccessEnvelope[{info.output_model.__name__}]:",
+                    f"    raw = {call}",
+                    "    try:",
+                    f"        result = {info.output_model.__name__}.model_validate(raw)",
+                    "    except ValidationError as exc:",
+                    "        raise OutputValidationError() from exc",
+                    "    return SuccessEnvelope(data=result, request_id=context.request_id)",
+                    "",
+                ]
+            )
+    return "\n".join(lines)
+
+
+def _service_py(service: str, functions: list[FunctionInfo]) -> str:
+    lines = [
+        _header(f"services/{service}.py"),
+        "from __future__ import annotations",
+        "",
+        "from pydantic import ValidationError",
+        "",
+        "from app.context import ExecutionContext",
+        "from app.dependencies import ServiceDependencies",
+        "from app.errors import OutputValidationError",
+        "",
+    ]
+    for info in functions:
+        lines.append(
+            f"from {info.module} import {info.name}, {info.input_model.__name__}, {info.output_model.__name__}"
+        )
+    first = functions[0]
+    last = functions[-1]
+    lines.extend(
+        [
+            "",
+            f"async def run_{service}_service(",
+            f"    payload: {first.input_model.__name__},",
+            "    deps: ServiceDependencies,",
+            "    context: ExecutionContext,",
+            f") -> {last.output_model.__name__}:",
+            "    current = payload",
+        ]
+    )
+    for index, info in enumerate(functions, start=1):
+        if index > 1:
+            lines.extend(
+                [
+                    "    try:",
+                    f"        current = {info.input_model.__name__}.model_validate(current.model_dump())",
+                    "    except ValidationError as exc:",
+                    "        raise OutputValidationError() from exc",
+                ]
+            )
+        call = (
+            f"await {info.name}(current, deps.for_function({info.name!r}), context)"
+            if info.is_async
+            else f"{info.name}(current, deps.for_function({info.name!r}), context)"
+        )
+        lines.extend(
+            [
+                f"    raw_{index} = {call}",
+                "    try:",
+                f"        current = {info.output_model.__name__}.model_validate(raw_{index})",
+                "    except ValidationError as exc:",
+                "        raise OutputValidationError() from exc",
+            ]
+        )
+    lines.extend(["    return current", ""])
+    return "\n".join(lines)
+
+
+def _function_registry_py(services: dict[str, list[FunctionInfo]]) -> str:
+    lines = [_header("generated/function_registry.py"), "FUNCTIONS = ("]
+    for functions in services.values():
+        for info in functions:
+            lines.append(
+                f"    {{'service': {info.service!r}, 'step': {info.step}, 'name': {info.name!r}, 'module': {info.module!r}}},"
+            )
+    lines.extend([")", ""])
+    return "\n".join(lines)
+
+
+def _service_registry_py(services: dict[str, list[FunctionInfo]]) -> str:
+    lines = [_header("generated/service_registry.py"), "SERVICES = {"]
+    for service, functions in services.items():
+        lines.append(f"    {service!r}: {[info.name for info in functions]!r},")
+    lines.extend(["}", ""])
+    return "\n".join(lines)
+
+
+def _manifest(
+    services: dict[str, list[FunctionInfo]], dev_routes: bool
+) -> dict[str, Any]:
+    return {
+        "generated_file": "DO NOT EDIT MANUALLY",
+        "generator_version": GENERATOR_VERSION,
+        "dev_routes": dev_routes,
+        "services": {
+            service: [
+                {
+                    "name": info.name,
+                    "module": info.module,
+                    "step": info.step,
+                    "dependencies": list(info.dependencies),
+                    "errors": info.errors,
+                }
+                for info in functions
+            ]
+            for service, functions in services.items()
+        },
+    }
+
+
+def _manifest_py(services: dict[str, list[FunctionInfo]], dev_routes: bool) -> str:
+    error_statuses = {
+        code: status
+        for functions in services.values()
+        for info in functions
+        for code, status in info.errors.items()
+    }
+    return _py(
+        "generated/manifest.py",
+        f"MANIFEST = {_manifest(services, dev_routes)!r}\nERROR_STATUSES = {error_statuses!r}\n",
+    )
+
+
+def _manifest_json(services: dict[str, list[FunctionInfo]], dev_routes: bool) -> str:
+    return json.dumps(_manifest(services, dev_routes), indent=2, sort_keys=True) + "\n"
+
+
+def _test_health_py() -> str:
+    return _py(
+        "tests/test_health.py",
+        """
+from app.main import create_app
+
+
+def test_health_routes_exist():
+    app = create_app()
+    paths = set(app.openapi()["paths"])
+    assert "/healthz" in paths
+    assert "/readyz" in paths
+""",
+    )
+
+
+def _test_openapi_py() -> str:
+    return _py(
+        "tests/test_openapi.py",
+        """
+from app.main import create_app
+
+
+def test_openapi_generates():
+    schema = create_app().openapi()
+    assert "paths" in schema
+""",
+    )
+
+
+def _validate_openapi(project_root: Path) -> None:
+    sys.path.insert(0, str(project_root))
+    importlib.invalidate_caches()
+    for name in list(sys.modules):
+        if name == "app" or name.startswith("app."):
+            del sys.modules[name]
+    try:
+        module = importlib.import_module("app.main")
+        module.create_app().openapi()
+    except Exception as exc:
+        raise BuilderError("GENERATED_OPENAPI_INVALID", str(exc)) from exc
+
+
+def _write_generated(path: Path, text: str, force: bool) -> Path:
+    if path.exists() and not force:
+        existing = path.read_text()
+        if (
+            existing
+            and "GENERATED FILE" not in existing
+            and "generated_file" not in existing
+        ):
+            raise BuilderError("GENERATED_FILE_CONFLICT", str(path))
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(text)
+    tmp.replace(path)
+    return path
+
+
+def _py(name: str, body: str) -> str:
+    return (
+        _header(name)
+        + "\n".join(line.rstrip() for line in body.strip().splitlines())
+        + "\n"
+    )
+
+
+def _header(name: str) -> str:
+    return f"# GENERATED FILE - DO NOT EDIT MANUALLY\n# Source: functions/**/*.py\n# Generated: {name}\n# Generator version: {GENERATOR_VERSION}\n\n"
+
+
+def _kebab(value: str) -> str:
+    return value.replace("_", "-")

function_api_builder-0.1.0/src/api_builder_runtime/__init__.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorDetail:
+    field: str | None
+    reason: str
+    metadata: dict[str, Any] | None = None
+
+
+class FunctionError(Exception):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        details: list[ErrorDetail] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details or []
+
+
+def function(
+    *,
+    service: str,
+    step: int,
+    description: str = "",
+    dependencies: list[str] | tuple[str, ...] = (),
+    errors: dict[str, int] | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(
+            fn,
+            "__api_builder_function__",
+            {
+                "service": service,
+                "step": step,
+                "description": description,
+                "dependencies": tuple(dependencies),
+                "errors": errors or {},
+            },
+        )
+        return fn
+
+    return decorate

function_api_builder-0.1.0/tests/test_builder.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import asyncio
+import importlib
+import json
+import sys
+from pathlib import Path
+from textwrap import dedent
+
+import httpx
+import pytest
+
+from api_builder import build
+from api_builder.generator import BuilderError, discover_functions
+
+
+def write_project(root: Path) -> None:
+    functions = root / "functions"
+    functions.mkdir()
+    (functions / "__init__.py").write_text("")
+    (functions / "pdf_summary.py").write_text(
+        dedent(
+            """
+            from pydantic import BaseModel
+            from api_builder_runtime import FunctionError, function
+
+
+            class ExtractPdfInput(BaseModel):
+                file_reference: str
+
+
+            class ExtractPdfOutput(BaseModel):
+                text: str
+                page_count: int
+                source_filename: str
+
+
+            class GenerateSummaryInput(BaseModel):
+                text: str
+                page_count: int
+                source_filename: str
+
+
+            class GenerateSummaryOutput(BaseModel):
+                summary: str
+                key_points: list[str]
+
+
+            @function(service="pdf_summary", step=1, dependencies=["pdf_extractor"])
+            async def extract_pdf_text(payload: ExtractPdfInput, deps, context) -> ExtractPdfOutput:
+                return ExtractPdfOutput(
+                    text="Quarterly revenue increased by twelve percent.",
+                    page_count=1,
+                    source_filename=payload.file_reference,
+                )
+
+
+            @function(
+                service="pdf_summary",
+                step=2,
+                errors={"EMPTY_DOCUMENT": 422},
+            )
+            async def generate_document_summary(
+                payload: GenerateSummaryInput,
+                deps,
+                context,
+            ) -> GenerateSummaryOutput:
+                if not payload.text.strip():
+                    raise FunctionError("EMPTY_DOCUMENT", "The document contains no readable text.")
+                return GenerateSummaryOutput(
+                    summary=payload.text,
+                    key_points=["Revenue increased by twelve percent."],
+                )
+            """
+        )
+    )
+
+
+def clear_modules() -> None:
+    for name in list(sys.modules):
+        if (
+            name == "functions"
+            or name.startswith("functions.")
+            or name == "app"
+            or name.startswith("app.")
+        ):
+            del sys.modules[name]
+    importlib.invalidate_caches()
+
+
+def test_discovers_and_orders_functions(tmp_path: Path) -> None:
+    write_project(tmp_path)
+    clear_modules()
+    found = discover_functions(tmp_path)
+    assert [item.name for item in found] == [
+        "extract_pdf_text",
+        "generate_document_summary",
+    ]
+    assert [item.step for item in found] == [1, 2]
+
+
+def test_generation_creates_runnable_app_and_routes(tmp_path: Path) -> None:
+    write_project(tmp_path)
+    clear_modules()
+    result = build(tmp_path)
+
+    assert (tmp_path / "app/main.py").exists()
+    assert (tmp_path / "app/services/pdf_summary.py").exists()
+    assert (tmp_path / "app/generated/manifest.json").exists()
+    assert ("POST", "/api/v1/pdf-summary") in {
+        (route.method, route.path) for route in result.routes
+    }
+    assert ("POST", "/__dev/functions/pdf-summary/extract-pdf-text") in {
+        (route.method, route.path) for route in result.routes
+    }
+
+    manifest = json.loads((tmp_path / "app/generated/manifest.json").read_text())
+    assert manifest["services"]["pdf_summary"][0]["name"] == "extract_pdf_text"
+
+
+def test_http_public_dev_health_and_openapi(tmp_path: Path) -> None:
+    write_project(tmp_path)
+    clear_modules()
+    build(tmp_path)
+    sys.path.insert(0, str(tmp_path))
+    clear_modules()
+    main = importlib.import_module("app.main")
+    config = importlib.import_module("app.config")
+    app = main.create_app(
+        config.Settings(environment="test", internal_dev_token="secret")
+    )
+
+    async def run() -> None:
+        transport = httpx.ASGITransport(app=app, raise_app_exceptions=False)
+        async with httpx.AsyncClient(
+            transport=transport, base_url="http://test"
+        ) as client:
+            health = await client.get("/healthz")
+            assert health.status_code == 200
+
+            public = await client.post(
+                "/api/v1/pdf-summary", json={"file_reference": "q3.pdf"}
+            )
+            assert public.status_code == 200
+            assert public.json()["data"]["summary"].startswith("Quarterly")
+
+            missing_token = await client.post(
+                "/__dev/functions/pdf-summary/extract-pdf-text",
+                json={"file_reference": "q3.pdf"},
+            )
+            assert missing_token.status_code == 401
+
+            dev = await client.post(
+                "/__dev/functions/pdf-summary/extract-pdf-text",
+                json={"file_reference": "q3.pdf"},
+                headers={"X-Internal-Dev-Token": "secret"},
+            )
+            assert dev.status_code == 200
+            assert dev.json()["data"]["page_count"] == 1
+
+        schema = app.openapi()
+        assert "/api/v1/pdf-summary" in schema["paths"]
+        assert "/__dev/functions/pdf-summary/extract-pdf-text" in schema["paths"]
+        prod = main.create_app(
+            config.Settings(environment="production", internal_dev_token="secret")
+        )
+        assert (
+            "/__dev/functions/pdf-summary/extract-pdf-text"
+            not in prod.openapi()["paths"]
+        )
+
+    asyncio.run(run())
+
+
+def test_sequence_mismatch_fails(tmp_path: Path) -> None:
+    write_project(tmp_path)
+    path = tmp_path / "functions/pdf_summary.py"
+    path.write_text(
+        path.read_text().replace("source_filename: str", "language: str", 1)
+    )
+    clear_modules()
+    with pytest.raises(BuilderError, match="SERVICE_SEQUENCE_INPUT_MISMATCH"):
+        build(tmp_path, check=True)
+
+
+def test_idempotent_regeneration(tmp_path: Path) -> None:
+    write_project(tmp_path)
+    clear_modules()
+    build(tmp_path)
+    before = {
+        path.relative_to(tmp_path): path.read_text()
+        for path in (tmp_path / "app").rglob("*")
+        if path.is_file() and "__pycache__" not in path.parts
+    }
+    build(tmp_path)
+    after = {
+        path.relative_to(tmp_path): path.read_text()
+        for path in (tmp_path / "app").rglob("*")
+        if path.is_file() and "__pycache__" not in path.parts
+    }
+    assert before == after