docs: refine v2 docs for accuracy against implementation#10
Open
marevol wants to merge 1 commit into
Open
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/)request_idformat (a1b2c3d4e5f6) instead of the unusedreq_01HZX...shape.GET /v1/recipes/{name}field table marksbest_class,best_params,best_score,metric,cutoff,tuning,data_stats,recotem_version,irspack_version,recipe_hash, andtrained_atas nullable, matching the Pydantic schema.recipe_hashis now correctly described as a bare 64-character hex digest (nosha256:prefix), distinct fromconfig_digest.UNKNOWN_USERexample body matches the string the server actually emits ("user not seen during training").Security (
docs/security.md+ja/)AWS_*,GCP_*,GOOGLE_*,AZURE_*,ALIYUN_*,ALICLOUD_*,OCI_*,IBM_*,DO_*,HCLOUD_*,DIGITALOCEAN_*).Environment variables / Recipe reference
RECOTEM_METADATA_FIELD_DENYis applied at metadata-index load, so the deny list now correctly says it covers:recommend,:recommend-related, and:batch-recommend*(withinclude_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
/v1/...,limit(notcutoff), AIP-136 colon verbs.recotem_v1_request*family).from_/to/bytes_read).Testing
/Users/shinsuke/workspace/recotemsource (FastAPI app, Pydantic schemas, CLI, env-var parsing, recipe schema, metrics, Dockerfile, compose.yaml).Pydantic v2UTC datetime serialization actually emitsZ(rejected one false-positive finding from the audit before applying it).Breaking Changes
None — documentation only.
Additional Notes
HEALTHCHECKinrecotem/Dockerfileandrecotem/compose.yamlprobes/health, which does not exist on the v1-mounted server (only/v1/healthdoes). The docs correctly warn about this and recommend overriding the probe. Worth tracking as a follow-up in the implementation repo.