Handbook

Tutorial 101 — Foundations

Developers new to LCDL who want a credential-free path: editable install, first TaskRunner call, and reading a real contract on disk.

Updated 2026-07-06

Audience

Developers new to LCDL who want a credential-free path: editable install, first TaskRunner call, and reading a real contract on disk.

Tutorial 101 foundations path

Credential-free path from editable install through a governed fake task run to reading contracts and interpreting results.

venv + pip install -e ".[dev]Create a virtual environment and install forge-lcdl in editable dev mode.
fake_chat TaskRunner smoke runExecute a governed task using fake transport instead of live APIs.
read contract.md / contract.jsonOpen the on-disk ContractSpec files for a catalog task.
interpret Ok | ErrMap task runner output to governed success or structured failure.

  venv + pip install -e ".[dev]"
      |
      v
  fake_chat TaskRunner smoke run
      |
      v
  read contract.md / contract.json
      |
      v
  interpret Ok | Err

What you will have at the end

Working venv + pip install -e ".[dev]"
One successful pw_chunk_classify run via fake_chat
Ability to open contract.md / contract.json for any catalog task and relate fields to Ok / Err

Prerequisites

Requirement	Notes
Python 3.11+	Matches `pyproject.toml`
Git checkout of forge-lcdl	Repo root = commands below
No API keys	Optional Granite/live tests are out of scope for 101

Sequence

Step	Page	Objective
1	Install and smoke	Toolchain + `pytest` baseline
2	Run a governed task	`TaskRunner` + fake JSON
3	Read a contract	ContractSpec files + `load_contract_spec`
4	Debug a failure	Force `Err` offline

Verify

From repo root (venv active):

pip install -e ".[dev]"
python -m compileall -q src tests
pytest -q
PYTHONPATH=src python3 examples/basic/run_fake_task.py

Expect pytest to pass with Granite-marked tests deselected by default (-m not granite). The example script should print Ok with merged chunks in the payload.

First hour · Getting started · Troubleshooting

Next track

When you need to author contracts, operators, and RAG flows: Tutorial 201.

Forge LCDL