First hour with Forge LCDL

Goal: prove imports, fake transport, run_task or TaskRunner, and one verification command — no live Granite URL or API key required.

Prerequisites:

• Python 3.11+
• This repo cloned with src/ layout unchanged

1. Editable install and compile check

cd forge-lcdl
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
python -m compileall -q src tests

Verify: exit code 0.

2. Run pytest (offline defaults)

pytest -q

Granite/live tests are gated with -m granite; default runs stay offline.

Verify: tests pass or only skip integration where env is absent.

3. One governed task with fake_chat (zero credentials)

PYTHONPATH=src python3 - <<'PY'
from forge_lcdl.runner import TaskRunner
from forge_lcdl.env import read_certificator_profile
from forge_lcdl.types import ChatResult


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


profile = read_certificator_profile()  # may use placeholders when no consumer .env — TaskRunner still drives parse path
runner = TaskRunner(chat=fake_chat)
r = runner.run(
    "pw_chunk_classify",
    "v1",
    {"url": "https://example.com/quiz", "chunks": [{"chunk_id": "a", "text_snippet": "Q1? Pick A,B,C,D."}]},
    profile=profile,
)
assert r.ok, r.err
payload = r.value
assert payload["chunks"][0]["chunk_id"] == "a"
print("ok:", payload["chunks"][0].get("is_question_block"))
PY

Verify: prints ok: True.

Note: read_certificator_profile may leave base_url empty when LLM_BASE_URL is unset; fake_chat still bypasses HTTP. For explicit locals: profile = read_certificator_profile({"LLM_BASE_URL": "http://example.invalid/v1", "LLM_MODEL": "none", "LLM_TIMEOUT_SEC": "120"}).

4. Inspect one contract file

Open:

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

Optional machine-readable metadata:

src/forge_lcdl/contracts/pw_chunk_classify/v1/contract.json (when present).

Verify: headings and JSON examples align with load_contract_spec output:

PYTHONPATH=src python3 - <<'PY'
from forge_lcdl.contracts_api import load_contract_spec
spec = load_contract_spec("pw_chunk_classify", "v1")
print(spec.task_id, bool(spec.input_schema.get("properties")))
PY

5. Where to go next