forge-lcdl

Start here (short): What is LCDL? · Getting started · Tutorial 101 · Adoption · Troubleshooting · For agents · Handbook publishing.

Private Python library: governed synchronous LLM tasks, domain-agnostic OpenAI-compatible helpers (forge_lcdl.generic), and control-flow operators (forge_lcdl.operators) for scripts that embed LLM calls without scattering transport and JSON quirks.

• Location: sibling repo under Code/forge-lcdl (not ~/LCDL/).
• Python: 3.11+
• Alpha / dogfood: docs/ALPHA-ROADMAP.md, docs/DOGFOODING.md, offline smoke script scripts/lcdl_alpha_check.py.
• Gateway timeout isolation: scripts/curl_chat_gateway_probe.sh (curl minimal vs heavy POST, same URL as forge_lcdl.generic.urls), scripts/gateway_probe_lcdl.py (chat_completion_sync parity), scripts/emit_heavy_gateway_probe_prompt.py (print or save the heavy user-message blob). For KS UX harness --llm, probe quota with python3 scripts/gateway_probe_lcdl.py --env-file /path/to/lcdl.env after loading profile via read_profile_from_env_file in forge_lcdl.env.
• Phased subprocess gates: forge_lcdl.testing.phased_gates (run_until_exit_zero, between_attempts improve hook after each failed A try before retry, optional argv_factory, python_script_between_attempts); CLI scripts/phased_gate_run.py supports --between-a-script.
• Cursor integration: docs/CURSOR-INTEGRATION.md (rules, skills, agents under .cursor/).
• Blueprints submodule: blueprints/ → autowww/blueprints (run git submodule update --init --recursive after clone). Forge SDLC layout: forge/forge.config.yaml, forge/, ember-logs/, forge-logs/. After bumping blueprints, re-sync Cursor rules: bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync --preset recommended, then bash …/sync-forge-cursor-rules.sh sync, then bash …/check.
• MCP: docs/MCP-CLIENT.md (Python client — Playwright MCP, policy, examples); docs/MCP-SIDECAR.md (LCDL as MCP tools in Cursor).
• Cheap-model loop: docs/CHEAP-MODEL-OPERATING-GUIDE.md.
• Benchmarks: see docs/BENCHMARKS.md (offline fake transport by default; optional --live; includes lcdl_dogfood_alpha).
• Schemas + ContractSpec catalog: docs/SCHEMAS.md, docs/CONTRACT-SPEC.md; sidecars (generate_contract_sidecars.py, audit_contract_docs.py [--strict]).
• Execution / RAG / graph: docs/CLIENT-API.md, docs/EXECUTION-ENGINE.md, docs/RAG.md, docs/PROMPT-CACHING.md, docs/TASK-PACKS.md.
• Model routing: see docs/MODEL-ROUTING.md (offline profiles and cheap-first ModelRouter; does not replace LlmEnvProfile).
• Decomposition graph: see docs/GRAPH.md (forge_lcdl.graph — DecisionPack parse, DAG validation, sequential GraphExecutor).
• Context packs: see docs/CONTEXT-PACKS.md (forge_lcdl.context — bounded repo context from a task string, no LLM).
• Verification: see docs/VERIFICATION.md (forge_lcdl.verification — schema/shape checks, optional subprocess, registry).
• Repair loops: see docs/REPAIR-LOOPS.md (forge_lcdl.repair — failure taxonomy, retry memory, deterministic repair hints).
• Coding executor: see docs/CODING-EXECUTOR.md (forge_lcdl.coding — patch units, planner, proof reports; no auto-apply in library).

Responsible use and boundaries

Use this library for authorized practice material you own, internal QA, and question-bank ingestion with explicit rights to the content. Do not build bypasses for proctored exams, paywalls, logins, CAPTCHA, rate limits, or anti-bot measures; do not add credential theft or logging of secrets (API keys, tokens, raw auth headers, full .env). Prefer deterministic extraction and validation; keep browser execution in consumers/runtime, not inside LCDL tasks. Full contributor policy: CONTRIBUTING.md.

Install

cd forge-lcdl
pip install -e ".[dev]"
pytest

Quick use

from forge_lcdl import (
    read_certificator_profile,
    run_task,
    TaskRunner,
)
from forge_lcdl.generic import chat_with_json_mode_then_plain, parse_json_object_lenient
from forge_lcdl.operators import fallback_chain, until_ok
from forge_lcdl.result import Err, Ok

Task runner (reference: chunk classify)

profile = read_certificator_profile()
out = run_task(
    "pw_chunk_classify",
    "v1",
    {"url": "https://example.com/exam", "chunks": [{"chunk_id": "a", "text_snippet": "Q1?"}]},
    profile=profile,
)

Contract: src/forge_lcdl/contracts/pw_chunk_classify/v1/contract.md.

Injectable transport (tests)

def fake_chat(messages, **kwargs):
    from forge_lcdl.types import ChatResult
    return ChatResult(True, '{"chunk_results":[{"chunk_id":"a","is_question_block":true,"confidence":0.9,"reason":"mcq"}]}')

runner = TaskRunner(chat=fake_chat)
runner.run("pw_chunk_classify", "v1", {...}, profile=profile)

Handbook (canonical narrative — keep in sync with this README)

Long-form onboarding, catalog tables, games vs LLM boundaries, Playwright/page-mechanics ingest, MCP/Cursor wiring, benchmarks, operators, extraction convergence, adoption notes, and LLM-plumbing cheat sheets live under docs/ and publish at lcdl.forgesdlc.com. Treat docs/index.md as the homepage narrative so GitHub and the static handbook cannot drift.

Package layout (abbrev.)

Live Granite tests (optional)

See live-granite-tests.md for env vars, markers, and pytest commands (pytest -m granite when credentials exist).

Demo repositories (sibling)

Optional consumer demos such as lcdl-snippets are described from the handbook Examples hub — they ship outside this wheel.

Sibling package: forge-lcdl-runtime

Disk-backed ChatSession, RAG-lite rag_concat_prefix, decision tables/trees, matrix helpers, and Playwright/MCP bridge stubs live in the separate repo ../forge-lcdl-runtime (open README.md there after cloning the sibling checkout). Install with pip install -e . from that folder after editable forge-lcdl.

Git

Initialize a private remote (GitHub/GitLab) and push this tree. Do not commit .env files or live gateway URLs.