Handbook

API and contract compatibility

Forge LCDL couples Python APIs, task IDs / versions, and JSON Schema sidecars. Treat customer-facing stability at three layers:

Updated

  1. Library Python surface (forge_lcdl.*) — SemVer in pyproject.toml; breaking signatures require a major bump unless explicitly marked experimental.
  2. Task contracts (task_id + version folder such as v1/) — input/output schemas are part of the compatibility promise for integrators using run_task.
  3. Documentation and examples — may move URLs or headings in the handbook; preserve redirects or stubs when renaming exported Markdown paths.

Compatibility categories

Label Meaning
stable Intended for production integrations; breaking changes require SemVer major or new task version folder.
beta Supported but may tighten schemas with migration notes in CHANGELOG.
alpha Experimental tasks/docs called out in ALPHA-ROADMAP; contracts may move quickly.
experimental No compatibility promise; demos only.
internal Maintainer fixtures (interaction_probe, artifact shapes) — do not ship blindly to external tenants.

Task schemas

Change Typical classification
Add optional input field with defaults / omission-safe parsers Non-breaking (same task version)
Remove, rename, or narrow required input fields Breaking → new task version directory (v2/)
Tighten output schema (fewer allowed shapes) Breaking for consumers relying on prior shapes
Loosen output schema (more optional fields) Usually non-breaking
Rename enum labels without aliases Breaking
Change task_id string Breaking — treat as a new task

Errors and transports

  • New Err codes or failure classes may ship behind minor bumps when callers already handle unknown failures gracefully.
  • Transport helpers must remain deterministic for identical inputs when documenting offline recipes.

Operators and generic helpers

Adding operators or optional kwargs is generally non-breaking. Removing or renaming public callables follows SemVer like other Python APIs.