Unbiased Cathode: LLM-based assistant for battery material supply chain optimization

🏆 First Place Winner - MIT Energy and Climate Hack 2023

Unbiased Cathode is an LLM-powered framework that helps battery researchers answer "what-if" questions about material selection and supply chain optimization. Researchers can ask questions in plain text (e.g., "What happens if we increase the nickel content in our NMC cathode by 20%?" or "How would switching to a different lithium supplier affect our production costs?"), and the framework uses optimization models to provide quantitative answers.

This project won first place at the MIT Energy and Climate Hack in 2023, demonstrating its innovative approach to solving critical challenges in battery material supply chain optimization through the integration of large language models and mathematical optimization.

What is This Repository About?

Battery research and development involves exploring new cathode materials, anode materials, electrolytes, and other battery components. Each material choice has critical implications for battery performance, cost, and supply chain viability. As researchers develop new battery chemistries (e.g., NMC, LFP, sodium-ion, solid-state), they need to understand how material selection impacts production costs, material availability, and supply chain resilience.

Battery material supply chains are complex, involving considerations of:

• Material availability: Critical minerals (lithium, cobalt, nickel, manganese) and their geographic distribution
• Material quality: Purity requirements, particle size, and electrochemical properties
• Cost optimization: Balancing material costs with performance requirements
• Supply chain risks: Geopolitical factors, mining capacity, and supplier diversification

Unbiased Cathode addresses these challenges by providing a natural language interface to optimization models, allowing researchers to:

• Explore different material compositions and their cost implications
• Analyze supply chain scenarios and material availability constraints
• Optimize battery material selection based on quality, cost, and availability
• Answer "what-if" questions about material properties and supply chain changes

Key Features:

• Battery-material focused: Specialized for cathode materials, anode materials, electrolytes, and battery component supply chains
• Privacy-preserving: Runs optimization locally without sending proprietary data to external LLMs
• Quantitative insights: Uses Gurobi optimization to provide precise cost and feasibility analysis
• Natural language interface: Ask questions in plain English about material compositions and supply chain scenarios

How It Works

Unbiased Cathode uses a multi-agent architecture to process natural language questions and generate optimization code. The system follows an iterative workflow:

1. User submits a question in natural language about battery materials or supply chain optimization
2. Commander agent receives the question and orchestrates the workflow
3. Writer agent generates Python code to modify the optimization model based on the question
4. Safeguard agent reviews the generated code for safety and correctness
5. Commander agent processes the code and executes it to get results
6. Results are interpreted and presented back to the user in human-readable format

This process repeats iteratively until the question is fully answered or a timeout occurs, allowing for refinement and error correction.

Architecture Overview

The system uses a multi-agent architecture with three specialized agents:

┌─────────┐
│  User   │
└────┬────┘
     │ ① User Question
     ▼
┌─────────────────────────────────────────┐
│         Commander Agent                  │
│  (Orchestrates workflow and coordinates) │
└────┬───────────────────────┬────────────┘
     │                       │
     │ ② Question            │ ④ Code
     ▼                       ▼
┌──────────────┐      ┌──────────────┐
│ Writer Agent │      │Safeguard Agent│
│ (Generates   │      │ (Reviews code │
│  code/answers)│      │  for safety) │
└──────┬───────┘      └──────┬───────┘
       │                      │
       │ ③ Code, ⑦ Ans        │ ⑤ Clearance
       └──────────┬───────────┘
                  │
                  │ (Iterative loop)
                  │
┌─────────────────┴──────────────────────┐
│  Repeat until question answered       │
│  or timeout                            │
└───────────────────────────────────────┘
                  │
                  │ ⑧ Final Answer
                  ▼
            ┌─────────┐
            │  User   │
            └─────────┘

Agent Roles

• Commander Agent: The central orchestrator that receives user questions, coordinates between Writer and Safeguard agents, executes code, and formulates final answers
• Writer Agent: Specialized in generating Python code to modify Gurobi optimization models based on natural language questions
• Safeguard Agent: Reviews generated code for safety, correctness, and adherence to constraints before execution

Workflow

1. User submits a question → Commander receives it
2. Commander sends question → Writer generates code
3. Writer sends code → Commander forwards to Safeguard
4. Safeguard reviews code → Provides clearance to Commander
5. Commander executes code → Gets optimization results
6. Commander interprets results → Sends answer to User
7. Process repeats if clarification is needed

Quick Start

Installation

1. Clone the repository:

   git clone <repository-url>
   cd UnbiasedCathode

2. Install Python dependencies:

   # Option 1: Install from requirements.txt
   pip install -r requirements.txt
   
   # Option 2: Install as a package (recommended)
   pip install -e .

3. Install Gurobi Optimizer:

   • Download Gurobi Optimizer from https://www.gurobi.com/
   • Get a free academic license or purchase a commercial license
   • Install the Python package: pip install gurobipy
   • Verify installation: python -c "import gurobipy; print(gurobipy.gurobi.version())"

4. Set up environment variables:

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env and add your OpenAI API key
   # OPENAI_API_KEY=your_actual_api_key_here

5. Verify installation:

   # Run quick test
   python test_quick.py

Usage

Basic Usage

1. Prepare your optimization model:

   • Create a Gurobi optimization model in Python (see benchmark/application/materials.py for an example)
   • The model should define variables, constraints, and an objective function

2. Load the model and create an agent:

   from optiguide.optiguide import OptiGuideAgent
   from flaml.autogen.agentchat import UserProxyAgent
   import os
   from dotenv import load_dotenv
   
   load_dotenv()
   
   # Load your optimization model code
   with open("benchmark/application/materials.py", "r") as f:
       source_code = f.read()
   
   # Create the OptiGuide agent
   agent = OptiGuideAgent(
       name="Battery Material Agent",
       source_code=source_code,
       llm_config={
           "config_list": [{
               "model": "gpt-3.5-turbo",
               "api_key": os.getenv("OPENAI_API_KEY")
           }]
       }
   )
   
   # Create a user proxy
   user = UserProxyAgent("user", max_consecutive_auto_reply=0, 
                        human_input_mode="NEVER", code_execution_config=False)
   
   # Ask a question
   user.initiate_chat(agent, message="What happens if we increase NMC622 usage by 20%?")

3. Use the Jupyter notebook:

   jupyter notebook notebook/optiguide_example.ipynb

   Follow the notebook cells to interact with the system interactively.

Example Questions

• "What happens if we increase the nickel content in NMC811 by 15%?"
• "How would the production cost change if we switch from LCO to LFP?"
• "What if the quality threshold increases by 10%?"
• "How does reducing cobalt usage affect the optimal material composition?"

Testing

Quick test:

python test_quick.py

Full test suite:

python test_materials.py

Test the notebook:

jupyter notebook notebook/optiguide_example.ipynb

See TESTING.md and HOW_TO_TEST.md for detailed testing instructions.

Project Structure

UnbiasedCathode/
├── optiguide/              # Core package
│   ├── optiguide.py       # Main OptiGuideAgent implementation
│   └── version.py         # Version information
├── benchmark/             # Example optimization models
│   ├── application/       # Optimization model files
│   │   └── materials.py  # Battery materials optimization example
│   └── QAs/              # Question-answer benchmarks
├── notebook/              # Jupyter notebooks
│   └── optiguide_example.ipynb  # Interactive example
├── test_quick.py          # Quick test script
├── test_materials.py     # Full test suite
├── requirements.txt       # Python dependencies
├── setup.py              # Package setup
└── README.md             # This file

Requirements

• Python 3.8+
• Gurobi Optimizer (with valid license)
• OpenAI API key (for LLM functionality)
• See requirements.txt for Python package dependencies

Documentation

• TESTING.md - Comprehensive testing guide
• HOW_TO_TEST.md - Step-by-step testing instructions

License

MIT License - See LICENSE file for details

Citation

If you use this work, please cite:

@article{optiguide2023,
  title={OptiGuide: LLM-based assistant for optimization modeling},
  author={Li, Beibin and others},
  journal={arXiv preprint arXiv:2307.03875},
  year={2023}
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.