feat: v1 API overhaul (/v1 namespace, 4 inference verbs, recipe discovery)

.github/workflows/test.yml

@@ -145,10 +145,17 @@ jobs:
 
           echo "Scanning log files in $LOG_DIR ..."
 
-          # Pattern 1: raw sha256 hex digest (signing key or hash leaked)
-          if grep -rEq 'sha256:[0-9a-f]{64}' "$LOG_DIR"; then
+          # Pattern 1: raw sha256 hex digest (signing key or hash leaked).
+          # Excludes the public X-Recotem-Model-Version header and the
+          # corresponding JSON "model_version" response field, which carry
+          # the artifact content hash by design and are not secrets.
+          pat1_hits=$(grep -rEn 'sha256:[0-9a-f]{64}' "$LOG_DIR" \
+            | grep -v '"model_version"[[:space:]]*:[[:space:]]*"sha256:' \
+            | grep -vi 'x-recotem-model-version:[[:space:]]*sha256:' \
+            || true)
+          if [ -n "$pat1_hits" ]; then
             echo "FAIL: Found sha256:<hex64> in log output."
-            grep -rEn 'sha256:[0-9a-f]{64}' "$LOG_DIR" | head -5
+            echo "$pat1_hits" | head -5
             FAIL=1
           fi
 

.gitignore

@@ -51,3 +51,8 @@ az:/
 
 # Tools
 .serena/
+
+# Local working docs (plans, specs) — not for the public repo
+docs/plans/
+docs/specs/
+

CLAUDE.md

@@ -11,7 +11,7 @@ single Python package (`pip install recotem`) plus a single Docker image.
 ├──────────────────────────────────────────────────────────────────┤
 │  CLI (Typer)                                                     │
 │  ├─ recotem train   <recipe.yaml>      batch: fetch→train→sign   │
-│  ├─ recotem serve   --recipes <dir>    FastAPI /predict          │
+│  ├─ recotem serve   --recipes <dir>    FastAPI /v1/recipes/:*   │
 │  ├─ recotem inspect <artifact>         read header (no payload)  │
 │  ├─ recotem validate <recipe.yaml>     schema + connectivity     │
 │  ├─ recotem schema                     emit JSON Schema for IDEs │
@@ -52,12 +52,12 @@ src/recotem/
 
 tests/
 ├── unit/               per-module tests (recipe, artifact, training, ...)
-├── integration/        in-process train + serve + predict
+├── integration/        in-process train + serve + recommend
 ├── fuzz/               hypothesis byte mutations on artifact / recipe loaders
-└── e2e/                bash script: train → serve → curl /predict
+└── e2e/                bash script: train → serve → curl /v1/recipes/{name}:recommend
 
 docs/
-├── getting-started.md  Docker / pip walkthrough → train → /predict
+├── getting-started.md  Docker / pip walkthrough → train → /v1/recipes/{name}:recommend
 ├── recipe-reference.md every recipe field, type, default, validation
 ├── data-sources/       bigquery.md, csv.md, ga4.md, sql.md
 ├── deployment/         docker.md, k8s.md, cron.md
@@ -90,16 +90,16 @@ uv run recotem train examples/tutorial-purchase-log/recipe.yaml
 # Serve from a directory of recipes
 uv run recotem serve --recipes ./recipes/ --port 8080
 
-# Predict
-curl -X POST http://localhost:8080/predict/news_articles \
+# Recommend
+curl -X POST http://localhost:8080/v1/recipes/news_articles:recommend \
      -H "X-API-Key: <plaintext>" \
      -H "Content-Type: application/json" \
-     -d '{"user_id":"u1","cutoff":10}'
+     -d '{"user_id":"u1","limit":10}'
 ```
 
 ## Recipe model
 
-A recipe is the single source of truth: 1 YAML = 1 model = 1 `/predict/{name}`.
+A recipe is the single source of truth: 1 YAML = 1 model = 1 `/v1/recipes/{name}:recommend` (plus the related/batch verbs).
 See `docs/recipe-reference.md` for the full schema. Highlights:
 
 - `source.type` is a discriminator (`csv` | `parquet` | `bigquery` | `sql` | `ga4` | plugins).
@@ -146,9 +146,11 @@ Binary container `magic | version | reserved | kid | hmac | header_json | payloa
   `uv run ruff format src tests`). Line-length 88. Selected rules in
   `pyproject.toml`.
 - pytest 8 + hypothesis 6. `@pytest.mark.slow` deselected by default.
-- `from __future__ import annotations` is used everywhere except where it
-  breaks FastAPI dependency introspection (e.g. `routes.py` uses
-  `kid: str = Depends(_require_auth)` instead of `Annotated[...]`).
+- `from __future__ import annotations` is used everywhere, including the
+  serving router. FastAPI dependency arguments are written as
+  `kid: str = Depends(_require_auth)` (not `Annotated[...]`) in
+  `serving/routes.py` so that `Depends` is resolved as a runtime
+  default rather than a stringified annotation.
 - structlog logger per module; the redaction processor in
   `recotem.log_redaction` is first in the chain and strips API keys, signing
   keys, and cloud creds. Lives at the top level so `train`-only invocations do
@@ -208,7 +210,7 @@ uv run ruff format --check src tests
 | `RECOTEM_MAX_PAYLOAD_BYTES` | 512 MiB | Per-payload cap (post-HMAC-verify) for serve-side deserialization. Clamped [1 MiB, 16 GiB]. Smaller than `RECOTEM_MAX_ARTIFACT_BYTES` to bound deserialization memory expansion. |
 | `RECOTEM_ARTIFACT_ROOT` | (empty) | If set, local `output.path` must lie under it. |
 | `RECOTEM_RECIPE_*` | — | Allow-listed for `${...}` recipe expansion. |
-| `RECOTEM_METADATA_FIELD_DENY` | (empty) | Comma-separated columns stripped from `/predict` responses. |
+| `RECOTEM_METADATA_FIELD_DENY` | (empty) | Comma-separated columns stripped from `/v1/recipes/{name}:recommend` and `:recommend-related` responses. |
 | `RECOTEM_METRICS_ENABLED` | (empty) | Opt-in Prometheus `/metrics` endpoint. Truthy values: `1`, `true`, `yes`, `on`. Requires `recotem[metrics]` extra. |
 | `RECOTEM_LOCK_DIR` | (empty) | Override directory for per-recipe training lock files. Local outputs always lock at `<output_path>.lock`; remote outputs (`s3://`, `gs://`, ...) need a host-local path and fall back to `<tempdir>/recotem-locks/`. `flock` is host-local — across hosts use scheduler-level mutex (`concurrencyPolicy: Forbid`). |
 | `RECOTEM_BQ_REQUIRE_STORAGE_API` | (empty) | When truthy (`1`/`true`/`yes`/`on`), the BigQuery source raises `DataSourceError` instead of falling back to the REST path when the Storage Read API fails. Requires the service account to hold `bigquery.readSessions.create`. |

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Recotem is a single Python package with two execution modes:
 
 - `recotem train recipe.yaml` — fetch → train → write a signed artifact.
 - `recotem serve --recipes <dir>` — FastAPI server that watches the dir and
-  serves `/predict/{name}` for every loaded recipe.
+  serves `/v1/recipes/{name}:*` for every loaded recipe.
 
 The two modes communicate only via the signed artifact file format, so the
 trainer and the server can run on completely separate hosts.

README.md

@@ -9,8 +9,9 @@ Recipe-driven recommender training and serving, built on
 [irspack](https://github.com/tohtsky/irspack). One YAML recipe describes
 where the data lives, how to train, and where to write the result —
 `recotem train` produces a signed binary artifact, `recotem serve`
-mounts it as a `/predict/{name}` HTTP endpoint and hot-swaps when a new
-artifact appears. No database, no message broker, no admin UI.
+mounts it under `/v1/recipes/{name}:recommend` (plus `:recommend-related`
+and batch verbs) and hot-swaps when a new artifact appears. No database,
+no message broker, no admin UI.
 
 ## Why Recotem
 
@@ -32,7 +33,7 @@ moving parts to a recipe file and a binary artifact:
 
 ## Features
 
-- Recipe-driven: 1 YAML = 1 model = 1 `/predict/{name}` endpoint
+- Recipe-driven: 1 YAML = 1 model = 1 `/v1/recipes/{name}:recommend` endpoint (with related/batch verbs)
 - Hyperparameter search across irspack algorithms via Optuna
 - Pluggable data sources (built-in: CSV / Parquet / BigQuery / SQL / GA4; extend via Python entry points)
 - HMAC-signed artifacts with multi-key rotation and a deterministic
@@ -84,21 +85,28 @@ recotem train examples/quickstart/recipe.yaml
 recotem serve --recipes examples/quickstart/ &
 
 # Wait for the server to become ready before sending traffic.
-until curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/health | grep -q "200"; do sleep 1; done
+until curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/v1/health | grep -q "200"; do sleep 1; done
 
-# 3. Predict
-curl -X POST http://localhost:8080/predict/top_picks \
+# 3. Recommend
+# 3a. Recommend for a known user
+curl -X POST http://localhost:8080/v1/recipes/top_picks:recommend \
   -H "X-API-Key: $RECOTEM_API_PLAINTEXT" \
   -H "Content-Type: application/json" \
-  -d '{"user_id": "u01", "cutoff": 5}'
+  -d '{"user_id": "u01", "limit": 5}'
+
+# 3b. Recommend items related to a seed item
+curl -X POST http://localhost:8080/v1/recipes/top_picks:recommend-related \
+  -H "X-API-Key: $RECOTEM_API_PLAINTEXT" \
+  -H "Content-Type: application/json" \
+  -d '{"seed_items": ["i00"], "limit": 5}'
 ```
 
 ```json
 {
-  "items": [{"item_id": "i00", "score": 0.91}],
-  "model": {"recipe": "top_picks", "trained_at": "...",
-            "best_class": "TopPopRecommender", "kid": "dev"},
-  "request_id": "..."
+  "request_id": "req_01HZX...",
+  "recipe": "top_picks",
+  "model_version": "sha256:abc...",
+  "items": [{"item_id": "i00", "score": 0.91}]
 }
 ```
 
@@ -112,8 +120,8 @@ for the source of truth and
 | Variable | Required by | Purpose |
 |---|---|---|
 | `RECOTEM_SIGNING_KEYS` | `train` and `serve` | HMAC sign / verify artifact files (server keeps plaintext; needed for both sides) |
-| `RECOTEM_API_KEYS` | `serve` | Authenticate `/predict` callers (server keeps **hash** only) |
-| `X-API-Key: <plaintext>` | HTTP clients | Sent by clients on every `/predict` call; server re-hashes and compares |
+| `RECOTEM_API_KEYS` | `serve` | Authenticate `/v1/recipes/*` callers (server keeps **hash** only) |
+| `X-API-Key: <plaintext>` | HTTP clients | Sent by clients on every `/v1/recipes/*` call; server re-hashes and compares |
 
 Both variables accept multiple comma-separated entries (`kid:value,kid2:value,…`)
 to enable zero-downtime key rotation — that is why they are pluralised.
@@ -129,7 +137,7 @@ to enable zero-downtime key rotation — that is why they are pluralised.
 │                   (batch job)        (HMAC-signed)        (FastAPI,    │
 │                                                            hot-swap)   │
 │                                                                        │
-│   any scheduler          local FS, S3,             POST /predict/{name}│
+│   any scheduler          local FS, S3,         POST /v1/recipes/{name} │
 │   (cron / k8s / …)       GCS, fsspec               X-API-Key auth      │
 │                                                                        │
 └────────────────────────────────────────────────────────────────────────┘

compose.yaml

@@ -20,10 +20,10 @@
 #   3. Serve + curl
 #      $ RECOTEM_SIGNING_KEYS="..." RECOTEM_API_KEYS="..." \
 #        docker compose up -d serve
-#      $ curl -sX POST http://localhost:8080/predict/purchase_log \
+#      $ curl -sX POST http://localhost:8080/v1/recipes/purchase_log:recommend \
 #          -H "X-API-Key: <api plaintext>" \
 #          -H "Content-Type: application/json" \
-#          -d '{"user_id": "1", "cutoff": 5}'
+#          -d '{"user_id": "1", "limit": 5}'
 
 x-recotem-image: &recotem-image
   image: ghcr.io/codelibs/recotem:latest

docs/README.md

@@ -2,7 +2,7 @@
 
 ## Getting started
 
-- [Getting started](getting-started.md) — install (Docker or pip), train from a public CSV, curl `/predict`
+- [Getting started](getting-started.md) — install (Docker or pip), train from a public CSV, curl `/v1/recipes/{name}:recommend`
 
 ## Reference