battery-erp

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

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

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]'   # 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.

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

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.