[2.7] Add Job Recipe API spec and design doc [skilp ci]

[chesterxgchen]

Summary

• Add docs/design/job_recipe_spec.md — the Recipe API interface design document covering:
  • User guide: constructor, export/execute, filters, config (add_server_config/add_client_config), decomposers, per-site config, model/checkpoint
  • Execution environments (SimEnv, PocEnv, ProdEnv)
  • Memory management (server_memory_gc_rounds with per-recipe defaults from codebase)
  • 14 API enhancement requirements (deploy map, multi-script/launcher, k8s, algorithm config, optional integrations, resource/GPU, client tracking, job scope, client memory)
  • Proposed API changes with recommendations (including recipe.add_resource_spec(), recipe.add_client_scripts() on base Recipe class, and noting existing add_server_config/add_client_config for algorithm overrides)
  • Real-world usage examples from BioNeMo (filters, config, decomposers)
• Add docs/design/README.md index file

Test plan

• Documentation only — no code changes
• Review rendered markdown for correctness and formatting

Made with Cursor

[greptile-apps]

Greptile Overview

Greptile Summary

Added comprehensive Recipe API design document (job_recipe_spec.md) covering user guide, interface design, and 14 enhancement requirements for release 2.7.2 and 2.8.0.

Major sections include:

• User guide with constructor patterns, export/execute workflows, filters, config methods, decomposers, per-site config, and checkpoint usage
• Three execution environments (SimEnv, PocEnv, ProdEnv) with environment-agnostic recipe design
• Memory management guidance (server-side server_memory_gc_rounds with defaults per recipe)
• 14 API enhancement requirements grouped by release (2.7.2 vs 2.8.0) covering deploy map, multi-script/launcher support, k8s, algorithm config, optional integrations, resource spec, client tracking, job scope, and client memory management
• Proposed API changes for each requirement with option comparisons and ease-of-use recommendations

The spec is a design document (not implementation) and correctly notes where proposed methods like set_resource_spec() and add_client_scripts() don't yet exist in the current Recipe base class.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Documentation-only PR adding a design spec for the Recipe API. No code changes that could introduce bugs or break existing functionality. The spec correctly distinguishes between current API and proposed future enhancements, and already-identified inconsistencies between spec and implementation have been documented in previous review threads.
• No files require special attention

Important Files Changed

Filename	Overview
docs/design/README.md	Simple index file with correct content and no issues
docs/design/job_recipe_spec.md	Comprehensive Recipe API spec with clear design proposals; minor consistency issues with proposed vs current API already noted in previous review threads

_{Last reviewed commit: 5e919e0}

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{2 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}