Battery ERP — Material, cell, pack, and supply-chain management with real-time
commodity pricing and Fabric Lakehouse analytics.
Covers the full battery value chain: lithium, cobalt, nickel, manganese, graphite
through cell chemistries (NMC-811, NCA, LFP, LMO) to battery packs with BOM costing,
supplier scoring, inventory management, and what-if cost scenarios.
mcp-name: io.github.icohangar-ops/battery-erp
What this is
Battery ERP manages the complete battery value chain — from raw material sourcing
through cell manufacturing to pack assembly. Every cost is traceable to a specific
material, supplier, and price point.
| Layer | Role |
|---|
| Data Models | RawMaterial, CellChemistry, BatteryCell, BatteryPack, BOMItem, Supplier, InventoryRecord, PurchaseOrder, ManufacturingBatch |
| Business Rules | BOM cost rollups, inventory status management, supplier scoring (composite A-D grade), manufacturing yield tracking, price trend analysis, what-if cost scenarios |
| Pricing Engine | Default material price table (20+ materials), AlphaVantage integration for live commodity prices, FRED macro overlay |
| Analytics | Inventory health reports, supply chain reports, manufacturing yield reports, chemistry cost comparison dashboards |
| Fabric Lakehouse | 11 Delta tables for persistent storage and SQL analytics |
Quick start
python3 -m pip install 'battery-erp[mcp]'
python3 -m pip install 'battery-erp[api]'
git clone https://github.com/icohangar-ops/battery-erp.git
cd battery-erp
python3 -m pip install -e '.[dev]'
PYTHONPATH=src python3 -m pytest tests/ -v
python3 -c "
from battery_erp.pricing import calculate_cell_cost_summary, get_material_price_table
prices = get_material_price_table()
for chem in ['NMC-811', 'NMC-622', 'NCA', 'LFP', 'LMO']:
r = calculate_cell_cost_summary(chem, 50.0, prices)
print(f'{chem}: \${r[\"cost_per_kwh\"]:.1f}/kWh (BOM: \${r[\"bom_cost_usd\"]:.2f})')
"
Architecture
┌──────────────────────────────────────┐
│ Raw Materials (20+ tracked) │
│ Lithium · Cobalt · Nickel · Mn · Gr │
└──────────────┬───────────────────────┘
│ BOM
┌──────────────▼───────────────────────┐
│ Cell Chemistries │
│ NMC-811 · NMC-622 · NCA · LFP · LMO │
└──────────────┬───────────────────────┘
│ cells + components
┌──────────────▼───────────────────────┐
│ Battery Packs │
│ EV · ESS · Consumer · Industrial │
└──────────────────────────────────────┘
Side modules:
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Supplier Scoring │ │ Inventory Mgmt │ │ Cost Scenarios │
│ Composite 0-100 │ │ Reorder logic │ │ What-if analysis │
│ A/B/C/D grades │ │ Status tracking │ │ Price shock model │
└─────────────────┘ └──────────────────┘ └──────────────────┘
Core modules
battery_erp.core.models
All domain dataclasses:
RawMaterial — material catalog with pricing, HS codes, hazardsCellChemistry — NMC-111/622/811, NCA, LFP, LMO with energy density and cycle lifeBatteryCell — cell specs (capacity, voltage, form factor, weight)BatteryPack — pack assembly (cells + BMS + thermal)BOMItem — bill of materials line item with waste factorSupplier — supplier catalog with quality rating, lead time, certificationsInventoryRecord — warehouse positions with reorder logicPurchaseOrder — PO lifecycle trackingManufacturingBatch — production batch yield trackingPriceHistory — commodity price time series
battery_erp.core.rules
Deterministic business rules:
rollup_bom_cost() — total BOM cost with material breakdown and waste costcalculate_cell_bom() — generate representative BOM for any chemistrycalculate_pack_bom() — pack-level BOM (cells + casing + BMS + cooling)update_inventory_status() — recalculate in_stock/low/out_of_stockcheck_reorder_suggestions() — generate PO suggestionscalculate_batch_metrics() — aggregate manufacturing yieldanalyze_price_history() — price trend analysis with volatilityestimate_cell_cost_impact() — what-if cost scenario modelingcalculate_pack_metrics() — pack energy density and efficiency
battery_erp.supply_chain
Supply chain management:
score_supplier() — composite score (quality 35%, OTD 35%, lead time 20%, certs 10%)rank_suppliers() — rank by score, filter by materialcreate_purchase_order() — PO creation from supplier dataanalyze_po_pipeline() — PO pipeline analysis (overdue detection, lead time tracking)suggest_dual_sourcing() — dual-sourcing strategy recommendation
battery_erp.pricing
Commodity pricing:
get_material_price_table() — default prices for 20+ battery materialscalculate_cell_cost_summary() — quick cost estimate per chemistryupdate_prices_from_alpha_vantage() — live commodity price fetchupdate_prices_from_fred() — macro economic indicators
battery_erp.analytics
Reporting:
generate_inventory_report() — full inventory health dashboardgenerate_supply_chain_report() — supplier + PO pipeline reportgenerate_manufacturing_report() — yield metricsgenerate_pricing_report() — chemistry cost comparison + price trends
Chemistry cost comparison (default prices, 50Ah cell)
| Chemistry | BOM Cost | $/kWh | Cathode % | Key feature |
|---|
| LFP | Lowest | ~$50-55 | ~35% | No Co/Ni, ultra-safe, 4000+ cycles |
| LMO | Low | ~$55-60 | ~40% | Low cost, power tools |
| NMC-111 | Medium | ~$70-80 | ~50% | Balanced, legacy |
| NMC-622 | Medium | ~$75-85 | ~48% | Good energy-cost balance |
| NMC-811 | Higher | ~$80-90 | ~52% | High energy, EV dominant |
| NCA | Highest | ~$85-95 | ~55% | Tesla flagship, 270 Wh/kg |
Microsoft Fabric Integration
Fabric Notebooks
| Notebook | Purpose |
|---|
fabric_setup_lakehouse.py | Create all 11 Delta tables with seed data |
fabric_cost_dashboard.py | Full cost analytics dashboard (chemistry comparison, pack costing, inventory, suppliers, price trends, scenarios) |
Delta Table Schema
| Table | Key Columns |
|---|
raw_materials | material_id, name, category, unit_price_usd, price_source, hs_code |
cell_chemistries | chemistry_id, name, cathode_type, energy_density_wh_per_kg, cycle_life |
battery_cells | cell_id, sku, chemistry, form_factor, nominal_capacity_ah, energy_wh, weight_kg |
battery_packs | pack_id, sku, cell_sku, total_cells, nominal_capacity_kwh, pack_weight_kg |
bill_of_materials | bom_id, parent_sku, material_name, quantity_per_unit, unit_cost_usd, waste_factor_pct |
suppliers | supplier_id, name, country, materials_supplied, quality_rating, lead_time_days |
inventory | record_id, sku, material_name, quantity_on_hand, quantity_reserved, reorder_point |
purchase_orders | po_id, po_number, supplier_name, quantity, total_usd, status, expected_delivery |
price_history | material_name, price_usd, as_of, source |
manufacturing_batches | batch_id, product_sku, chemistry, quantity_produced, quantity_pass, yield_pct |
cost_scenarios | scenario_id, scenario_name, material_name, current_price_usd, scenario_price_usd, pct_change |
Fabric Quick Start
- Run
fabric_setup_lakehouse.py to create all 11 Delta tables
- Run
fabric_cost_dashboard.py for the full analytics dashboard
- Dashboard covers: chemistry cost comparison, pack-level costing, inventory health, supplier scorecard, price trends, manufacturing yield, cost scenarios
Inventory adapters (REST + MCP)
Battery ERP is a domain library, not a hosted ERP. For SMS / text-line and
agent workflows, a shared InventoryService sits under both a thin REST API and
an MCP server. Full detail: docs/INTEGRATION.md.
SMS / ClickSend Cursor / Claude (stdio MCP)
│ │
▼ ▼
REST API (port 8088) battery_erp.mcp
└──────────┬──────────────┘
▼
InventoryService
▼
InMemoryInventoryStore (demo)
▼
Human bin confirmation
Do not call MCP from a browser. Keep REST and MCP in separate terminals.
Install (macOS / zsh)
Use python3. Quote pip extras so zsh does not glob them:
cd ~/Desktop/icohangar-repos/battery-erp
python3 -m pip install -e '.[dev]'
Terminal A — REST (text-line backend)
cd ~/Desktop/icohangar-repos/battery-erp
export BATTERY_ERP_CONFIRM_TOKEN=dev-secret
export BATTERY_ERP_AUDIT_LOG=/tmp/battery-erp-audit.jsonl
PYTHONPATH=src python3 -m battery_erp.api
curl -s http://127.0.0.1:8088/health
curl -s http://127.0.0.1:8088/inventory/lookup/lithium
Terminal B — MCP (agents / Cursor only)
Leave Terminal A running. In a new terminal:
cd ~/Desktop/icohangar-repos/battery-erp
export BATTERY_ERP_CONFIRM_TOKEN=dev-secret
PYTHONPATH=src python3 -m battery_erp.mcp
That process stays quiet on stdio — normal for MCP hosts. Do not paste this into the API terminal.
Cursor MCP config
Add to ~/.cursor/mcp.json (absolute paths; python3 not python):
{
"mcpServers": {
"battery-erp": {
"command": "python3",
"args": ["-m", "battery_erp.mcp"],
"env": {
"PYTHONPATH": "/Users/YOU/Desktop/icohangar-repos/battery-erp/src",
"BATTERY_ERP_CONFIRM_TOKEN": "replace-me",
"BATTERY_ERP_AUDIT_LOG": "/tmp/battery-erp-audit.jsonl"
}
}
}
}
Then reload MCP servers in Cursor. Tools exposed: lookup_inventory,
get_inventory_status, get_inventory_record, list_inventory,
create_bin_check_request, record_bin_confirmation.
| Surface | Entry | Shared layer |
|---|
| REST | GET /inventory/lookup/{part}, bin-check / bin-confirm | battery_erp.services.InventoryService |
| MCP | tools above (mcp SDK 2.x MCPServer) | same |
Mutating bin confirmation requires BATTERY_ERP_CONFIRM_TOKEN and optionally
writes JSONL audit to BATTERY_ERP_AUDIT_LOG.
Directory / registry packaging: see PUBLISH.md (glama.json,
Dockerfile, server.json).
Tests
PYTHONPATH=src python3 -m pytest tests/ -v
Use cases
- Cell manufacturers — BOM cost tracking across chemistries, yield optimization
- Pack integrators — pack-level cost estimation, supplier selection
- Procurement — supplier scoring, dual-sourcing, PO pipeline management
- Finance — commodity price risk, what-if scenarios, inventory valuation
- C-suite — dashboard showing $/kWh trends, supply chain resilience, cost reduction opportunities
License
MIT. See LICENSE.
CHP Governance
This repository is hardened with the Consensus Hardening Protocol (CHP), Cubiczan's decision-governance layer for multi-agent AI systems.
Protocol Layers
- R0 Gate: All decisions must pass Solvable, Scoped, Valid, Worth_it checks
- Foundation Disclosure: 1-3 weakest assumptions, 1-2 invalidation conditions, 1 key vulnerability
- Adversarial Layer: Mandatory devil's advocate at Phase 0 and Round 3
- State Machine: EXPLORING → PROVISIONAL → PROVISIONAL_LOCK → LOCKED
- Third-Party Validation: Independent CONFIRM/REJECT before lock
Domain Configuration
- Category: Mining / Supply Chain
- Foundation Threshold: 75
- CFO Accuracy Guard: Disabled
Compliance Artifacts
| File | Purpose |
|---|
.chp/STATE_MACHINE.md | Decision state transitions |
.chp/R0_CONFIG.yaml | Domain-calibrated thresholds |
.chp/ADVERSARIAL_PROMPTS.md | Standardized challenge templates |
.chp/CHP_COMPLIANCE.md | Compliance tracking & audit trail |
CHP Version
cognitive-mesh-orchestrator 0.1.0 | Protocol Docs
Demo
Handheld — Parts Bin Text Line
Mobile capture from the live lead page
(parts-bin-text-line--icohangar.replit.app).
SMS → text-line → Battery ERP inventory check → human bin confirm.
