An autonomous grid management assistant that evolves a Milestone 1 ML forecasting model into a multi-node LangGraph agentic workflow with RAG-grounded decision-making and structured report generation.
┌─────────────────────────────────────────────────────────────────┐
│ Streamlit Professional UI │
│ ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌─────────────┐ │
│ │Dashboard │ │Agent Workflow│ │Full Report │ │ RAG Sources │ │
│ └──────────┘ └──────────────┘ └────────────┘ └─────────────┘ │
└─────────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────────▼───────────────────────────────────┐
│ LangGraph Multi-Node Pipeline │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌─────────┐ ┌──────────┐ │
│ │ Analysis │──▶│RAG Retrieval │──▶│Planning │──▶│Generation│ │
│ │ Node │ │ Node │ │ Node │ │ Node │ │
│ └──────────┘ └──────┬───────┘ └─────────┘ └──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ FAISS Vector Store │ │
│ │ (4 Knowledge Bases)│ │
│ └─────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────▼───────────────────────────────────┐
│ Milestone 1 Forecast Model (Trigger) │
│ RandomForestRegressor on Synthetic Solar Data │
└──────────────────────────────────────────────────────────────────┘
AgentState (TypedDict)
├── forecast_data ← Input (Milestone 1 output)
├── analysis_result ← Analysis Node
├── risk_factors ← Analysis Node
├── risk_level ← Analysis Node
├── retrieved_guidelines ← RAG Retrieval Node
├── energy_plan ← Planning Node
├── final_report ← Generation Node
├── current_node ← Control flow
├── error_log ← Annotated[list, operator.add] (reducer)
└── iteration_count ← Safety counter
milestone2/
├── app.py # Streamlit UI entry point
├── requirements.txt # Dependencies
├── README.md # This file
├── Testing_Guide.md # Testing & verification checklist
├── .streamlit/config.toml # Dark theme & server config
├── config/
│ └── settings.py # API keys, model configs, constants
├── agent/ # 🤖 Agent Logic (separated)
│ ├── state.py # TypedDict state schema
│ ├── graph.py # LangGraph workflow definition
│ └── nodes/
│ ├── analysis.py # Solar variability analysis
│ ├── rag_retrieval.py # FAISS retrieval pipeline
│ ├── planning.py # Energy strategy formulation
│ └── generation.py # Structured report generation
├── rag/ # 📚 RAG Logic (separated)
│ ├── documents/ # Knowledge base markdown files
│ │ ├── grid_balancing_guidelines.md
│ │ ├── solar_storage_protocols.md
│ │ ├── energy_regulatory_standards.md
│ │ └── renewable_best_practices.md
│ ├── ingest.py # Document → FAISS indexing
│ └── retriever.py # Semantic retrieval interface
├── models/
│ ├── forecast.py # Milestone 1 synthetic model
│ └── schemas.py # Pydantic output schemas
├── utils/
│ ├── error_handling.py # API retry, hallucination guards
│ └── helpers.py # Utility functions
├── data/ # Sample data directory
└── vectorstore/ # FAISS index (auto-generated)
Modularity: Agent logic (
agent/) and RAG logic (rag/) are fully separated into independent packages with clean interfaces.
- Python 3.10+
- Google Gemini API Key (free tier available at ai.google.dev)
# Clone the repository
git clone <repo-url>
cd milestone2
# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtOption A: Environment Variable
export GOOGLE_API_KEY="your-gemini-api-key-here"Option B: Streamlit Secrets (recommended for deployment)
mkdir -p .streamlit
echo 'GOOGLE_API_KEY = "your-gemini-api-key-here"' > .streamlit/secrets.tomlOption C: In-App Input Enter your API key directly in the sidebar when running the app.
Note: The system works without an API key using statistical fallbacks, but LLM-powered analysis provides significantly richer insights.
streamlit run app.pyThe app opens at http://localhost:8501. Use the sidebar to configure parameters and click Run Grid Optimization Agent.
| Provider | Model | Setup | Cost |
|---|---|---|---|
| Google Gemini (default) | gemini-2.0-flash |
ai.google.dev | Free tier (60 RPM) |
- Go to Google AI Studio
- Sign in with your Google account
- Click "Get API Key" → "Create API Key"
- Copy the key and set it via one of the methods above
- Create a new Space at huggingface.co/new-space
- Select Streamlit as the SDK
- Upload all project files
- Add
GOOGLE_API_KEYas a Space Secret (Settings → Secrets) - The app will auto-deploy
- Push code to a GitHub repository
- Go to share.streamlit.io
- Connect your repo and set
app.pyas the main file - Add
GOOGLE_API_KEYin Advanced Settings → Secrets
- Analysis Node: Statistical computation (CoV, ramp rates) + LLM-powered insights
- RAG Retrieval Node: Risk-adaptive multi-query FAISS retrieval from 4 knowledge bases
- Planning Node: Context-grounded energy strategy formulation
- Generation Node: Pydantic-validated structured report with 6 sections
- Forecast Summary — Generation outlook, variability index, trend
- Risk Analysis — Risk level, factors, mitigation strategies
- Grid Balancing Actions — Prioritized actions with timeframes
- Storage Recommendations — Charge/Discharge/Hold with SoC targets
- Energy Utilization Plan — Solar/Grid/Storage allocation percentages
- References — Cited RAG sources for grounding
- Exponential backoff retry on API failures (3 attempts)
- Graceful degradation with statistical fallbacks
- Hallucination guards: numerical bounds validation, grounding checks
- Pydantic schema validation with fallback parsing
- Dark theme with glassmorphism aesthetic
- Interactive Plotly charts (time-series, daily bars, allocation donut)
- Tabbed layout: Dashboard, Agent Workflow, Full Report, RAG Sources
- Downloadable reports (JSON / TXT)
See Testing_Guide.md for a comprehensive testing checklist covering:
- LangGraph state flow verification
- RAG grounding validation
- Deployment stability checks
- Rubric adherence verification
This project is developed for educational and internship evaluation purposes.