trade-pipeline-skill: Instructions file for Claude Code

CLAUDE.md — Instructions for AI Agents

Quick Start

# Create and activate a virtual environment first.
# macOS / Linux:
python3 -m venv .venv && source .venv/bin/activate
# Windows (PowerShell):
#   py -m venv .venv; .\.venv\Scripts\Activate.ps1

pip install -e .
python -m trade_pipeline --input examples/sample_inquiry.xlsx --order TEST01 --buyer global_fasteners

Always work inside the venv. Once activated, python and pip resolve to the venv's interpreter on every platform — no python vs python3 branching needed. Installing into the system interpreter is not an option on many setups: Homebrew and Debian mark theirs externally-managed (PEP 668) and will refuse pip install outright.

Output goes to output/TEST01/. Steps 1–7 generate: rfq.json, model.json, quotation.xlsx, pi.xlsx, ci.xlsx. Step 8 (PL) is optional and requires the separate pl-gen package.

Project Structure

trade_pipeline/
├── extractors/     # Step 1: Excel → ExtractedDocument
├── understanding/  # Steps 2-4: parse → canonicalize → assemble OrderModel
├── models/         # OrderModel dataclass (single source of truth)
├── writers/        # Steps 5-8: generate Excel documents from OrderModel
├── validation/     # review.json mechanism for human-in-the-loop
├── adapters/       # PL config resolution
├── legacy/         # Bridge to external pl-gen (optional)
├── pipeline/       # Main orchestrator (main.py) + price updater
└── config/         # config.yaml (sellers, buyers, terms, formats)

Privacy: --use-llm

The optional --use-llm flag sends the raw inquiry content (customer name, products, quantities) to the Anthropic API for parsing. It is off by default and opt-in. The default rule-based parser runs fully offline and sends nothing over the network. Avoid --use-llm for sensitive or confidential documents.

Key Rules

• All Writers read from OrderModel only — never re-parse Excel in a Writer
• Buyer match failure = hard block — generates review.json, pipeline stops
• UUID anchoring — quotation has hidden UUID column; price write-back uses UUID, not row numbers
• Config-driven — change config/config.yaml to add sellers, buyers, terms, formats