precog-api 1.0.0__py3-none-any.whl

precog_api/__init__.py

@@ -0,0 +1,5 @@
+"""Precog REST API."""
+
+from precog_api.app import create_app
+
+__all__ = ["create_app"]

precog_api/__main__.py

@@ -0,0 +1,17 @@
+"""Package entry point: ``python -m precog_api`` / ``precog-api``."""
+
+from __future__ import annotations
+
+import uvicorn
+
+from precog_api.app import create_app
+from precog_api.config import Settings
+
+
+def main() -> None:
+    settings = Settings()
+    uvicorn.run(create_app(settings), host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

precog_api/app.py

@@ -0,0 +1,427 @@
+"""FastAPI application factory."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated, Any
+
+from fastapi import Body, Depends, FastAPI, Header, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse, Response
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+from pydantic import BaseModel
+
+from precog_api.config import Settings
+from precog_api.engine import Engine, FakeEngine
+from precog_api.mapping import to_execution_problem, to_forecast_response
+from precog_api.observability import (
+    FORECAST_SERIES,
+    INFLIGHT,
+    METRICS_EXCLUDED_PATHS,
+    MODEL_LOAD_SECONDS,
+    REQUEST_COUNT,
+    REQUEST_LATENCY,
+    configure_logging,
+    request_id_var,
+)
+from precog_api.tracing import setup_tracing
+from precog_schemas import (
+    Capabilities,
+    ExecutionFeatures,
+    ExecutionLimits,
+    ForecastRequest,
+    ForecastResponse,
+    ModelProvenance,
+)
+
+logger = logging.getLogger("precog.api")
+
+PROBLEM_MEDIA_TYPE = "application/problem+json"
+
+FORECAST_EXAMPLES: dict[str, Any] = {
+    "targets": {
+        "summary": "Single target with quantiles",
+        "value": {
+            "horizon": 4,
+            "targets": [{"id": "sales", "values": [100, 102, 101, 105, 107, 106, 108, 109]}],
+            "quantiles": [0.1, 0.5, 0.9],
+        },
+    },
+    "covariates": {
+        "summary": "Target with past-only and known-future covariates",
+        "value": {
+            "horizon": 3,
+            "targets": [{"id": "kiosk", "values": [50, 52, 51, 53, 55, 54, 56, 57]}],
+            "past_covariates": [
+                {"id": "footfall", "values": [0.1, 0.2, 0.15, 0.3, 0.4, 0.35, 0.5, 0.6]}
+            ],
+            "known_future_covariates": [
+                {
+                    "id": "promo",
+                    "history": [0, 1, 0, 0, 0, 1, 0, 0],
+                    "future": [1, 0, 0],
+                }
+            ],
+            "quantiles": [0.1, 0.9],
+        },
+    },
+    "joint_targets": {
+        "summary": "Multiple targets forecast jointly",
+        "value": {
+            "horizon": 3,
+            "targets": [
+                {"id": "a", "values": [10, 11, 12, 13, 14]},
+                {"id": "b", "values": [20, 21, 22, 23, 24]},
+            ],
+            "quantiles": [0.5],
+        },
+    },
+    "point_only": {
+        "summary": "Point-only forecast (no quantiles)",
+        "value": {
+            "horizon": 3,
+            "targets": [{"id": "cpu", "values": [1.0, 2.0, 3.0, 4.0, 5.0]}],
+            "quantiles": [],
+        },
+    },
+}
+
+
+class ProblemDetail(BaseModel):
+    """RFC 7807 problem payload."""
+
+    type: str = "about:blank"
+    title: str
+    status: int
+    detail: str | None = None
+
+
+def load_engine(settings: Settings) -> Engine:
+    """Build the configured engine."""
+    if settings.engine == "fake":
+        logger.info("using FakeEngine")
+        return FakeEngine()
+    from precog_api.engine_timesfm3 import TimesFM3Engine
+
+    logger.info("loading TimesFM-3 engine (device=%s)", settings.device)
+    return TimesFM3Engine(settings)
+
+
+def create_app(settings: Settings | None = None, engine: Engine | None = None) -> FastAPI:
+    """Create the ASGI application."""
+    settings = settings or Settings()
+    configure_logging(json_logs=settings.log_json)
+    if settings.enable_docs:
+        docs_url: str | None = "/docs"
+        redoc_url: str | None = "/redoc"
+        openapi_url: str | None = "/openapi.json"
+    else:
+        docs_url = redoc_url = openapi_url = None
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        app.state.settings = settings
+        app.state.semaphore = asyncio.Semaphore(settings.max_concurrency)
+        app.state.rate_buckets = {}
+        app.state.engine = engine
+        if app.state.engine is None:
+            started = time.perf_counter()
+            app.state.engine = load_engine(settings)
+            MODEL_LOAD_SECONDS.set(time.perf_counter() - started)
+            logger.info(
+                "precog-api %s ready (engine=%s, model=%s)",
+                app.version,
+                settings.engine,
+                settings.model_name,
+            )
+        app.state.ready = app.state.engine.ready
+        yield
+
+    app = FastAPI(
+        title="Precog API",
+        version="0.1.0",
+        summary="Zero-shot forecasting with TimesFM-3.",
+        description=(
+            "Synchronous TimesFM-3 execution. "
+            f"Limits: horizon <= {settings.max_horizon}, context <= {settings.max_context}, "
+            f"targets <= {settings.max_series}. Errors use RFC 7807 "
+            "(`application/problem+json`)."
+            + (" Bearer authentication is required." if settings.api_key else "")
+        ),
+        lifespan=lifespan,
+        docs_url=docs_url,
+        redoc_url=redoc_url,
+        openapi_url=openapi_url,
+    )
+
+    if settings.otel_enabled:
+        setup_tracing(settings.otel_service_name, fastapi_app=app)
+
+    @app.middleware("http")
+    async def _observe(request: Request, call_next: Any) -> Response:
+        request_id = request.headers.get("x-request-id") or uuid.uuid4().hex
+        token = request_id_var.set(request_id)
+        path = request.url.path
+        counted = path not in METRICS_EXCLUDED_PATHS
+        if counted:
+            INFLIGHT.inc()
+        started = time.perf_counter()
+        try:
+            if settings.rate_limit_requests > 0 and path == "/v1/forecast":
+                retry_after = _register_hit(app, settings, request)
+                if retry_after > 0:
+                    problem = ProblemDetail(
+                        title="Too Many Requests",
+                        status=429,
+                        detail=f"rate limit exceeded; retry in {retry_after}s",
+                    )
+                    response: Response = JSONResponse(
+                        status_code=429,
+                        content=problem.model_dump(),
+                        media_type=PROBLEM_MEDIA_TYPE,
+                        headers={"Retry-After": str(retry_after)},
+                    )
+                else:
+                    response = await call_next(request)
+            else:
+                response = await call_next(request)
+        finally:
+            duration = time.perf_counter() - started
+            if counted:
+                INFLIGHT.dec()
+            request_id_var.reset(token)
+        response.headers["x-request-id"] = request_id
+        if counted:
+            REQUEST_COUNT.labels(request.method, path, str(response.status_code)).inc()
+            REQUEST_LATENCY.labels(request.method, path).observe(duration)
+        logger.info(
+            "request",
+            extra={
+                "request_id": request_id,
+                "method": request.method,
+                "path": path,
+                "status": response.status_code,
+                "duration_ms": round(duration * 1000, 2),
+                "client": _client_key(request),
+            },
+        )
+        return response
+
+    @app.exception_handler(HTTPException)
+    async def _http_exception_handler(_: Request, exc: HTTPException) -> JSONResponse:
+        problem = ProblemDetail(
+            title=_status_title(exc.status_code), status=exc.status_code, detail=str(exc.detail)
+        )
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=problem.model_dump(),
+            media_type=PROBLEM_MEDIA_TYPE,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation_handler(_: Request, exc: RequestValidationError) -> JSONResponse:
+        problem = ProblemDetail(
+            title="Unprocessable Entity", status=422, detail=_format_errors(exc)
+        )
+        return JSONResponse(
+            status_code=422, content=problem.model_dump(), media_type=PROBLEM_MEDIA_TYPE
+        )
+
+    def require_api_key(authorization: str | None = Header(default=None)) -> None:
+        if not settings.api_key:
+            return
+        expected = f"Bearer {settings.api_key}"
+        if authorization != expected:
+            raise HTTPException(status_code=401, detail="invalid or missing API key")
+
+    @app.get("/healthz", tags=["ops"])
+    async def healthz() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/readyz", tags=["ops"])
+    async def readyz() -> JSONResponse:
+        ready = bool(getattr(app.state, "ready", False))
+        payload = {"status": "ready" if ready else "loading"}
+        return JSONResponse(status_code=200 if ready else 503, content=payload)
+
+    @app.get("/metrics", include_in_schema=False)
+    async def metrics() -> Response:
+        return Response(content=generate_latest(), media_type=CONTENT_TYPE_LATEST)
+
+    @app.get("/v1/capabilities", response_model=Capabilities, tags=["forecast"])
+    async def capabilities() -> Capabilities:
+        engine = app.state.engine
+        return Capabilities(
+            engine=settings.engine,
+            model=ModelProvenance(id=settings.model_id, revision=settings.model_revision),
+            device=settings.device,
+            limits=ExecutionLimits(
+                max_horizon=settings.max_horizon,
+                max_context=_min_limit(settings.max_context, engine.max_context),
+                max_variates=engine.max_variates,
+                max_targets=settings.max_series,
+            ),
+            quantile_levels=list(engine.quantile_levels),
+            features=ExecutionFeatures(
+                point_forecast=True,
+                probabilistic_forecast=True,
+                past_covariates=True,
+                known_future_covariates=True,
+                joint_targets=True,
+            ),
+            auth_required=bool(settings.api_key),
+        )
+
+    @app.post(
+        "/v1/forecast",
+        response_model=ForecastResponse,
+        dependencies=[Depends(require_api_key)],
+        tags=["forecast"],
+        summary="Forecast time series",
+        response_description="Point forecast and the caller-selected quantiles per target.",
+        responses={
+            401: {"description": "Missing or invalid API key"},
+            422: {"description": "Validation error or configured limit exceeded"},
+            429: {"description": "Rate limit exceeded"},
+            504: {"description": "Forecast timed out"},
+        },
+    )
+    async def forecast(
+        payload: Annotated[ForecastRequest, Body(openapi_examples=FORECAST_EXAMPLES)],
+    ) -> ForecastResponse:
+        _enforce_limits(payload, settings, app.state.engine)
+        problem = to_execution_problem(payload)
+        started = time.perf_counter()
+        async with app.state.semaphore:
+            try:
+                result = await asyncio.wait_for(
+                    asyncio.to_thread(app.state.engine.predict, problem),
+                    timeout=settings.request_timeout_s,
+                )
+            except TimeoutError as exc:
+                raise HTTPException(status_code=504, detail="forecast timed out") from exc
+        latency_ms = (time.perf_counter() - started) * 1000
+        FORECAST_SERIES.inc(len(payload.targets))
+        return to_forecast_response(
+            payload,
+            result,
+            model=settings.model_id,
+            revision=settings.model_revision,
+            latency_ms=round(latency_ms, 3),
+        )
+
+    return app
+
+
+def _client_key(request: Request) -> str:
+    authorization = request.headers.get("authorization")
+    if authorization:
+        return authorization
+    return request.client.host if request.client else "unknown"
+
+
+def _register_hit(app: FastAPI, settings: Settings, request: Request) -> int:
+    """Record a request and return seconds to wait (0 if allowed)."""
+    key = _client_key(request)
+    now = time.monotonic()
+    window = settings.rate_limit_window_s
+    bucket: list[float] = app.state.rate_buckets.setdefault(key, [])
+    while bucket and now - bucket[0] > window:
+        bucket.pop(0)
+    if len(bucket) >= settings.rate_limit_requests:
+        return max(1, int(window - (now - bucket[0])) + 1)
+    bucket.append(now)
+    return 0
+
+
+def _min_limit(configured: int, engine_limit: int | None) -> int:
+    """Intersect a configured limit with the active engine's effective limit."""
+    return configured if engine_limit is None else min(configured, engine_limit)
+
+
+def _max_unit_variates(payload: ForecastRequest) -> int:
+    """Variates Precog sends to the single forward pass for this problem.
+
+    Targets and covariate channels share the same execution budget.
+    """
+    return (
+        len(payload.targets) + len(payload.past_covariates) + len(payload.known_future_covariates)
+    )
+
+
+def _enforce_limits(payload: ForecastRequest, settings: Settings, engine: Engine) -> None:
+    if payload.horizon > settings.max_horizon:
+        raise HTTPException(
+            status_code=422,
+            detail=f"horizon {payload.horizon} exceeds max {settings.max_horizon}",
+        )
+    if len(payload.targets) > settings.max_series:
+        raise HTTPException(
+            status_code=422,
+            detail=f"{len(payload.targets)} targets exceed max {settings.max_series}",
+        )
+    effective_context = _min_limit(settings.max_context, engine.max_context)
+    longest = max(len(target.values) for target in payload.targets)
+    if longest > effective_context:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"context length {longest} exceeds max {effective_context}; "
+                "Precog never truncates input to fit the model context"
+            ),
+        )
+    # The target policy ceiling and the backend execution budget are distinct:
+    # targets + covariate channels share the engine's forward-pass budget.
+    if engine.max_variates is not None:
+        variates = _max_unit_variates(payload)
+        if variates > engine.max_variates:
+            raise HTTPException(
+                status_code=422,
+                detail=(
+                    f"{variates} variates exceed max {engine.max_variates}; "
+                    "Precog never drops or chunks covariates/targets to fit the model"
+                ),
+            )
+    _enforce_supported_quantiles(payload, engine)
+
+
+def _enforce_supported_quantiles(payload: ForecastRequest, engine: Engine) -> None:
+    """Reject requested quantile levels the active runtime cannot produce.
+
+    The runtime grid is the execution source of truth (#179); unsupported levels
+    fail closed before any backend column lookup.
+    """
+    supported = engine.quantile_levels
+    for level in payload.quantiles:
+        if not any(abs(level - candidate) < 1e-9 for candidate in supported):
+            allowed = ", ".join(f"{value:g}" for value in supported)
+            raise HTTPException(
+                status_code=422,
+                detail=f"unsupported quantile {level}; supported levels: {allowed}",
+            )
+
+
+def _status_title(status_code: int) -> str:
+    return {
+        401: "Unauthorized",
+        422: "Unprocessable Entity",
+        429: "Too Many Requests",
+        504: "Gateway Timeout",
+    }.get(status_code, "Error")
+
+
+def _format_errors(exc: RequestValidationError) -> str:
+    try:
+        return "; ".join(
+            f"{'.'.join(str(p) for p in err['loc'])}: {err['msg']}" for err in exc.errors()
+        )
+    except (KeyError, TypeError):
+        return "invalid request"
+
+
+__all__ = ["ProblemDetail", "create_app", "load_engine"]

precog_api/config.py

@@ -0,0 +1,49 @@
+"""Runtime configuration, loaded from ``PRECOG_*`` environment variables."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """API settings.
+
+    Every field can be overridden with a ``PRECOG_``-prefixed env var, e.g.
+    ``PRECOG_MAX_HORIZON=512``.
+    """
+
+    model_config = SettingsConfigDict(env_prefix="PRECOG_", env_file=".env", extra="ignore")
+
+    engine: Literal["fake", "timesfm3"] = "timesfm3"
+    device: str = "cpu"
+    model_path: str = "/opt/precog/models"
+    model_id: str = "google/timesfm-3.0-pytorch"
+    model_revision: str | None = None
+    cache_dir: str | None = None
+    local_files_only: bool = False
+    preload: Literal["auto", "always", "never"] = "auto"
+    preload_retries: int = 3
+    model_required: bool = True
+    prune_old_revisions: bool = False
+    hf_token: str | None = None
+    per_core_batch_size: int = 16
+    torch_threads: int = 0
+    max_concurrency: int = 1
+    request_timeout_s: float = 300.0
+    api_key: str | None = None
+    enable_docs: bool = True
+    log_json: bool = True
+    otel_enabled: bool = False
+    otel_service_name: str = "precog-api"
+    rate_limit_requests: int = 0
+    rate_limit_window_s: int = 60
+
+    max_horizon: int = 1024
+    max_context: int = 16384
+    max_series: int = 64
+
+    @property
+    def model_name(self) -> str:
+        return "timesfm-3.0"

precog_api/engine.py

@@ -0,0 +1,74 @@
+"""Engine abstraction for TimesFM-3 inference.
+
+The API talks to an :class:`Engine` over the canonical execution boundary
+(ADR 0006). Tests and local demos use :class:`FakeEngine`; production uses the
+TimesFM-3 implementation loaded lazily so the base install does not require
+torch.
+"""
+
+from __future__ import annotations
+
+from precog_api.execution import (
+    Engine,
+    ExecutionProblem,
+    ExecutionResult,
+    QuantileExecutionResult,
+    TargetExecutionResult,
+)
+
+
+class FakeEngine:
+    """Deterministic engine that repeats the last observed value."""
+
+    _QUANTILE_LEVELS: tuple[float, ...] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9)
+
+    def __init__(
+        self,
+        *,
+        ready: bool = True,
+        max_context: int | None = None,
+        max_variates: int | None = None,
+        quantile_levels: tuple[float, ...] | None = None,
+    ) -> None:
+        self._ready = ready
+        self._max_context = max_context
+        self._max_variates = max_variates
+        self._quantile_levels = (
+            tuple(quantile_levels) if quantile_levels is not None else self._QUANTILE_LEVELS
+        )
+
+    @property
+    def ready(self) -> bool:
+        return self._ready
+
+    @property
+    def max_context(self) -> int | None:
+        return self._max_context
+
+    @property
+    def max_variates(self) -> int | None:
+        return self._max_variates
+
+    @property
+    def quantile_levels(self) -> tuple[float, ...]:
+        return self._quantile_levels
+
+    def predict(self, problem: ExecutionProblem) -> ExecutionResult:
+        targets: list[TargetExecutionResult] = []
+        for target in problem.targets:
+            last = float(target.values[-1])
+            quantiles = [
+                QuantileExecutionResult(level=level, values=[last] * problem.horizon)
+                for level in problem.quantiles
+            ]
+            targets.append(
+                TargetExecutionResult(
+                    id=target.id,
+                    forecast=[last] * problem.horizon,
+                    quantiles=quantiles,
+                )
+            )
+        return ExecutionResult(targets=targets)
+
+
+__all__ = ["Engine", "FakeEngine"]

precog_api/engine_timesfm3.py

@@ -0,0 +1,211 @@
+"""TimesFM-3 engine.
+
+Imported lazily so the base installation does not require torch. The mapping
+follows the real TimesFM-3 API (``TimesFM3Evaluator.predict_batch``) validated
+during the PREC-1 spike and contains all backend-specific shape translation
+(ADR 0006): single vs joint targets, covariate stacking, known-future
+history+future concatenation, quantile-column selection and evaluator options.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from precog_api.config import Settings
+from precog_api.execution import (
+    ExecutionKnownFutureCovariate,
+    ExecutionPastCovariate,
+    ExecutionProblem,
+    ExecutionResult,
+    QuantileExecutionResult,
+    TargetExecutionResult,
+)
+
+# Used only when the engine extra is unavailable; the live evaluator is the
+# source of truth so capability enforcement cannot drift from the backend.
+_FALLBACK_MAX_VARIATES = 32
+
+
+def effective_max_variates() -> int:
+    """Variates the active TimesFM-3 evaluator accepts per forward pass.
+
+    Above this limit the evaluator subsamples covariates and chunks targets,
+    which would silently change the consumer's data; Precog rejects instead.
+    """
+    try:
+        from timesfm3.torch.evaluator import _MAX_VARIATES_PER_FORWARD
+    except ImportError:  # pragma: no cover - engine extra not installed
+        return _FALLBACK_MAX_VARIATES
+    return int(_MAX_VARIATES_PER_FORWARD)
+
+
+class TimesFM3Engine:
+    """Adapter around ``timesfm3.TimesFM3Evaluator``."""
+
+    def __init__(self, settings: Settings) -> None:
+        import torch  # noqa: PLC0415
+        from timesfm3 import ModelConfig, TimesFM3Evaluator  # noqa: PLC0415
+
+        if settings.torch_threads > 0:
+            torch.set_num_threads(settings.torch_threads)
+
+        model_dir = Path(settings.model_path)
+        if model_dir.is_dir():
+            checkpoint = settings.model_path
+            local_only = True
+        else:
+            checkpoint = settings.model_id
+            local_only = settings.local_files_only
+        config = ModelConfig(
+            checkpoint_path=checkpoint,
+            per_core_batch_size=settings.per_core_batch_size,
+            device=settings.device,
+            revision=settings.model_revision,
+            cache_dir=settings.cache_dir,
+            local_files_only=local_only,
+        )
+        self._evaluator = TimesFM3Evaluator(config)
+        # ``global_context`` is the context length the model actually honors;
+        # anything longer is truncated by the backend.
+        self._max_context = int(self._evaluator.global_context)
+        self._max_variates = effective_max_variates()
+        # The active quantile grid is the model's own, not the REST schema's.
+        self._quantile_levels = tuple(float(level) for level in self._evaluator.config.quantiles)
+        self._ready = True
+
+    @property
+    def ready(self) -> bool:
+        return self._ready
+
+    @property
+    def max_context(self) -> int:
+        return self._max_context
+
+    @property
+    def max_variates(self) -> int:
+        return self._max_variates
+
+    @property
+    def quantile_levels(self) -> tuple[float, ...]:
+        """The quantile grid the active model produces, in column order."""
+        return self._quantile_levels
+
+    def predict(self, problem: ExecutionProblem) -> ExecutionResult:
+        if len(problem.targets) == 1:
+            return self._predict_univariate(problem)
+        return self._predict_joint(problem)
+
+    def _predict_univariate(self, problem: ExecutionProblem) -> ExecutionResult:
+        target = problem.targets[0]
+        past_only = _stacked(problem.past_covariates)
+        past_future = _stacked_known(problem.known_future_covariates)
+        outputs = list(
+            self._evaluator.predict_batch(
+                contexts=[np.asarray(target.values, dtype=np.float32)],
+                horizon=problem.horizon,
+                past_only_covariates=[past_only] if past_only is not None else None,
+                past_future_covariates=[past_future] if past_future is not None else None,
+                ts_ids=[target.id],
+                **_EVALUATOR_OPTIONS,
+                return_quantiles=bool(problem.quantiles),
+            )
+        )
+        return ExecutionResult(
+            targets=[_target_result(target.id, outputs[0], problem, self._quantile_levels)]
+        )
+
+    def _predict_joint(self, problem: ExecutionProblem) -> ExecutionResult:
+        contexts = [np.asarray(target.values, dtype=np.float32) for target in problem.targets]
+        kwargs: dict[str, object] = {}
+        past_only = _stacked(problem.past_covariates)
+        past_future = _stacked_known(problem.known_future_covariates)
+        if past_only is not None:
+            kwargs["past_only_covariates"] = [past_only]
+        if past_future is not None:
+            kwargs["past_future_covariates"] = [past_future]
+        outputs = list(
+            self._evaluator.predict_batch(
+                contexts=[np.stack(contexts)],
+                horizon=problem.horizon,
+                **_EVALUATOR_OPTIONS,
+                return_quantiles=bool(problem.quantiles),
+                **kwargs,
+            )
+        )
+        output = outputs[0]
+        return ExecutionResult(
+            targets=[
+                _target_result(target.id, output, problem, self._quantile_levels, index=index)
+                for index, target in enumerate(problem.targets)
+            ]
+        )
+
+
+# Explicit evaluator options (ADR 0007): set rather than inherited, so evaluator
+# benchmark defaults cannot silently change Precog behavior.
+_EVALUATOR_OPTIONS: dict[str, object] = {
+    "use_symmetric_averaging": False,
+    "make_positive": False,
+    "sort_quantiles": True,
+    "use_znorm": False,
+    "padding_mode": "none",
+}
+
+
+def _stacked(covariates: list[ExecutionPastCovariate]) -> np.ndarray | None:
+    """Stack covariate channels into an ``(n_channels, length)`` array."""
+    if not covariates:
+        return None
+    return np.stack([np.asarray(covariate.values, dtype=np.float32) for covariate in covariates])
+
+
+def _stacked_known(known: list[ExecutionKnownFutureCovariate]) -> np.ndarray | None:
+    """Concatenate known-future ``history + future`` into the backend array."""
+    if not known:
+        return None
+    return np.stack(
+        [
+            np.asarray([*covariate.history, *covariate.future], dtype=np.float32)
+            for covariate in known
+        ]
+    )
+
+
+def _target_result(
+    target_id: str,
+    output: Any,
+    problem: ExecutionProblem,
+    quantile_levels: tuple[float, ...],
+    *,
+    index: int | None = None,
+) -> TargetExecutionResult:
+    """Normalize one backend output into a canonical target result."""
+    forecast = np.asarray(output.forecast)
+    point = forecast.reshape(-1) if index is None else np.atleast_2d(forecast)[index].reshape(-1)
+
+    quantiles: list[QuantileExecutionResult] = []
+    if problem.quantiles:
+        raw = output.quantiles
+        if raw is None:
+            raise RuntimeError("evaluator returned no quantiles although they were requested")
+        matrix = np.asarray(raw)
+        if index is not None:
+            matrix = matrix[index]
+        for level in problem.quantiles:
+            column = _column_index(level, quantile_levels)
+            quantiles.append(
+                QuantileExecutionResult(level=level, values=matrix[:, column].tolist())
+            )
+
+    return TargetExecutionResult(id=target_id, forecast=point.tolist(), quantiles=quantiles)
+
+
+def _column_index(level: float, quantile_levels: tuple[float, ...]) -> int:
+    """Map a requested level to its column in the active model quantile grid."""
+    for index, candidate in enumerate(quantile_levels):
+        if abs(candidate - level) < 1e-9:
+            return index
+    raise ValueError(f"unsupported quantile level {level}")

precog_api/execution.py

@@ -0,0 +1,114 @@
+"""Canonical Precog execution types and Engine protocol (ADR 0006).
+
+These are server-internal execution types, not HTTP DTOs. The REST wire contract
+lives in :mod:`precog_schemas`; :mod:`precog_api.mapping` translates between the
+two. The Engine boundary only sees the canonical problem and returns normalized
+predictions, never API timing or provenance.
+
+Phase 2 standalone: the API still accepts the pre-release wire contract and maps
+it onto this boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class ExecutionTarget:
+    """One target series, ordered oldest to newest."""
+
+    id: str
+    values: list[float]
+
+
+@dataclass(frozen=True)
+class ExecutionPastCovariate:
+    """A covariate known only during the historical context."""
+
+    id: str
+    values: list[float]
+
+
+@dataclass(frozen=True)
+class ExecutionKnownFutureCovariate:
+    """A covariate whose history and future values are both known."""
+
+    id: str
+    history: list[float]
+    future: list[float]
+
+
+@dataclass(frozen=True)
+class ExecutionProblem:
+    """A canonical, single-role forecasting problem.
+
+    Targets are forecast jointly, matching the semantic contract. ``quantiles``
+    is empty for point-only output.
+    """
+
+    horizon: int
+    targets: list[ExecutionTarget]
+    quantiles: list[float] = field(default_factory=list)
+    past_covariates: list[ExecutionPastCovariate] = field(default_factory=list)
+    known_future_covariates: list[ExecutionKnownFutureCovariate] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class QuantileExecutionResult:
+    """One requested quantile level and its values for a target."""
+
+    level: float
+    values: list[float]
+
+
+@dataclass(frozen=True)
+class TargetExecutionResult:
+    """Normalized point forecast and requested quantiles for one target."""
+
+    id: str
+    forecast: list[float]
+    quantiles: list[QuantileExecutionResult] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    """Normalized engine predictions only: no timing, envelope or provenance."""
+
+    targets: list[TargetExecutionResult]
+
+
+class Engine(Protocol):
+    """Minimal contract the API depends on."""
+
+    @property
+    def ready(self) -> bool:
+        """Whether the engine finished loading and can serve forecasts."""
+
+    @property
+    def max_context(self) -> int | None:
+        """Effective context length honored by the engine, or ``None`` if unbounded."""
+
+    @property
+    def max_variates(self) -> int | None:
+        """Effective variates per forward pass, or ``None`` if unbounded."""
+
+    @property
+    def quantile_levels(self) -> tuple[float, ...]:
+        """The quantile grid the active runtime can produce, in column order."""
+
+    def predict(self, problem: ExecutionProblem) -> ExecutionResult:
+        """Run one canonical execution problem and return a normalized result."""
+
+
+__all__ = [
+    "Engine",
+    "ExecutionKnownFutureCovariate",
+    "ExecutionPastCovariate",
+    "ExecutionProblem",
+    "ExecutionResult",
+    "ExecutionTarget",
+    "QuantileExecutionResult",
+    "TargetExecutionResult",
+]

precog_api/mapping.py

@@ -0,0 +1,81 @@
+"""Translation between the REST wire contract and the canonical execution
+boundary (ADR 0006).
+
+The wire contract and the canonical execution problem now share the same shape
+(Phase 2 cutover); this module keeps the engine boundary from depending on wire
+DTOs and assembles the response envelope at the API layer.
+"""
+
+from __future__ import annotations
+
+from precog_api.execution import (
+    ExecutionKnownFutureCovariate,
+    ExecutionPastCovariate,
+    ExecutionProblem,
+    ExecutionResult,
+    ExecutionTarget,
+)
+from precog_schemas import (
+    ForecastRequest,
+    ForecastResponse,
+    ModelProvenance,
+    QuantileForecast,
+    TargetForecast,
+    Usage,
+)
+
+
+def to_execution_problem(request: ForecastRequest) -> ExecutionProblem:
+    """Compile the wire request into one canonical execution problem."""
+    return ExecutionProblem(
+        horizon=request.horizon,
+        targets=[
+            ExecutionTarget(id=target.id, values=list(target.values)) for target in request.targets
+        ],
+        quantiles=list(request.quantiles),
+        past_covariates=[
+            ExecutionPastCovariate(id=covariate.id, values=list(covariate.values))
+            for covariate in request.past_covariates
+        ],
+        known_future_covariates=[
+            ExecutionKnownFutureCovariate(
+                id=covariate.id,
+                history=list(covariate.history),
+                future=list(covariate.future),
+            )
+            for covariate in request.known_future_covariates
+        ],
+    )
+
+
+def to_forecast_response(
+    request: ForecastRequest,
+    result: ExecutionResult,
+    *,
+    model: str,
+    revision: str | None,
+    latency_ms: float,
+) -> ForecastResponse:
+    """Assemble the wire response envelope around normalized engine output."""
+    return ForecastResponse(
+        horizon=request.horizon,
+        targets=[
+            TargetForecast(
+                id=target.id,
+                forecast=target.forecast,
+                quantiles=[
+                    QuantileForecast(level=quantile.level, values=quantile.values)
+                    for quantile in target.quantiles
+                ],
+            )
+            for target in result.targets
+        ],
+        model=ModelProvenance(id=model, revision=revision),
+        usage=Usage(
+            latency_ms=latency_ms,
+            context_len=len(request.targets[0].values),
+        ),
+    )
+
+
+__all__ = ["to_execution_problem", "to_forecast_response"]

precog_api/observability.py

@@ -0,0 +1,65 @@
+"""Logging and metrics helpers for the API."""
+
+from __future__ import annotations
+
+import json
+import logging
+from contextvars import ContextVar
+from typing import Any
+
+from prometheus_client import Counter, Gauge, Histogram
+
+request_id_var: ContextVar[str] = ContextVar("request_id", default="-")
+
+REQUEST_COUNT = Counter(
+    "precog_requests_total", "HTTP requests processed.", ["method", "path", "status"]
+)
+REQUEST_LATENCY = Histogram(
+    "precog_request_duration_seconds", "HTTP request duration in seconds.", ["method", "path"]
+)
+INFLIGHT = Gauge("precog_inflight_requests", "In-flight HTTP requests.")
+FORECAST_SERIES = Counter("precog_forecast_series_total", "Target series forecast.")
+MODEL_LOAD_SECONDS = Gauge("precog_model_load_seconds", "Engine load time in seconds.")
+
+# Paths excluded from request metrics (noise / scraping).
+METRICS_EXCLUDED_PATHS = frozenset({"/metrics", "/healthz", "/readyz"})
+
+_LOG_EXTRA_FIELDS = ("request_id", "method", "path", "status", "duration_ms", "client")
+_configured = False
+
+
+class JsonFormatter(logging.Formatter):
+    """Render log records as single-line JSON."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S%z"),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+            "request_id": getattr(record, "request_id", None) or request_id_var.get(),
+        }
+        for field in _LOG_EXTRA_FIELDS:
+            value = getattr(record, field, None)
+            if value is not None:
+                payload[field] = value
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False)
+
+
+def configure_logging(*, json_logs: bool = True, level: str = "INFO") -> None:
+    """Configure root logging once, with JSON or plain output."""
+    global _configured
+    if _configured:
+        return
+    handler = logging.StreamHandler()
+    if json_logs:
+        handler.setFormatter(JsonFormatter())
+    else:
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+    root = logging.getLogger()
+    root.handlers[:] = [handler]
+    root.setLevel(level)
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    _configured = True

precog_api/tracing.py

@@ -0,0 +1,44 @@
+"""Optional OpenTelemetry tracing.
+
+Enabled with ``PRECOG_OTEL_ENABLED=true``. The exporter and endpoint come from
+the standard ``OTEL_EXPORTER_OTLP_ENDPOINT`` / ``OTEL_SERVICE_NAME`` variables.
+The OpenTelemetry packages are an optional extra (``precog-api[otel]``); when
+they are missing, tracing is skipped with a warning.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+logger = logging.getLogger("precog.tracing")
+
+
+def setup_tracing(service_name: str = "precog-api", *, fastapi_app: FastAPI | None = None) -> bool:
+    """Configure a tracer provider and instrument the FastAPI app.
+
+    Returns ``True`` when tracing was configured, ``False`` when the optional
+    dependencies are not installed.
+    """
+    try:
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    except ImportError:
+        logger.warning("OpenTelemetry enabled but not installed; skipping tracing")
+        return False
+
+    provider = TracerProvider(resource=Resource.create({"service.name": service_name}))
+    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+    trace.set_tracer_provider(provider)
+
+    if fastapi_app is not None:
+        from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+
+        FastAPIInstrumentor.instrument_app(fastapi_app)
+    return True

precog_api/warmup.py

@@ -0,0 +1,148 @@
+"""Provision the TimesFM-3 weights into the model cache.
+
+Used by the container entrypoint to download the weights into a mounted volume
+when they are not already present. Works with any volume type: an ephemeral
+directory, a named volume, a bind mount or a Kubernetes PVC.
+
+The download is environment-agnostic: it only needs the Hugging Face hub layout
+under ``PRECOG_CACHE_DIR`` and the pinned revision.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import string
+import time
+from pathlib import Path
+
+from precog_api.config import Settings
+
+logger = logging.getLogger("precog.warmup")
+
+REQUIRED_FILES = ("config.json", "model.safetensors")
+
+
+def model_cache_path(settings: Settings) -> Path:
+    """Return the cache directory the engine and the downloader share."""
+    if settings.cache_dir:
+        return Path(settings.cache_dir)
+    from huggingface_hub import constants  # noqa: PLC0415
+
+    return Path(constants.HF_HUB_CACHE)
+
+
+def is_model_present(cache_dir: Path, model_id: str) -> bool:
+    """Check for a complete snapshot of ``model_id`` in the hub cache."""
+    snapshots = cache_dir / f"models--{model_id.replace('/', '--')}" / "snapshots"
+    if not snapshots.is_dir():
+        return False
+    return any(
+        all((snapshot / name).is_file() for name in REQUIRED_FILES)
+        for snapshot in snapshots.iterdir()
+        if snapshot.is_dir()
+    )
+
+
+def download_model(settings: Settings) -> None:
+    """Download the pinned model revision into the cache directory."""
+    from huggingface_hub import snapshot_download  # noqa: PLC0415
+
+    cache_dir = model_cache_path(settings)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    logger.info(
+        "downloading %s@%s into %s",
+        settings.model_id,
+        settings.model_revision or "main",
+        cache_dir,
+    )
+    snapshot_download(
+        repo_id=settings.model_id,
+        revision=settings.model_revision,
+        cache_dir=str(cache_dir),
+        token=settings.hf_token,
+    )
+
+
+def ensure_model(settings: Settings) -> bool:
+    """Ensure the model is available locally, downloading it if needed."""
+    cache_dir = model_cache_path(settings)
+    if settings.preload == "never":
+        present = is_model_present(cache_dir, settings.model_id)
+        logger.info("preload disabled; model present=%s in %s", present, cache_dir)
+        if not present and settings.model_required:
+            raise SystemExit(
+                f"model {settings.model_id} not present in {cache_dir} and PRECOG_PRELOAD=never"
+            )
+        return present
+    if settings.preload == "auto" and is_model_present(cache_dir, settings.model_id):
+        logger.info("model already present in %s", cache_dir)
+        return True
+
+    last_error: Exception | None = None
+    for attempt in range(settings.preload_retries + 1):
+        try:
+            download_model(settings)
+            return True
+        except Exception as exc:  # noqa: BLE001 - report any download failure
+            last_error = exc
+            logger.warning("download attempt %d failed: %s", attempt + 1, exc)
+            if attempt < settings.preload_retries:
+                time.sleep(min(2**attempt, 30))
+
+    message = f"failed to provision model {settings.model_id}: {last_error}"
+    if settings.model_required:
+        raise SystemExit(message)
+    logger.error("%s (continuing; startup may fail)", message)
+    return False
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    settings = Settings()
+    ensure_model(settings)
+    if settings.prune_old_revisions:
+        prune_cache(settings)
+
+
+def prune_cache(settings: Settings) -> int:
+    """Remove cached snapshots other than the pinned revision; return the count.
+
+    Only runs when ``model_revision`` is a pinned commit sha (otherwise we cannot
+    tell which snapshot is current).
+    """
+    revision = settings.model_revision or ""
+    if not (len(revision) == 40 and all(char in string.hexdigits for char in revision)):
+        logger.info("model revision is not a pinned commit; skipping cache prune")
+        return 0
+
+    cache_dir = model_cache_path(settings)
+    repo_dir = cache_dir / f"models--{settings.model_id.replace('/', '--')}"
+    snapshots = repo_dir / "snapshots"
+    if not snapshots.is_dir():
+        return 0
+
+    removed = 0
+    for snapshot in snapshots.iterdir():
+        if snapshot.is_dir() and snapshot.name != revision:
+            shutil.rmtree(snapshot, ignore_errors=True)
+            removed += 1
+    _remove_unreferenced_blobs(repo_dir)
+    logger.info("pruned %d snapshot(s) from %s", removed, snapshots)
+    return removed
+
+
+def _remove_unreferenced_blobs(repo_dir: Path) -> None:
+    """Delete blobs no longer referenced by any remaining snapshot."""
+    blobs = repo_dir / "blobs"
+    snapshots = repo_dir / "snapshots"
+    if not blobs.is_dir():
+        return
+    referenced = {str(path.resolve()) for path in snapshots.rglob("*") if path.is_symlink()}
+    for blob in blobs.iterdir():
+        if str(blob.resolve()) not in referenced:
+            blob.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    main()

precog_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: precog-api
+Version: 1.0.0
+Summary: Precog REST API exposing TimesFM-3 forecasts.
+Project-URL: Homepage, https://github.com/Albe83/precog
+Project-URL: Repository, https://github.com/Albe83/precog
+Project-URL: Issues, https://github.com/Albe83/precog/issues
+Project-URL: Changelog, https://github.com/Albe83/precog/blob/main/CHANGELOG.md
+License: MIT
+Keywords: forecasting,time-series,timesfm,zero-shot
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: numpy>=1.26
+Requires-Dist: precog-schemas<0.2.0,>=0.1.0
+Requires-Dist: prometheus-client>=0.20
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2.7
+Requires-Dist: uvicorn[standard]>=0.53.0
+Provides-Extra: engine
+Requires-Dist: timesfm[torch]>=3.0.2; extra == 'engine'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# precog-api
+
+Precog **REST Execution API**: Google
+[TimesFM-3](https://research.google/blog/timesfm-3-a-zero-shot-foundation-model-for-multivariate-forecasting/)
+zero-shot forecasting as a synchronous, typed HTTP service.
+
+This is the Python distribution of the Precog API. Containers and Helm remain
+the preferred production deployment path; install this package for development,
+labs and Python-native environments. The distribution contains **no model
+weights**.
+
+## Install
+
+```bash
+pip install precog-api             # base install: fake engine only, no torch
+pip install "precog-api[engine]"   # real TimesFM-3 engine (weights download at runtime)
+```
+
+The base install is lightweight and runs the deterministic fake engine, which is
+enough to exercise the REST contract.
+
+## Run
+
+```bash
+PRECOG_ENGINE=fake precog-api      # http://localhost:8000
+precog-api                         # real engine (requires the [engine] extra)
+```
+
+Configuration uses the `PRECOG_` prefix (`PRECOG_ENGINE`, `PRECOG_DEVICE`,
+`PRECOG_MAX_*`, `PRECOG_API_KEY`, ...). See the repository documentation.
+
+## License
+
+Application code is MIT. The TimesFM-3 model weights are distributed under the
+TimesFM Non-Commercial License v1.0 and are **not** part of this distribution.

precog_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+precog_api/__init__.py,sha256=UQksd19z7GTODzOMh3YP6t5RUPIs6l2RiXKZ11KO6pE,88
+precog_api/__main__.py,sha256=iSCHyEge_Kb3RWNxbdp_mGCLFgNLUvJ7dwIyEkNkIHQ,353
+precog_api/app.py,sha256=UVKekh8ca2fx2F_2KXnu0g7l5I5CKnwJUQ0ugSmRFec,15588
+precog_api/config.py,sha256=6T8ebJmmY6Y2tBXzw8NvB2mOeTSO9ueU8HQGKs02fmY,1446
+precog_api/engine.py,sha256=mUEERPdYw3QwyFAzzQ2HAjP52LdKi3A5scKkMJFpCOc,2169
+precog_api/engine_timesfm3.py,sha256=PBx0eCnkWLD2DRZEeK-23ymLgt6vgHa24iIq68mr_eM,7856
+precog_api/execution.py,sha256=SdAmnqkAE3sbKo1Gk-H6NRez1xxNgoiF6Kn4Zzon4SQ,3158
+precog_api/mapping.py,sha256=1kCCFaBG7LUQr02QdDfm5W0fZwihLfH_yZfGvUbH04A,2459
+precog_api/observability.py,sha256=mTijhceVPorffgtlGAfydx-5IvGoxFdSqo2h4jOQhOo,2393
+precog_api/tracing.py,sha256=e1bY6BkC8Uh5taWZM_l2_N812API98OQbs6nUTqBHLY,1644
+precog_api/warmup.py,sha256=aQ0qNet52S2yrLdGaXS13AqUAkq4S-UbIwaPS2Kg0jw,5171
+precog_api-1.0.0.dist-info/METADATA,sha256=AMV_m5HYpZQL2Uu8M3-M7Ug9ltsmwvSFsT00EVBc-6M,2525
+precog_api-1.0.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+precog_api-1.0.0.dist-info/entry_points.txt,sha256=h5BJQ_d6BKs9iSTSR5J93OjpKGLyEB3-n7FvvUdtWhA,103
+precog_api-1.0.0.dist-info/RECORD,,

precog_api-1.0.0.dist-info/WHEEL

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

precog_api-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+precog-api = precog_api.__main__:main
+precog-download-model = precog_api.warmup:main