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.

Related MCP server: Factory Insight MCP Server

Quick start

# 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

                    ┌──────────────────────────────────────┐
                    │  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)

Microsoft Fabric Integration

Fabric Notebooks

Delta Table Schema

Fabric Quick Start

1. Run fabric_setup_lakehouse.py to create all 11 Delta tables

2. Run fabric_cost_dashboard.py for the full analytics dashboard

3. 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]'   # api + mcp + pytest

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

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.

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). After merge to main, claim on Glama as @icohangar-ops/battery-erp.

Tests

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

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.