Project Apache-2.0
in development 20%
Supply Chain Operations Planning & Execution in Commodities (SCOPEC)
How do you plan and execute supply chain operations for commodities?
SCOPEC is a supply chain operations planning and execution tool for commodities: one planning kernel runs S&OP and S&OE on the same data model, commodity families live as data profiles, and agents act on exceptions under an autonomy ladder they earn.
Commodity planning lives between two kinds of software
Planning software is built around discrete products and factories. Trading software runs contracts, positions and the hedge book, and stops where the physical flow begins. A commodity operation sits between the two: lots instead of units, origin, grade and certification as attributes that decide what a lot can become, crop years and shutdown schedules as the calendar, yields and co-products where a bill of materials would be.
So the monthly plan usually lives in one spreadsheet and the weekly execution in another, and the two meet in a meeting. By then the vessel has sailed.
One kernel, two horizons, commodity families as data
SCOPEC runs S&OP and S&OE on one planning kernel and one data model. The monthly plan sets volumes by family; the weekly and daily execution runs orders, lots and shipments inside the time fences. When actuals drift beyond tolerance, the gap opens an exception with an owner and a proposed amendment to the published plan - so the plan hears about a deviation on the quay before the next review meeting does.
Commodity knowledge lives in a domain profile, not in code: attributes, quality specs, units, calendar, KPI and rule packs, compliance. The kernel never branches on commodity. Soft commodities are the first profile; hard commodities follow, built over the same kernel and allowed to break it where the abstraction is wrong.
A network twin runs every scenario forward with stochastic inputs and returns distributions instead of points, including the probability that the published plan holds. The solvers say what to do; the twin says how robust it is.
On top of the exception engine sits an agentic execution layer: domain agents that run the lab's OODAA loop on each exception and act through the same typed kernel API a planner uses. Every action lands in an action ledger, explained in planning language and reversible, and autonomy is earned on that evidence. Model-written text carries EU AI Act Article 50 marking by construction, recorded in COMPLIANCE.md.
How SCOPEC works
Drag sideways to read the whole schematic →
General notes
- 1Inputs arrive as commodity objects: contracts and call-offs, intake and production plans, lots with origin, grade and certification, positions in transit and afloat, and the disruptions that hit them.
- 2A domain profile is data, never code: attributes, quality specs, units, calendar, KPI and rule packs, compliance. Soft commodities come first; hard commodities, for processors, later over the same kernel.
- 3One kernel, two horizons. S&OP plans volumes by family each month, 3 to 24 months out; S&OE runs orders, lots and shipments each week and day, up to 8 weeks out. Time fences separate them.
- 4Gap to plan is the hinge: when actuals from operations breach tolerance, S&OE opens an exception with an owner and proposes an amendment to the published plan.
- 5Every constant is a parameter with scope, dates and provenance, snapshotted into each scenario. Thresholds and rules are data too, so two plan versions diff parameter by parameter.
- 6Predictions arrive through a provider contract SCOPEC owns: each slot binds to the kernel's deterministic tier, to Auspex as an optional external provider, or to an ensemble, and the evaluator sets the default binding. Every number records which binding produced it.
- 7The action ledger records every planner, model and agent action, explained in planning language. The glass box lets you review it, trace a number back to its inputs and reverse it with a reason.
- 8The CTRM stays the system of record: contracts and positions are imported through an adapter, and hedging, mark-to-market and the trading book enter SCOPEC as parameters and scenarios.
- 9The network twin runs a scenario forward with stochastic inputs from the prediction slots and returns distributions - service, days of cover, demurrage, margin and the probability the plan holds. The same simulation core generates the test data.
- 10Agentic execution runs the OODAA loop on each exception: observe, orient with kernel context, decide among solver options, pass the gate, act through the kernel API or MCP, adjust. Numbers come from solvers and providers, never from the model; autonomy climbs a ladder on ledger evidence, with a kill switch per agent.
Legend
- Signal or action
- Measurement, external provider
- System boundary
- Control loop: actuals, gap to plan, agentic execution, glass box
- Approval gate
- Instrument: A actuals, G gate, EV evals
- Physical operation
Built for physical commodity flows, not for SKUs
An item is a commodity by origin, grade, certification and crop year. Recipes carry yields and co-products, and positions include stock in transit and afloat.
Thresholds, costs, service levels and rules carry scope, dates and provenance, and every scenario keeps its own snapshot. Diff any two plan versions.
Every planner, model and agent action is recorded in planning language. Click a number, see the chain from data to model to parameter. Reverse any change with a reason.
The kernel ships deterministic models. Probabilistic forecasting is an optional binding to Auspex, and every output records which model and parameters produced it.
Where SCOPEC is heading
Lots with genealogy, recipes with yields and co-products, contracts and positions, the parameter and rules store, the scenario store, the action ledger, and the simulation core as a synthetic company generator.
Crop calendars, intake forecasts, quality degradation in storage, certification and EUDR traceability, blend optimisation under quality constraints.
Demand, inventory, MRP with yields and co-products, capacity as a linear programme; contract allocation, available-to-promise, a shortage control tower, gap to plan; the twin testing every plan beside the solvers.
Domain agents on the exception engine - shortage, follow-up, quality, replenishment, amendments - running the OODAA loop under an earned autonomy ladder, with the kernel tools also exposed over MCP.
Metals and minerals for processors: assays, wet and dry tonnes, payable metal, pricing formulas and settlement, shutdown calendars. Built as data over the same kernel, to prove the abstraction holds.
Out of scope by design: energy, and the trading book. Code lands in the repository at v0.1.