Giraffe Agent — Universal Order Execution Model - MCP Server
🦒 Giraffe Agent — Universal Order Execution Model - MCP Server
Every industrial order should run a delivery feasibility simulation before confirmation.
What is Giraffe Agent
Giraffe Agent is an industrial order execution agent.
It is not a chatbot or a supplier directory. It starts from a buyer's existing communication channel — a raw RFQ email — and automatically expands it into multi-supplier inquiry, upstream evidence checks, delivery feasibility simulation, rejected-path reasoning, Top 3 decision paths, and a buyer-ready reply email.
The v9 email-native demo starts from a raw buyer RFQ email and expands it into:
- 10 supplier inquiry emails
- Supplier reply processing (complete, incomplete, and ambiguous replies)
- Upstream evidence checks (fabric, logistics, QC, packaging, subcontracting)
- Supplier response rollups combining reply evidence and upstream confirmation
- Delivery path simulation (13 paths across multiple strategies)
- Rejected-path reasoning with explicit business explanations
- Top 3 buyer decision paths ranked by scoring model
- Buyer-ready reply email draft
- Industrial Execution Graph
MCP Tool Layer (v10)
python scripts/run_mcp_server.py --test # smoke test (26 checks)
python scripts/run_mcp_server.py --list # list all 21 tools
python scripts/run_mcp_server.py --help # usage help
python scripts/run_mcp_server.py # start stdio MCP server
Note:
--testis a smoke test. Runpytest -qfor full regression coverage (180 tests).
The MCP layer exposes 21 tools covering the full email-native workflow: buyer email → requirement parsing → supplier RFQs → upstream node confirmation → lead-time calculation → dynamic path enumeration → Top 3 ranking → artifact generation.
Top 3 ranking tie-break rule (deterministic):
- Score (descending)
- Shelf-date buffer days (descending)
- Split-delivery paths ranked above single-batch at equal score
- Delivery risk score (ascending)
- Path ID (ascending — stable alphabetical)
See docs/mcp_server.md for full tool reference.
Quickstart — v9 Email-Native Demo (Recommended Entry Point)
pip install -e .
python scripts/run_email_shirt_order_demo.py
pytest -q
This demo starts from a raw .eml buyer RFQ email from sourcing@sakura-fashion.jp and produces all 15 artifacts in artifacts/demo_email_shirt_order/.
Quickstart — v8 Baseline Python Demo
pip install -e .
python scripts/run_shirt_order_demo.py
pytest -q
This demo converts a structured shirt procurement request into supplier RFQs, response packets, delivery feasibility simulation, Top 3 delivery paths, and an AI Merchandiser execution plan.
Repository Structure
src/
├── giraffe_agent/
│ ├── channel_gateway/ # Email gateway — parses .eml into EmailEvent
│ │ └── email_gateway.py
│ └── demo_scenarios/
│ ├── email_shirt_order_10k.py # v9 email-native demo engine
│ └── shirt_order_10k.py # v8 baseline engine demo
├── engine/ # TypeScript — order execution engine (experimental)
│ ├── types.ts scheduler.ts critical-path.ts
│ ├── route-tree.ts pruning.ts scoring.ts
│ └── decision-packet.ts execution-plan.ts
└── scenarios/ # TypeScript — three demonstration scenarios (experimental)
├── dress-demo.ts
├── shirt-10000-demo.ts
└── cnc-demo.ts
fixtures/
├── emails/
│ ├── inbound_buyer_rfq_shirt_10k.eml
│ └── supplier_replies/ # 10 supplier reply .eml fixtures
artifacts/
└── demo_email_shirt_order/ # 15 generated artifacts from v9 demo
├── 01_inbound_buyer_email.eml
├── 02_email_parse_result.json
├── ...
└── 15_demo_summary.md
scripts/
├── run_email_shirt_order_demo.py # v9 runner
└── run_shirt_order_demo.py # v8 runner
tests/
├── test_email_shirt_order_demo.py # v9 tests
└── test_shirt_order_demo.py # v8 tests
Demo Versions
| Version | Entry Point | Description |
|---------|-------------|-------------|
| v9 (current) | python scripts/run_email_shirt_order_demo.py | Email-native 10-M parallel RFQ demo — starts from raw buyer .eml |
| v8 (baseline) | python scripts/run_shirt_order_demo.py | Python engine demo — structured RFQ, 3 suppliers, execution plan |
| TypeScript | npm run demo:shirt/dress/cnc | Experimental order execution engine scenarios |
Python Demo Acceptance Criteria
| Check | Status |
|-------|--------|
| pip install -e . | ✅ |
| python scripts/run_email_shirt_order_demo.py generates 15 artifacts | ✅ |
| python scripts/run_shirt_order_demo.py generates 10 artifacts | ✅ |
| pytest -q — all Python tests pass | ✅ |
| v9 starts from raw .eml buyer email (not a form) | ✅ |
| Top 3 paths derived from scoring model (not hard-coded) | ✅ |
| Buyer decision packet evidence is path-bound and supplier-correct | ✅ |
| Reply email options match 10_top3_delivery_paths.json | ✅ |
| No Chinese text in GitHub-facing files | ✅ |
TypeScript Engine (Experimental)
The TypeScript engine implements core algorithms for universal order execution simulation (CPM critical path, route enumeration, scoring).
npm install
npm run build
npm run demo:shirt # 10,000 pcs shirt multi-variable simulation
npm run demo:dress # single dress cross-language merchandising
npm run demo:cnc # CAD → CNC capability matching
npm test
Note: TypeScript engine is experimental and uses synthetic fixture dates. It is a separate demonstration from the Python demos. Use the Python demos as the primary entry point.
Scoring Formula (TypeScript engine)
totalScore =
0.25 × onTimeProbability
+ 0.15 × costEfficiency
+ 0.15 × supplierReliability
+ 0.15 × dataConfidence
+ 0.10 × commercialWindowFit
+ 0.10 × executionSimplicity
- 0.04 × criticalPathRisk
- 0.03 × qcRisk
- 0.02 × logisticsRisk
- 0.01 × approvalDelayRisk
Roadmap
- Connect to real database (PostgreSQL)
- API layer (FastAPI / Hono)
- Frontend visualization (Gantt chart + path comparison)
- Unified Python / TypeScript fixture data source
- Full Supplier Memory persistence
- Live email gateway integration (Gmail / Outlook / WeChat)
- IM channel adapters (Line, WhatsApp, Telegram)
Patent: China ZL 2023 1 1645939.9 / CN 117670482 B; Japan P7644545. Contact: mich@giraffe.technology