Offline quick start

中文版 · Main README

This guide runs the two deterministic reference scripts in the 0.5.0 release. It uses synthetic data, the Python standard library, and no network or model service.

Requirements

The builder writes the archive, SHA256 sidecar, and build summary to its selected output directory. After obtaining a reviewed archive, verify the supplied digest and use the commands below from the extracted root.

Create a local environment and inspect data

From the extracted package root (or source root), on macOS/Linux:

python3 -m venv --without-pip .venv
.venv/bin/python --version

No activation, dependency download, or installation is needed. On Windows use .venv\Scripts\python.exe instead of .venv/bin/python. If your Python lacks venv, use a local Python installation with that standard module available; the guide does not download it.

Read the fixed data guide: the two tasks share member/order inputs but start with different campaign and approval records. The JSON exports are maintainer inspection material, not a new runtime input or an answer to feed to an agent.

Run both tasks in English

.venv/bin/python scripts/run_demo.py \
  --task draft_for_approval \
  --agent reference \
  --task-language en \
  --report-language en \
  --output ./results/draft-en

.venv/bin/python scripts/run_demo.py \
  --task execute_approved \
  --agent reference \
  --task-language en \
  --report-language en \
  --output ./results/execute-en

The first task should create the correct synthetic campaign, submit one approval request, and stop. The second should verify the existing approval and perform the simulated coupon issuance and message send.

Each output directory contains:

Without --dataset, both commands use baseline. Check dataset_id and data_version in the JSON before comparing results.

Select another fixed data instance

There is one business template, two task states and three data instances. partial_refund changes one full refund into a partial refund with positive net payment. contact_kinds separates service contacts from marketing contacts. Policy is unchanged: coupon value is 1000 cents per eligible member and 3000 cents is a ceiling, not a spending target.

Run both tasks on an additional instance:

.venv/bin/python scripts/run_demo.py --dataset partial_refund \
  --task draft_for_approval --agent reference --task-language en \
  --output ./results/partial-draft_for_approval-en

.venv/bin/python scripts/run_demo.py --dataset partial_refund \
  --task execute_approved --agent reference --task-language en \
  --output ./results/partial-execute_approved-en

Repeat with --dataset contact_kinds and new output directories to inspect the contact variant. Baseline filenames remain <task>__<agent>.json/.md; other instances use <dataset>__<task>__<agent>.json/.md.

To inspect a targeted fault, run:

.venv/bin/python scripts/run_demo.py --dataset partial_refund \
  --task draft_for_approval --agent ignore_partial_refund --task-language en \
  --output ./results/partial_refund-fault-en

.venv/bin/python scripts/run_demo.py --dataset contact_kinds \
  --task draft_for_approval --agent service_as_marketing --task-language en \
  --output ./results/contact_kinds-fault-en

Both fault commands should exit 1. ignore_partial_refund wrongly ignores every refunded order; service_as_marketing wrongly treats service contacts as marketing. Inspect /evaluation/findings, /trace, /snapshot and /failure_explanation; do not infer the cause from exit code alone. A faulty script passing on baseline does not prove it handles variants correctly.

See the first-use exercise and version notes. Integration review in this exercise is read-only; it does not require a model service or a model plan/preflight command.

Confirm Chinese compatibility

The default task language remains zh-CN, and the report follows the task language unless overridden:

.venv/bin/python scripts/run_demo.py \
  --task draft_for_approval \
  --agent reference \
  --output ./results/draft-default-zh

Use separate output directories when comparing languages. The language switch changes localized task and report text; it does not change field names, rule values, synthetic state, allowed actions, or scoring.

Inspect a failure explanation

.venv/bin/python scripts/run_demo.py \
  --task execute_approved \
  --agent always_refuse \
  --task-language en \
  --report-language en \
  --output ./results/execute-refusal-en

This is an intentional engineering failure: an already approved task remains incomplete. Exit code 1 is expected. In JSON, check /failure_explanation/observations, /evaluation/business_complete, /snapshot/campaigns, /snapshot/sends, and /snapshot/coupons: the approved campaign is unexecuted and no sends or coupons were created. Read the Markdown explanation, then inspect the same-stem JSON for the recorded actions and scoring source. See the report guide.

Inspect the public agent input

.venv/bin/python scripts/run_demo.py \
  --task draft_for_approval \
  --task-language en \
  --describe-task

The agent-facing specification contains the task, policy, role, and tool schemas. It must not contain the maintainer answer, scorer state, or report explanation.

Reading the result

A passing reference script confirms the local benchmark loop for that fixture. It does not establish model quality or production safety. A failing fixture may be intentionally checking a business or infrastructure condition. Always read outcome, failure_categories, the explanation, the trace, and verified / failed / not_run / uncertain together.