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

server.ts

# From PyPI — https://pypi.org/project/battery-erp/
python3 -m pip install 'battery-erp[mcp]'   # MCP tools
python3 -m pip install 'battery-erp[api]'   # REST adapter

# From source
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

# Domain modules
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

Code

                    ┌──────────────────────────────────────┐
                    │  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, hazards
CellChemistry — NMC-111/622/811, NCA, LFP, LMO with energy density and cycle life
BatteryCell — cell specs (capacity, voltage, form factor, weight)
BatteryPack — pack assembly (cells + BMS + thermal)
BOMItem — bill of materials line item with waste factor
Supplier — supplier catalog with quality rating, lead time, certifications
InventoryRecord — warehouse positions with reorder logic
PurchaseOrder — PO lifecycle tracking
ManufacturingBatch — production batch yield tracking
PriceHistory — commodity price time series

`battery_erp.core.rules`

Deterministic business rules:

rollup_bom_cost() — total BOM cost with material breakdown and waste cost
calculate_cell_bom() — generate representative BOM for any chemistry
calculate_pack_bom() — pack-level BOM (cells + casing + BMS + cooling)
update_inventory_status() — recalculate in_stock/low/out_of_stock
check_reorder_suggestions() — generate PO suggestions
calculate_batch_metrics() — aggregate manufacturing yield
analyze_price_history() — price trend analysis with volatility
estimate_cell_cost_impact() — what-if cost scenario modeling
calculate_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 material
create_purchase_order() — PO creation from supplier data
analyze_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 materials
calculate_cell_cost_summary() — quick cost estimate per chemistry
update_prices_from_alpha_vantage() — live commodity price fetch
update_prices_from_fred() — macro economic indicators

`battery_erp.analytics`

Reporting:

generate_inventory_report() — full inventory health dashboard
generate_supply_chain_report() — supplier + PO pipeline report
generate_manufacturing_report() — yield metrics
generate_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.

Code

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:

bash

cd ~/Desktop/icohangar-repos/battery-erp
python3 -m pip install -e '.[dev]'   # api + mcp + pytest

Terminal A — REST (text-line backend)

server.ts

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
# Uvicorn → http://127.0.0.1:8088

Terminal

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:

server.ts

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):

config.json

{
  "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).

Directory	Link
PyPI	https://pypi.org/project/battery-erp/
MCP Registry	`io.github.icohangar-ops/battery-erp`
Glama	https://glama.ai/mcp/servers/@icohangar-ops/battery-erp

Tests

bash

PYTHONPATH=src python3 -m pytest tests/ -v
# Domain tests + inventory service / REST / MCP scaffold

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.

Parts Bin Text Line handheld demo