🔋 BatteryForge AI

Multi-Agent Battery Intelligence Platform powered by Google Gemini 3 & ADK

An advanced agentic AI system for battery manufacturing defect detection, physics-based optimization, and fleet management. Built with Google's Agent Development Kit (ADK) for seamless multi-agent orchestration.

📋 Table of Contents

🎯 Overview
✨ Key Features
🏗️ Architecture
🚀 Quick Start - Start Here!
- 🐳 Docker Deployment (Recommended)
- 💻 Manual Setup
📖 Usage Guide
🛠️ Technology Stack
📊 API Endpoints
🚀 Deployment
🤝 Contributing

🎯 Overview

BatteryForge AI revolutionizes battery quality control and fleet management through 5 specialized AI agents working in harmony:

Agent	Role	Capabilities
🎖️ BatteryForge Commander	Strategic Orchestrator	Routes requests, coordinates workflows, ensures safety protocols
👁️ Defect Analysis Agent	Visual Inspection Expert	Real-time defect detection, PCB/BMS inspection, thermal runaway monitoring
⚡ Charging Optimization Agent	Electrochemistry Specialist	EIS analysis, PyBaMM physics simulation, capacity fade prediction
🚀 Fleet Commander Agent	Strategic Planner	Fleet monitoring, scenario simulation, risk assessment
🛡️ Safety Guardian Agent	Emergency Response	HITL emergency shutdown, thermal event detection, safety protocols
🔧 Predictive Maintenance Agent	Lifecycle Expert	RUL prediction, aging analysis, maintenance scheduling

✨ Key Features

🤖 Multi-Agent Orchestration (ADK)

Autonomous delegation - Commander intelligently routes tasks to specialist agents
Real-time trace visualization - See agent transfers and tool calls in action
Context & Memory - Agents maintain long-term conversation history, remembering previous queries, results, and user preferences (e.g., "Show me the graph for that pack")
Marathon workflows - Long-running tasks (pack audits, continuous monitoring)

👁️ Visual Intelligence

Real-time analysis - Webcam, screen share, or YouTube video defect detection
"Detect-Locate-Describe" methodology for precise classification
Multi-modal support - Images, videos, live streams, thermal cameras
PCB inspection - Open circuits, shorts, solder mask defects via Gemini Vision

⚡ Physics-Based Simulation

PyBaMM integration - Doyle-Fuller-Newman (DFN) physics modeling
Universal CSV parser - AI-powered semantic column mapping for any format
Interactive visualization - Multi-plot Recharts with voltage, current, temperature
EIS analysis - Layer-by-layer impedance diagnosis (Ohmic, Kinetics, Diffusion)

🚀 Fleet Management

Unified Dashboard - Real-time tracking of vehicles, drivers, and charging stations
Scenario Simulation - Heat waves, cold snaps, fast charging stress tests
Strategic Insights - Thermal spread analytics, risk assessment, tactical commands
Smart Settings - Configurable thresholds, notifications, and units via new Settings Panel
AI Command Center - "Add Driver", "Assign Vehicle" via natural language commands

🏭 PCB Manufacturing

Gerber file analysis - Automated CAM validation
Adaptive process control - Etching optimization, lamination scaling
Quality assurance - Automated compliance certificate generation
Flight bar optimization - Plating uniformity prediction

🧠 RAG Knowledge Assistant

ChromaDB vector store - Semantic search across technical documentation
Gemini embeddings - Context-aware retrieval
Chat integration - Ask questions with automatic knowledge injection
PDF ingestion - Parse battery safety standards, extensive manuals, and supplier datasheets
Technical Q&A - "What is the max charging current for the Samsung 30Q based on the datasheet?"

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                  React Frontend (Vite)                  │
│  ┌──────────┬──────────┬──────────┬─────────┬────────┐ │
│  │  Visual  │ Charging │  Fleet   │   PCB   │  Chat  │ │
│  │   Scout  │ Analysis │  Monitor │  Mfg.   │   AI   │ │
│  └──────────┴──────────┴──────────┴─────────┴────────┘ │
└──────────────────────┬──────────────────────────────────┘
                       │ FastAPI REST + WebSocket
┌──────────────────────┴──────────────────────────────────┐
│              Python Backend (FastAPI)                    │
│  ┌────────────────────────────────────────────────────┐ │
│  │     ADK Multi-Agent System (Runner)                │ │
│  │  ┌──────────┬──────────┬──────────┬─────────────┐ │ │
│  │  │Commander │  Defect  │ Charging │   Fleet     │ │ │
│  │  │  Agent   │  Agent   │  Agent   │   Agent     │ │ │
│  │  └──────────┴──────────┴──────────┴─────────────┘ │ │
│  │  ┌──────────┬──────────────────────────────────┐  │ │
│  │  │  Safety  │  Predictive Maintenance Agent   │  │ │
│  │  └──────────┴──────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────┐ │
│  │              20+ Specialized Tools                 │ │
│  │  Vision • PyBaMM • EIS • Fleet • Reporting • RAG  │ │
│  └────────────────────────────────────────────────────┘ │
│  ┌──────────┬──────────┬─────────────────────────────┐ │
│  │  SQLite  │ ChromaDB │  PyBaMM Physics Engine      │ │
│  └──────────┴──────────┴─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

🚀 Quick Start

🐳 Docker Deployment (Recommended)

The fastest way to run BatteryForge AI - containerized deployment with zero manual configuration.

Prerequisites

Docker Desktop (includes Docker Compose)
Gemini API Key (free tier available)

One-Command Setup

# 1. Clone and navigate
git clone <your-repo-url>
cd BatteryForgeAI

# 2. Configure API key
cp .env.example .env
nano .env  # Add: GEMINI_API_KEY=your_actual_key_here

# 3. Launch (builds and starts all services)
docker compose up --build -d

Access Your Application

Service	URL	Description
🌐 Frontend	http://localhost	Main web interface
🔧 Backend API	http://localhost:8000	FastAPI server
📚 API Docs	http://localhost:8000/docs	Interactive Swagger UI
❤️ Health Check	http://localhost:8000/health	Service status

Common Commands

# View real-time logs
docker compose logs -f

# View specific service logs
docker compose logs -f backend
docker compose logs -f frontend

# Restart services
docker compose restart

# Stop services (keeps data)
docker compose down

# Stop and REMOVE all data (⚠️ destructive)
docker compose down -v

# Rebuild after code changes
docker compose up --build

📖 For advanced Docker usage, troubleshooting, and production deployment, see DOCKER.md

💻 Manual Setup (Development)

For local development without Docker:

Prerequisites

Python 3.11+ (3.13 recommended)
Node.js 18+
Gemini API Key (Get one here)

Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate (Windows)
.\venv\Scripts\activate

# Activate (macOS/Linux)
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# Run server
uvicorn main:app --reload

Backend will be available at http://localhost:8000

Frontend Setup

cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

Frontend will be available at http://localhost:5173

📖 Usage Guide

1. Visual Defect Detection

Upload Mode:

Navigate to Visual Intelligence tab
Upload battery/PCB image or video
Click Analyze to detect defects
Review classification, severity, and mitigation

Live Scout Mode:

Go to Visual Intelligence → Live Scout
Select input source (Webcam, Upload, YouTube URL)
Click Start Scout AI for real-time analysis
Monitor live defect logs with timestamps

2. Charging Analysis

Standard Workflow:

Go to Charging Analysis tab
Upload CSV file (any format - Arbin, BioLogic, Tesla, etc.)
System auto-detects columns using AI semantic mapping
View interactive plots with voltage, current, temperature
Get PyBaMM physics comparison and safety score

EIS Analysis:

Upload EIS data (frequency, real/imaginary impedance)
View Nyquist plot with layer-by-layer diagnosis
Get ohmic, kinetics, and diffusion health assessment

3. Fleet Monitoring

Navigate to Fleet Monitor
View real-time status of Vehicles, Drivers, and Charging Stations at a glance
Use the Map View (powered by Leaflet) to track assets geographically
Run scenario simulations (heat wave, cold snap) via the AI Agent
Manage fleet configuration via the new Settings tab

4. AI Chat Assistant

Open Chat Interface
Ask questions or give commands:
- "Analyze this battery image for defects"
- "Simulate a heat wave on the fleet"
- "What is lithium plating?"
- "According to the uploaded LG datasheet, what is the cutoff voltage?"
- "Run a full pack audit"
Watch agent trace to see specialist collaboration
Navigate automatically with [VIEW: VISUAL] commands
Contextual Memory - The agent remembers previous context, allowing for natural follow-up questions (e.g., "Add a driver for that vehicle")

5. PCB Manufacturing

Go to PCB Manufacturing tab
Upload Gerber file for CAM validation
Get adaptive etching control recommendations
Run lamination scaling predictions
Generate compliance certificates

🛠️ Technology Stack

AI & Machine Learning

Google Gemini 3 Flash Preview - Multi-agent orchestration & tool calling
Google ADK - Agent Development Kit for workflow coordination
Gemini Vision - Multimodal defect detection
ChromaDB - Vector database for RAG
Gemini Embeddings - Semantic search

Physics & Simulation

PyBaMM - Python Battery Mathematical Modeling (DFN solver)
NumPy - Numerical computing
Pandas - Data analysis
SciPy - Scientific computing

Backend

FastAPI - High-performance API framework
Uvicorn - ASGI server
Pydantic - Data validation
SQLite - Analysis history
AsyncIO - Asynchronous programming

Frontend

React 18 - UI framework
Vite - Lightning-fast build tool
Recharts - Scientific data visualization
Leaflet (Vanilla) - Lightweight, robust mapping without React wrappers
Framer Motion - Smooth animations
React Player - Video playback
Tailwind CSS - Utility-first styling

Deployment & Infrastructure

Docker - Containerization for consistent deployment
Docker Compose - Multi-container orchestration
Nginx - Production web server and reverse proxy
Multi-stage builds - Optimized container images
Persistent volumes - Data preservation across restarts

📊 API Endpoints

Agent System

GET /api/agent/status - Check ADK agent availability
POST /api/chat/send - Multi-agent chat interface
POST /api/agent/workflow - Trigger marathon workflows
GET /api/agent/session/{id} - Get session state
WS /api/ws/agent - Real-time agent streaming

Analysis

POST /api/analyze/defect - Visual defect detection
POST /api/analyze/charging - Charging curve analysis
POST /api/analyze/log - Fault log parsing
POST /api/analyze/aging - Battery aging prediction
POST /api/analyze/comparison - Multi-file comparison

Fleet

GET /api/fleet/data - Real-time fleet status
POST /api/fleet/simulate - Run scenario simulation
POST /api/fleet/material-selection - Material optimization
POST /api/fleet/drill-check - Drill wear analysis

PCB Manufacturing

POST /api/gerber/analyze - Gerber file validation
POST /api/process/etching-control - Etching optimization
POST /api/process/lamination-scaling - Lamination prediction
POST /api/process/plating-optimization - Plating uniformity

Knowledge

POST /api/rag/query - RAG knowledge base search

🎓 Advanced Features

Marathon Agents (Long-Running Workflows)

Pack Audit Workflow:

POST /api/agent/workflow
{
  "workflow_name": "pack_audit",
  "session_id": "audit_session_1",
  "parameters": {
    "pack_id": "PACK-001",
    "depth": "comprehensive"
  }
}

Continuous Monitor Workflow:

POST /api/agent/workflow
{
  "workflow_name": "continuous_monitor",
  "session_id": "monitor_session_1",
  "parameters": {
    "interval_seconds": 30,
    "alert_threshold": "critical"
  }
}

Custom Agent Tools

All agents have access to 20+ specialized tools:

Vision: analyze_battery_image, analyze_pcb_image, analyze_video_stream
Simulation: run_pybamm_simulation, simulate_fleet_scenario, predict_aging_trajectory
Data: parse_charging_data, analyze_eis_spectrum, search_knowledge_base
Fleet: get_fleet_status, control_charging_rate, send_operator_alert
Safety: initiate_emergency_shutdown (HITL confirmation required)

🔬 Scientific Background

Defect Detection Methodology

Follows "Detect-Locate-Describe" framework:

Detect - Identify anomaly presence (swelling, corrosion, thermal runaway)
Locate - Pinpoint physical region (tab, body, terminal)
Describe - Technical electrochemical assessment
Recommend - Immediate mitigation action

Physics-Based Simulation

Uses Doyle-Fuller-Newman (DFN) model - the gold standard for lithium-ion simulation:

Accounts for solid-state diffusion, electrolyte transport, and electrochemical reactions
Predicts voltage, current, temperature with high accuracy
Validates experimental data against first-principles physics

EIS Analysis Layers

Multi-layer impedance diagnosis per IEST standards:

High Frequency (>1kHz) - Ohmic resistance (contact, cable, electrolyte)
Mid Frequency (1Hz-1kHz) - Charge transfer (R_ct), SEI layer
Low Frequency (<1Hz) - Diffusion (Warburg impedance)

🎯 Use Cases

Manufacturing QA

Automated visual inspection at production line speeds
PCB defect detection before assembly
Compliance certification generation
Batch quality trending and analytics

Battery R&D

Charging curve optimization using physics models
Aging mechanism identification from EIS data
Material comparison via multi-file analysis
Protocol validation against knowledge base

Fleet Operations

Predictive maintenance scheduling
Thermal event monitoring with live alerts
Strategic planning via scenario simulation
Emergency response with HITL safety controls

Research & Education

Interactive battery physics visualization
AI-powered technical Q&A with citations
Multimodal analysis demonstrations
Agent reasoning transparency via trace logs

🚀 Deployment

Docker Deployment (Production-Ready)

BatteryForge AI is fully containerized and ready for deployment to any Docker-compatible platform.

Local/Development

docker compose up -d

Cloud Platforms

AWS (Elastic Container Service)

# Push to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account>.dkr.ecr.us-east-1.amazonaws.com
docker tag batteryforgeai-backend:latest <account>.dkr.ecr.us-east-1.amazonaws.com/batteryforge-backend:latest
docker push <account>.dkr.ecr.us-east-1.amazonaws.com/batteryforge-backend:latest
# Deploy via ECS task definition

Google Cloud Platform (Cloud Run)

# Build and deploy
gcloud builds submit --tag gcr.io/<project-id>/batteryforge-backend
gcloud run deploy batteryforge --image gcr.io/<project-id>/batteryforge-backend --platform managed

Azure (Container Instances)

# Deploy via Azure Container Instances
az container create --resource-group batteryforge-rg \
  --name batteryforge-backend \
  --image batteryforgeai-backend \
  --dns-name-label batteryforge \
  --ports 8000

DigitalOcean App Platform

Use docker-compose.yml with App Platform's Docker Compose support
Configure environment variables in dashboard
Automatic HTTPS and scaling

Kubernetes (Advanced)

For high-availability production deployments:

Convert docker-compose.yml to Kubernetes manifests using kompose
Use Helm charts for package management
Configure horizontal pod autoscaling for backend
Set up Ingress for routing

See DOCKER.md for detailed production deployment, security hardening, and monitoring setup.

Data Persistence

All data is preserved across container restarts via Docker volumes:

Analysis history - SQLite database
Knowledge base - ChromaDB vector store
User uploads - Battery images, CSVs, videos

Backup volumes before upgrades:

docker run --rm -v batteryforgeai_battery-db:/data -v $(pwd)/backups:/backup \
  alpine tar czf /backup/battery-db-$(date +%Y%m%d).tar.gz -C /data .

🤝 Contributing

We welcome contributions! Areas of interest:

New specialist agents (compliance, supply chain, thermal management)
Extended tool library (acoustic analysis, X-ray/CT integration)
Custom PyBaMM models (degradation mechanisms, parameter fitting)
Hardware integrations (BMS live telemetry, thermal cameras)

📝 License

This project is built for the Google Gemini 3 Hackathon.

⚡ Powered by Google Gemini 3 & ADK ⚡

🙏 Acknowledgments

Google Gemini Team - For the incredible Gemini 3 and ADK framework
PyBaMM Community - For open-source battery modeling tools
ChromaDB Team - For vector database infrastructure
React Ecosystem - For amazing frontend libraries

📧 Contact & Support

Have questions or want to collaborate?

GitHub Issues - Bug reports and feature requests
Discussions - Technical Q&A and ideas
Email - For partnership inquiries

Built with ❤️ for safer, smarter batteries

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.venv		.venv
backend		backend
frontend		frontend
scripts		scripts
.env		.env
.env.example		.env.example
.gitattributes		.gitattributes
COPY_PASTE_INTEGRATION.js		COPY_PASTE_INTEGRATION.js
DOCKER.md		DOCKER.md
LICENSE		LICENSE
README.md		README.md
doc.md		doc.md
docker-compose.yml		docker-compose.yml
models_log.txt		models_log.txt

Folders and files

Latest commit

History

Repository files navigation

🔋 BatteryForge AI

📋 Table of Contents

🎯 Overview

✨ Key Features

🤖 Multi-Agent Orchestration (ADK)

👁️ Visual Intelligence

⚡ Physics-Based Simulation

🚀 Fleet Management

🏭 PCB Manufacturing

🧠 RAG Knowledge Assistant

🏗️ Architecture

🚀 Quick Start

🐳 Docker Deployment (Recommended)

Prerequisites

One-Command Setup

Access Your Application

Common Commands

💻 Manual Setup (Development)

Prerequisites

Backend Setup

Frontend Setup

📖 Usage Guide

1. Visual Defect Detection

2. Charging Analysis

3. Fleet Monitoring

4. AI Chat Assistant

5. PCB Manufacturing

🛠️ Technology Stack

AI & Machine Learning

Physics & Simulation

Backend

Frontend

Deployment & Infrastructure

📊 API Endpoints

Agent System

Analysis

Fleet

PCB Manufacturing

Knowledge

🎓 Advanced Features

Marathon Agents (Long-Running Workflows)

Custom Agent Tools

🔬 Scientific Background

Defect Detection Methodology

Physics-Based Simulation

EIS Analysis Layers

🎯 Use Cases

Manufacturing QA

Battery R&D

Fleet Operations

Research & Education

🚀 Deployment

Docker Deployment (Production-Ready)

Local/Development

Cloud Platforms

Kubernetes (Advanced)

Data Persistence

🤝 Contributing

📝 License

🙏 Acknowledgments

📧 Contact & Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages