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