forge-lcdl

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).
• 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/).
• 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).
• Contract metadata: see docs/CONTRACT-SPEC.md (optional contract.json beside v1 Markdown; ContractSpec v2 extensions for RAG / inference / cache wiring).
• 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.

Generic catalog tasks (v1)

Solution-agnostic governed tasks are registered in runner.run_task via TASK_REGISTRY_V1. Examples:

Contracts live under src/forge_lcdl/contracts/<task_id>/v1/contract.md.

Deterministic games (engine vs LCDL)

• Engine (stdlib only): forge_lcdl.game_engine — legal moves, immutable states, JSON replay, reference rulesets (tic_tac_toe, nim, connect_four_like, checkers_am (American/English draughts), resource_build_lite, hidden_hand_lite, trade_lite, coop_defense_lite). See docs/GAME-ENGINE.md.
• LCDL helpers: forge_lcdl.game_lcdl builds task payloads from engine state and validates model outputs against engine move_id sets. The engine never imports LLM helpers; constrained tasks reject invented move_ids.

Page mechanics and Playwright discovery (source ingest)

Consumer repos run Playwright and validators; forge-lcdl supplies governed tasks for pw_page_kind_route, pw_quiz_mechanics_discover, pw_mechanics_repair, and related helpers. Start with docs/PLAYWRIGHT-DISCOVERY.md (end-to-end loop and payloads) and docs/PAGE-MECHANICS.md (schema split and task catalog).

Messages and transport aliases

FileRef, LlmMessage, build_openai_messages (messages.py); transport_chat_completions / transport_chat_with_policies / transport_batch_sequential / estimate_token_budget for the catalog transport surface.

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)

Layout

Replacing in-script LLM plumbing (cheat sheet)

Live Granite tests (optional integration)

Integration tests live under tests/integration/. They call the real OpenAI-compatible Granite gateway and are marked granite so default pytest stays quiet when credentials are absent: if the env file is missing or LLM_BASE_URL / API key are empty after load, those tests skip (no network).

Commands:

cd forge-lcdl
pytest -m granite          # live smoke + pw_chunk_classify (+ stress only if FORGE_LCDL_STRESS_CONTEXT=1)
pytest -m stress_context   # subset: large prompt probe (still needs Granite env + -m granite or full run)
pytest                     # unit tests + skipped integration when no env file

“Unlimited context” in catalog names is a product label, not a hard guarantee; treat stress results as informational.

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. 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.