S&OP Planning Suite

Multi-agent Sales & Operations Planning system for Codex and Hermes Agent.

Architecture

sop-planning-suite/
├── .codex-plugin/plugin.json    # Codex plugin manifest
├── .mcp.json                     # MCP server configuration
├── .app.json                     # Desktop app UI definition
├── skills/                       # 4 Agent skills
│   ├── ingest-sop-library/       # OCR and knowledge ingestion
│   ├── solve-sop-case/           # Multi-agent S&OP pipeline
│   ├── audit-sop-plan/           # Citation and compliance audit
│   └── evaluate-sop-agents/      # Benchmark evaluation
├── agents/
│   └── agent_team.py             # 9 specialist agent definitions
├── scripts/                      # Executable pipelines
│   ├── ingest-document           # OCR ingestion
│   ├── validate-ocr              # Quality validation
│   ├── build-index               # Knowledge index builder
│   └── run-evaluations           # Benchmark runner
├── mcp-server/
│   └── serve.py                  # MCP knowledge server
├── cases/                        # 10 benchmark cases
│   ├── bench-001.json ... bench-010.json
├── assets/
│   ├── generate_report.py        # DOCX report generator
│   ├── report-template.docx      # Executive report template
│   └── scenario-template.xlsx    # Scenario workbook template
└── knowledge-index/              # Built knowledge index
    ├── metadata.db               # SQLite metadata
    ├── vectors/                  # Embedding vectors
    └── books/                    # Per-book records

Quick Start

1. Install dependencies

pip install pytesseract pdf2image Pillow python-docx openpyxl pulp numpy

2. Ingest an S&OP book

python scripts/ingest-document \
  --source input/your_book.pdf \
  --book-id book-01 \
  --title "Supply Chain Excellence" \
  --license internal-use

3. Build the search index

python scripts/build-index \
  --knowledge-dir knowledge-index/ \
  --db-path knowledge-index/metadata.db \
  --vector-path knowledge-index/vectors/

4. Solve an S&OP case

# Via the solve-sop-case skill (multi-agent pipeline)
# or programmatically:
python -c "
from agents.agent_team import SOPPipeline
import json

with open('cases/bench-001.json') as f:
    case = json.load(f)

pipeline = SOPPipeline(case)
result = pipeline.run()
print(json.dumps(result, indent=2))
"

5. Run benchmarks

python scripts/run-evaluations --cases-dir cases/

6. Generate executive report

python assets/generate_report.py \
  --pipeline-output output.json \
  --output report.docx

Agent Team

Agent	Role	Triggers On
S&OP Orchestrator	Decompose, dispatch, reconcile, finalize	Always active
Demand Planner	Forecasting, seasonality, promotions, bias	Demand data
Supply Planner	Capacity, constraints, suppliers, scheduling	Supply data
Inventory Planner	Safety stock, service levels, working capital	Inventory data
Finance Partner	Revenue, margin, cash, scenario economics	Financial data
Market Researcher	External evidence, competitors, macro factors	Always active
Scenario Challenger	Optimistic/expected/downside, assumption stress-test	Before final plan
Verification Agent	Independent recalculation of material results	After all specialists
Audit Agent	Citation verification, data lineage, compliance	After verification

Benchmark Cases

10 cases spanning easy to hard difficulty:

ID	Title	Difficulty	Tests
bench-001	Single-Product Baseline	easy	Basic forecasting, capacity check
bench-002	Multi-Product Single Stage	easy	Product mix, capacity allocation
bench-003	Seasonal Demand	easy	Seasonality, pre-build logic
bench-004	Promotional Lift	easy	Promo estimation, inventory buildup
bench-005	Multi-Stage Production	easy	WIP flow, bottleneck propagation
bench-006	Supply Disruption	medium	Disruption planning, contingency
bench-007	Working Capital Trade-off	medium	Service level vs inventory investment
bench-008	Labor-Constrained Planning	medium	Overtime economics, hiring trade-offs
bench-009	Full LP Optimization	hard	4-stage LP, multi-machine, labor
bench-010	Uncertainty Planning	hard	3-scenario, dual sourcing, resilience

Scoring Dimensions

Dimension	Weight	What It Measures
Numerical Accuracy	35%	Calculations vs ground truth
Citation Accuracy	20%	Source identification and application
Plan Usefulness	20%	Completeness, clarity, actionability
Cost Efficiency	10%	Tokens/API cost per case
Latency	10%	Wall-clock time
Audit Pass Rate	5%	Findings per plan

MCP Integration

The knowledge index is served via MCP protocol:

{
  "mcpServers": {
    "sop-knowledge": {
      "command": "python",
      "args": ["mcp-server/serve.py"],
      "env": {
        "INDEX_PATH": "./knowledge-index"
      }
    }
  }
}

Tools exposed: search_knowledge, get_citation, list_sources, verify_citation.

License

MIT — workflows, schemas, and evaluation cases are original work.
Book contents must be legally owned and stored in a private, access-controlled index.
See the copyright section in skills/ingest-sop-library/SKILL.md.

S&OP Planning Suite — Multi-Agent