Handbook

Enterprise architecture

Forge LCDL is a Python library boundary. Everything outside that boundary is owned by consumers, platforms, or operators.

Updated

Responsibility matrix (runtime)

Concern LCDL Consumer / pipeline Model gateway
Task JSON in/out schemas Owns contract + validation Owns domain payloads and UX N/A
Chat transport Helpers + injectable chat May wrap auth, logging, routing Owns completion + errors
Playwright / browsers Does not run browsers Owns launch, policy, URLs N/A
Evidence / retrieval interfaces Defines task contracts + RAG hooks Implements retrievers, stores N/A

Runtime responsibility lanes

How LCDL, the consumer application, and the model gateway divide governed task execution at the enterprise boundary.

  1. LCDL ─ contracts registry run_task operators verification retrieval interfacesPython library zone for versioned contracts, task dispatch, and verification primitives.
  2. Consumer ─ business logic UX browsers Playwright secrets deploymentApplication and operator layer for domain logic, UX, and runtime infrastructure.
  3. Gateway ─ chat completions routing latency model IDsExternal chat completion plane reached through injectable transport helpers.

Layers

Layer Owns
LCDL Task contracts, registry, run_task / TaskRunner, generic OpenAI-compatible helpers, operators, verification/repair primitives, retrieval interfaces.
Consumer app / repo Business logic, persistence, UX, browser / Playwright runtime where applicable, secret storage, deployment.
Model gateway Chat completions behavior, availability, latency, model IDs (LCDL consumes via LlmEnvProfile + transport).
CI / release Tests, audit_contract_docs, audit_docs_site, benchmarks, publishing the handbook submodule.

Sequence (textual)

  1. Caller builds payload + selects task_id / version.
  2. run_task resolves implementation + contract; optional chat injection.
  3. Transport returns text → parse → validate against contract output schema → Ok or Err.
  4. Optional verification / repair layers (consumer or LcdlClient wiring).