add quickstart LangChain example with end-to-end CI and 10-minute budget

[cchinchilla-dev]

Description

One of the 0.2.0 release's non-negotiable criteria is that a first-time user can pip install agentanvil + run a LangChain quickstart in under 10 minutes on a fresh venv. The quickstart is both documentation and a CI-enforced regression check.

The example must:

1. Use LangChain (most common framework; best-optimised trade-off for "popular + small").
2. Use DirectBackend (portability invariant — no AgentLoom required).
3. Be runnable offline in CI via MockBackend replay of a pre-recorded session.
4. Produce a contract YAML + Dockerfile + scenarios + HTML report — every artefact a user would touch.

Proposal

1. Directory structure:

examples/quickstart-langchain/
├── README.md                           # 5-step instructions, target 10 min
├── agent.py                            # ~50 LOC LangChain agent
├── contract.yaml                       # policies, tasks, constraints
├── Dockerfile                          # python:3.12-slim base, pins deps
├── requirements.txt                    # agentanvil, langchain-openai, etc.
├── scenarios.yaml                      # optional: hand-crafted scenarios
├── recordings/
│   └── quickstart.json                 # replay for CI
└── expected/
    ├── quickstart.report.json          # byte-exact expected output
    └── quickstart.report.html

2. README.md 5-step path:

# AgentAnvil Quickstart with LangChain

Target: first run in < 10 minutes.

## 1. Install (1 min)
pip install agentanvil

## 2. Read the contract (1 min)
Open `contract.yaml`. The agent must:
- answer the user question (task).
- never expose API keys (policy, rule).
- respond in < 5 seconds, < $0.01 per call (constraints).

## 3. Validate (30 sec)
agentanvil validate contract.yaml

## 4. Run (5 min, live) OR Replay (30 sec, offline)
# Live — requires OPENAI_API_KEY.
agentanvil run --contract contract.yaml --agent-path ./agent.py --backend direct

# Offline — uses the bundled recording.
agentanvil replay --recording recordings/quickstart.json --contract contract.yaml

## 5. Review (2 min)
Open `agentanvil-results/<run_id>.html` in your browser.

3. CI integration:

New workflow job .github/workflows/ci.yml:

quickstart-langchain:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: "3.12"
    - run: pip install -e .
    - run: pip install -r examples/quickstart-langchain/requirements.txt
    - run: |
        cd examples/quickstart-langchain
        agentanvil validate contract.yaml
        agentanvil replay --recording recordings/quickstart.json --contract contract.yaml --out-dir ./ci-output
        diff -q ci-output/*.report.json expected/quickstart.report.json

This job budgets < 3 minutes of CI time and certifies the "10-minute" user promise externally.

Scope

• examples/quickstart-langchain/agent.py
• examples/quickstart-langchain/contract.yaml
• examples/quickstart-langchain/Dockerfile
• examples/quickstart-langchain/requirements.txt
• examples/quickstart-langchain/scenarios.yaml
• examples/quickstart-langchain/recordings/quickstart.json
• examples/quickstart-langchain/expected/quickstart.report.json
• examples/quickstart-langchain/expected/quickstart.report.html
• examples/quickstart-langchain/README.md
• .github/workflows/ci.yml — new quickstart-langchain job.
• docs/quickstart.md — also points to this example.

Regression tests

• CI job quickstart-langchain green on every PR.
• test_quickstart_contract_validates_cleanly
• test_quickstart_replay_reproduces_expected_json
• test_quickstart_html_report_contains_score_breakdown

Notes

• Mock LangChain's LLM calls via the MockBackend so CI does not consume API budget.
• Live-run section of the README is documentation only — not exercised in CI.
• Breaking change risk: none.
• Depends on: add evaluator Layer 2 (single LLM-as-judge) with structured output #11, add portability invariant and determinism CI jobs #15, add first Tier A single-agent case study under examples/case-studies/ #17, ship 0.2.0: single-agent MVP with LangChain quickstart under 10 minutes #18, #019, #020.
• Blocks: #022 (portability invariant job can use this example as its probe).