Skip to content

docs: refine v2 docs for accuracy against implementation#10

Open
marevol wants to merge 1 commit into
mainfrom
docs/refine-v2-accuracy
Open

docs: refine v2 docs for accuracy against implementation#10
marevol wants to merge 1 commit into
mainfrom
docs/refine-v2-accuracy

Conversation

@marevol
Copy link
Copy Markdown
Contributor

@marevol marevol commented May 23, 2026

Summary

Audit pass over the recipe-driven 2.0 documentation (English + Japanese, 24 files). Four parallel research agents cross-checked every substantive claim in the modified pages against the recotem source tree, and this PR applies the corrections that mattered.

The diff also rolls in the previously uncommitted polishing of the v2 docs that came out of earlier sessions, so the whole set of modifications lands together.

Changes Made

Serving API reference (docs/serving-api.md + ja/)

  • Response examples use the actual 12-hex request_id format (a1b2c3d4e5f6) instead of the unused req_01HZX... shape.
  • GET /v1/recipes/{name} field table marks best_class, best_params, best_score, metric, cutoff, tuning, data_stats, recotem_version, irspack_version, recipe_hash, and trained_at as nullable, matching the Pydantic schema.
  • recipe_hash is now correctly described as a bare 64-character hex digest (no sha256: prefix), distinct from config_digest.
  • UNKNOWN_USER example body matches the string the server actually emits ("user not seen during training").
  • Stub-filtering wording covers both artifact- and YAML-load failures.

Security (docs/security.md + ja/)

  • Threat-model row lists the full cloud-prefix blacklist (AWS_*, GCP_*, GOOGLE_*, AZURE_*, ALIYUN_*, ALICLOUD_*, OCI_*, IBM_*, DO_*, HCLOUD_*, DIGITALOCEAN_*).

Environment variables / Recipe reference

  • RECOTEM_METADATA_FIELD_DENY is applied at metadata-index load, so the deny list now correctly says it covers :recommend, :recommend-related, and :batch-recommend* (with include_metadata=true) instead of only the two single-recommend verbs.

Guides

  • guide/batch.md: load errors surface on /v1/health/details (and the structured log), not /v1/health — the unauthenticated endpoint only returns counts.
  • guide/index.md: a recipe exposes a set of HTTP endpoints (single + batch, user-to-item + item-to-item), not "one API endpoint" — matches the rest of the page.

Other v2 doc polish

  • Modernized endpoint paths to /v1/..., limit (not cutoff), AIP-136 colon verbs.
  • Metric renames (recotem_v1_request* family).
  • Event-field corrections (from_/to/bytes_read).
  • Japanese mirrors of every English change.

Testing

  • Cross-checked every substantive claim against /Users/shinsuke/workspace/recotem source (FastAPI app, Pydantic schemas, CLI, env-var parsing, recipe schema, metrics, Dockerfile, compose.yaml).
  • Verified Pydantic v2 UTC datetime serialization actually emits Z (rejected one false-positive finding from the audit before applying it).

Breaking Changes

None — documentation only.

Additional Notes

  • One implementation issue surfaced during the audit but is not addressed here: the image-level HEALTHCHECK in recotem/Dockerfile and recotem/compose.yaml probes /health, which does not exist on the v1-mounted server (only /v1/health does). The docs correctly warn about this and recommend overriding the probe. Worth tracking as a follow-up in the implementation repo.
  • The PR consolidates several days of v2 doc edits, so it is large but the changes are all text-only.

Audit pass over the recipe-driven 2.0 docs (English + Japanese). Cross-checks
every substantive claim in the modified pages against the recotem source tree,
correcting mismatches in the serving API reference, security threat model,
environment-variable scoping, batch artifact swap flow, and the overview page.

Notable fixes:
- serving-api.md: response examples use the actual 12-hex request_id format;
  /v1/recipes/{name} field table marks the optional fields nullable and
  distinguishes recipe_hash (bare 64-hex) from config_digest (sha256:<hex>);
  UNKNOWN_USER example matches the string the server actually emits; stub
  filtering wording covers both artifact- and YAML-load failures.
- security.md: threat-model row lists the full cloud-prefix blacklist.
- environment-variables.md / recipe-reference.md: RECOTEM_METADATA_FIELD_DENY
  is applied at metadata-index load, so it covers batch-recommend* too.
- guide/batch.md: load errors surface on /v1/health/details, not /v1/health.
- guide/index.md: a recipe now exposes a set of HTTP endpoints, not one.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant