Handbook

Example — basic task runner

Prove TaskRunner + a deterministic chat returns Ok for pw_chunk_classify without a live model.

Updated 2026-07-06

Use case

Prove TaskRunner + a deterministic chat returns Ok for pw_chunk_classify without a live model.

What it demonstrates

Injectable chat for tests and docs.
Ok result after JSON parse + schema validation.

Source

examples/basic/run_fake_task.py

Command

PYTHONPATH=src python3 examples/basic/run_fake_task.py

Inline equivalent (same logic as the script):

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

payload = {
    "chunk_results": [
        {
            "chunk_id": "c1",
            "is_question_block": False,
            "confidence": 0.5,
            "reason": "example",
        }
    ]
}

def fake_chat(messages, **kwargs):
    return ChatResult(True, json.dumps(payload))

profile = LlmEnvProfile(
    kind="certificator",
    base_url="http://localhost",
    api_key="",
    model="fake",
    timeout_sec=30,
    ngrok_bypass=False,
    prefer_json_object_mode=True,
)

runner = TaskRunner(chat=fake_chat)
r = runner.run(
    "pw_chunk_classify",
    "v1",
    {
        "url": "https://example.com",
        "chunks": [{"chunk_id": "c1", "text_snippet": "Text"}],
    },
    profile=profile,
)
print(r)
PY

Expected output

The fake chat returns JSON shaped like OpenAI tool/json output with a top-level chunk_results array—this mirrors what a model might emit before LCDL merges results back onto the caller’s chunk list.

The TaskRunner merges those rows onto the input chunks; the public Ok.value shape follows the contract’s chunks output array (each chunk carries merged labels such as is_question_block, confidence, and classify_reason).

Example line:

Ok(value={'chunks': [{'chunk_id': 'c1', 'text_snippet': 'Sample', ...}]})

Failure modes

unknown task — wrong task_id / version.
Err — malformed JSON from fake_chat or payload that fails schema (see Tutorial 101 — debug).

Forge LCDL