Add Grid-Gent Space code and Dockerfile (no binary assets)

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows the guidelines of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)  
+and this project adheres to **Semantic Versioning**.
+
+---
+
+## [1.0.0] – 11-20-2025
+### Added
+- First public, versioned release of **Grid-Gent**.
+- Support for uploading custom feeder models (`.json` or `.csv`).
+- Agentic scenario engine with:
+  - Unknown/smalltalk handling  
+  - Conceptual explanation mode  
+  - Scenario mode (`simulation`, `hosting_capacity`)
+- Lightweight grid screening logic for early-stage planning.
+- Local web UI (`http://localhost:8000`).
+- Packaging structure for PyPI distribution.
+- Initial example screenshot included in README.
+- GitHub release notes and version tag `v1.0.0`.
+
+---
+

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11-slim
+
+# Work inside /code
+WORKDIR /code
+
+# Copy everything into the image
+COPY . .
+
+# Expose the port Hugging Face expects for Docker Spaces (default 7860)
+EXPOSE 7860
+
+# Run Grid-Gent using your existing entrypoint.
+# main.py reads GRID_GENT_PORT and passes it to run_server(...)
+CMD ["sh", "-c", "GRID_GENT_PORT=${PORT:-7860} python main.py"]

LICENSE

@@ -0,0 +1 @@
+MIT License

README.md

@@ -1,12 +1,69 @@
----
-title: Grid Gent
-emoji: 🐠
-colorFrom: pink
-colorTo: pink
-sdk: docker
-pinned: false
-license: mit
-short_description: Lightweight agentic assistant for early-stage distribution g
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Grid-Gent Demo (v4) – Uploadable Grid Models
+
+Agentic-style assistant for city distribution grid scenarios with:
+
+- Unknown/smalltalk handling (no fake scenarios for 'hi', 'why', etc.).
+- Conceptual explanation mode when no feeder/MW is given.
+- Scenario mode (simulation / hosting_capacity) for actual what-if questions.
+- **New:** Upload your own grid model (JSON or CSV) and the demo will use it.
+
+
+![Grid-Gent UI](app/web/Grid-Gent-1.png)
+
+
+## Running
+
+```bash
+python main.py
+```
+
+Then open http://localhost:8000.
+
+On the right side of the UI you can upload a `.json` or `.csv` file with feeder definitions.
+The server will replace the built-in demo feeders with your uploaded ones (still using a simplified
+calculation, not a full AC power flow).
+
+
+## Background: Why Lightweight Grid Scenario Screening Tools Matter
+
+### Can Utilities Benefit from Lightweight Tools for Early-Stage Grid Scenario Screening?
+
+“Can this feeder handle 1.5 MW of new load?”  
+“What if we add a rooftop solar portfolio in this neighborhood?”
+
+Utility planning engineers are asked variations of these questions constantly. They seem simple, but they come from developers, facility managers, municipalities, and internal stakeholders who simply want to understand what is possible on the distribution grid.
+
+Today, many utilities still rely on the same sophisticated processes used for full-scale planning studies to answer these early-stage questions. It’s often like killing a fly with a missile. This workflow mismatch has quietly become one of the least-discussed bottlenecks in distribution planning, despite the wide range of modeling tools utilities already maintain.
+
+Technologies driving the energy transition—EV charging clusters, distributed solar, data centers, campus loads—create a surge of exploratory inquiries long before a formal interconnection request is filed. This was predictable, and it highlights the need for a middle layer between “no analysis” and “full analysis.”
+
+Lightweight, reasonably accurate early-stage scenario screening could help triage straightforward questions before escalating them to deeper engineering study, reducing unnecessary load on specialists.
+
+### What Should This Early-Stage Screening Tool Look Like?
+
+An effective early-stage screening tool should:
+
+- Translate everyday language into structured parameters a planner can validate.
+- Provide quick approximations of peak loading, hosting capacity, and voltage sensitivities.
+- Be transparent—planners must be able to see and correct the assumptions.
+- Avoid black-box behavior; interpretability is essential.
+
+### The Risks of Ignoring This Problem
+
+If every inquiry is treated as a full-scale study:
+
+- Interconnection backlogs will continue to grow.
+- Developers will lose confidence in utility response times.
+- Electrification and modernization goals will keep slipping.
+
+Ironically, many delays stem from tasks requiring structured reasoning, not deep physics.
+
+### A Path Forward
+
+Agentic Artificial Intelligence (Agentic AI) may serve as this missing early-stage screening layer. A well-designed agentic system can plan a task, reason through assumptions, execute the steps needed for an approximate assessment, and present the results transparently.
+
+Grid-Gent (https://github.com/jamesafful/grid-gent) is one example of an experimental assistant for grid scenario exploration. It enables planners and developers to test multiple scenarios on a simplified feeder model, without invoking a full power flow engine.
+
+### Conclusion
+
+Given the accelerating pace of the energy transition, modern planning workflows need dependable, lightweight tools that complement—not replace—rigorous engineering. Early-stage screening can help utilities respond faster, reduce bottlenecks, and improve overall planning efficiency.

app/__init__.py

@@ -0,0 +1 @@
+# package

app/server.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+import json
+import os
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlparse
+from typing import Tuple
+
+from gridgent.core.orchestrator import GridGentOrchestrator
+from gridgent.tools.grid_stub import parse_uploaded_grid, save_uploaded_grid, get_all_feeders
+
+
+ORCHESTRATOR = GridGentOrchestrator()
+
+
+def _read_file(path: str) -> str:
+    here = os.path.dirname(os.path.abspath(__file__))
+    full = os.path.join(here, "web", path)
+    with open(full, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+class GridGentHandler(BaseHTTPRequestHandler):
+    def _set_common_headers(self, status: int = 200, content_type: str = "text/html; charset=utf-8"):
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+        self.send_header("Access-Control-Allow-Methods", "POST, GET, OPTIONS")
+        self.end_headers()
+
+    def log_message(self, format, *args):
+        return
+
+    def do_OPTIONS(self):
+        self._set_common_headers(200)
+
+    def do_GET(self):
+        parsed = urlparse(self.path)
+        if parsed.path in ("/", "/index.html"):
+            try:
+                html = _read_file("index.html")
+                self._set_common_headers(200, "text/html; charset=utf-8")
+                self.wfile.write(html.encode("utf-8"))
+            except FileNotFoundError:
+                self._set_common_headers(500, "text/plain; charset=utf-8")
+                self.wfile.write(b"index.html not found")
+        elif parsed.path == "/api/feeders":
+            data = get_all_feeders()
+            self._set_common_headers(200, "application/json; charset=utf-8")
+            self.wfile.write(json.dumps({"feeders": data}).encode("utf-8"))
+        else:
+            self._set_common_headers(404, "text/plain; charset=utf-8")
+            self.wfile.write(b"Not Found")
+
+    def _read_json(self) -> Tuple[bool, dict]:
+        length = int(self.headers.get("Content-Length") or "0")
+        try:
+            body = self.rfile.read(length).decode("utf-8")
+            data = json.loads(body)
+            return True, data
+        except Exception as exc:
+            return False, {"error": f"Invalid JSON body: {exc}"}
+
+    def do_POST(self):
+        parsed = urlparse(self.path)
+        if parsed.path == "/api/ask":
+            ok, data = self._read_json()
+            if not ok:
+                self._set_common_headers(400, "application/json; charset=utf-8")
+                self.wfile.write(json.dumps(data).encode("utf-8"))
+                return
+
+            query = str(data.get("query") or "").strip()
+            if not query:
+                self._set_common_headers(400, "application/json; charset=utf-8")
+                self.wfile.write(json.dumps({"error": "Missing 'query' in request body"}).encode("utf-8"))
+                return
+
+            result = ORCHESTRATOR.run(query)
+            resp = result.to_dict()
+            self._set_common_headers(200, "application/json; charset=utf-8")
+            self.wfile.write(json.dumps(resp).encode("utf-8"))
+        elif parsed.path == "/api/upload-grid":
+            ok, data = self._read_json()
+            if not ok:
+                self._set_common_headers(400, "application/json; charset=utf-8")
+                self.wfile.write(json.dumps(data).encode("utf-8"))
+                return
+            raw = data.get("raw")
+            fmt = data.get("format")
+            if not raw or not fmt:
+                self._set_common_headers(400, "application/json; charset=utf-8")
+                self.wfile.write(json.dumps({"error": "Missing 'raw' or 'format' in request body"}).encode("utf-8"))
+                return
+            try:
+                cfg = parse_uploaded_grid(str(raw), str(fmt))
+                save_uploaded_grid(cfg)
+                feeders = list(cfg.get("feeders", {}).keys())
+                self._set_common_headers(200, "application/json; charset=utf-8")
+                self.wfile.write(json.dumps({"status": "ok", "feeders_loaded": feeders}).encode("utf-8"))
+            except Exception as exc:
+                self._set_common_headers(400, "application/json; charset=utf-8")
+                self.wfile.write(json.dumps({"error": str(exc)}).encode("utf-8"))
+        else:
+            self._set_common_headers(404, "application/json; charset=utf-8")
+            self.wfile.write(json.dumps({"error": "Not Found"}).encode("utf-8"))
+
+
+def run_server(host: str = "0.0.0.0", port: int = 8000):
+    server_address = (host, port)
+    httpd = ThreadingHTTPServer(server_address, GridGentHandler)
+    print(f"Grid-Gent demo server running at http://{host}:{port}")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nShutting down server...")
+    finally:
+        httpd.server_close()
+
+
+if __name__ == "__main__":
+    port_str = os.environ.get("GRID_GENT_PORT", "8000")
+    try:
+        port = int(port_str)
+    except ValueError:
+        port = 8000
+    run_server(port=port)

app/web/index.html

@@ -0,0 +1,389 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <title>Grid-Gent Demo</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+        :root {
+            font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+            background-color: #0f172a;
+            color: #e5e7eb;
+        }
+        body { margin: 0; padding: 0; }
+        .page { max-width: 1040px; margin: 0 auto; padding: 24px 16px 48px; }
+        .card {
+            background: #020617;
+            border-radius: 16px;
+            padding: 20px;
+            box-shadow: 0 18px 40px rgba(15,23,42,0.8);
+            border: 1px solid rgba(148, 163, 184, 0.2);
+        }
+        h1 { font-size: 1.8rem; margin-bottom: 0.25rem; }
+        h2 { font-size: 1.1rem; margin: 0; color: #9ca3af; }
+        textarea {
+            width: 100%;
+            min-height: 90px;
+            padding: 10px 12px;
+            border-radius: 10px;
+            border: 1px solid #4b5563;
+            background: #020617;
+            color: #e5e7eb;
+            resize: vertical;
+            font-family: inherit;
+            font-size: 0.95rem;
+        }
+        textarea:focus {
+            outline: none;
+            border-color: #38bdf8;
+            box-shadow: 0 0 0 1px #0ea5e9;
+        }
+        button {
+            margin-top: 10px;
+            padding: 9px 16px;
+            border-radius: 999px;
+            border: none;
+            background: linear-gradient(135deg, #0ea5e9, #22c55e);
+            color: white;
+            font-weight: 600;
+            cursor: pointer;
+            font-size: 0.95rem;
+            display: inline-flex;
+            align-items: center;
+            gap: 6px;
+        }
+        button:disabled { opacity: 0.5; cursor: not-allowed; }
+        .answer {
+            margin-top: 18px;
+            white-space: pre-wrap;
+            background: #020617;
+            border-radius: 10px;
+            padding: 12px 14px;
+            border: 1px solid #4b5563;
+            font-size: 0.9rem;
+        }
+        .answer-badge {
+            display: inline-block;
+            font-size: 0.75rem;
+            padding: 3px 8px;
+            border-radius: 999px;
+            border: 1px solid rgba(248, 250, 252, 0.2);
+            background: rgba(127, 29, 29, 0.6);
+            color: #fecaca;
+            margin-bottom: 6px;
+        }
+        .steps { margin-top: 16px; font-size: 0.8rem; }
+        .step {
+            padding: 8px 10px;
+            border-radius: 8px;
+            border: 1px solid rgba(75,85,99,0.7);
+            background: rgba(15,23,42,0.8);
+            margin-bottom: 6px;
+        }
+        .step strong { color: #a5b4fc; }
+        .badge {
+            display: inline-block;
+            padding: 2px 7px;
+            border-radius: 999px;
+            font-size: 0.7rem;
+            background: rgba(15,118,110,0.3);
+            color: #a7f3d0;
+            margin-left: 6px;
+        }
+        .badge-secondary {
+            background: rgba(30,64,175,0.5);
+            color: #bfdbfe;
+        }
+        .header-row {
+            display: flex;
+            justify-content: space-between;
+            align-items: baseline;
+            gap: 12px;
+            flex-wrap: wrap;
+        }
+        .pill {
+            font-size: 0.75rem;
+            padding: 4px 10px;
+            border-radius: 999px;
+            border: 1px solid rgba(148,163,184,0.5);
+            color: #e5e7eb;
+        }
+        .examples {
+            margin-top: 10px;
+            font-size: 0.8rem;
+            color: #9ca3af;
+        }
+        .examples code {
+            background: rgba(15,23,42,0.8);
+            padding: 2px 6px;
+            border-radius: 6px;
+            font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+        }
+        .layout {
+            display: grid;
+            grid-template-columns: minmax(0, 2.2fr) minmax(0, 1.2fr);
+            gap: 18px;
+            margin-top: 18px;
+        }
+        @media (max-width: 900px) {
+            .layout { grid-template-columns: minmax(0, 1fr); }
+        }
+        .panel {
+            border-radius: 12px;
+            border: 1px solid rgba(148,163,184,0.25);
+            padding: 12px 12px 14px;
+            background: rgba(15,23,42,0.8);
+        }
+        .panel-title {
+            font-size: 0.9rem;
+            font-weight: 600;
+            margin-bottom: 6px;
+        }
+        .panel-sub {
+            font-size: 0.75rem;
+            color: #9ca3af;
+            margin-bottom: 6px;
+        }
+        input[type="file"] {
+            font-size: 0.8rem;
+        }
+        .status {
+            margin-top: 6px;
+            font-size: 0.75rem;
+            color: #9ca3af;
+            white-space: pre-wrap;
+        }
+        .feeders-list {
+            margin-top: 4px;
+            font-size: 0.78rem;
+        }
+        .feeders-list code {
+            background: rgba(15,23,42,0.8);
+            padding: 1px 5px;
+            border-radius: 6px;
+        }
+    </style>
+</head>
+<body>
+    <div class="page">
+        <div class="card">
+            <div class="header-row">
+                <div>
+                    <h1>Grid-Gent Demo</h1>
+                    <h2>Agentic assistant for city distribution grid scenarios (simplified)</h2>
+                </div>
+                <div class="pill">Offline demo · no real grid connection</div>
+            </div>
+
+            <div class="layout">
+                <div>
+                    <div>
+                        <label for="query">Describe a grid scenario or question:</label>
+                        <textarea id="query" placeholder="Example: What happens on feeder F2 if we add 5 MW of rooftop PV?"></textarea>
+                        <button id="ask-btn" onclick="sendQuery()">
+                            <span id="btn-label">Run Grid-Gent</span>
+                            <span id="btn-spinner" style="display:none;">⏳</span>
+                        </button>
+                    </div>
+
+                    <div class="examples">
+                        Try things like:
+                        <div><code>What happens on feeder F2 if we add 5 MW of rooftop PV?</code></div>
+                        <div><code>Simulate adding 3 MW of load on feeder F1.</code></div>
+                    </div>
+
+                    <div id="answer" class="answer" style="display:none;">
+                        <div class="answer-badge">Demo only · not using your real grid data unless you upload a model · not for operational decisions</div>
+                        <div id="answer-text"></div>
+                    </div>
+                    <div id="steps" class="steps" style="display:none;"></div>
+                </div>
+
+                <div>
+                    <div class="panel">
+                        <div class="panel-title">Upload grid model (JSON or CSV)</div>
+                        <div class="panel-sub">
+                            We will replace the demo feeders with your uploaded ones (still using a simplified calculation).
+                        </div>
+                        <input type="file" id="grid-file" accept=".json,.csv" />
+                        <button id="upload-btn" style="margin-top:8px;" onclick="uploadGrid()">
+                            <span id="upload-label">Upload model</span>
+                            <span id="upload-spinner" style="display:none;">⏳</span>
+                        </button>
+                        <div id="upload-status" class="status"></div>
+                    </div>
+
+                    <div class="panel" style="margin-top:10px;">
+                        <div class="panel-title">Currently loaded feeders</div>
+                        <div class="panel-sub">Based on demo data or your last upload.</div>
+                        <div id="feeders" class="feeders-list">Loading...</div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        async function refreshFeeders() {
+            const el = document.getElementById("feeders");
+            try {
+                const resp = await fetch("/api/feeders");
+                if (!resp.ok) {
+                    el.textContent = "Error loading feeders.";
+                    return;
+                }
+                const data = await resp.json();
+                const feeders = data.feeders || {};
+                const ids = Object.keys(feeders);
+                if (!ids.length) {
+                    el.textContent = "No feeders configured.";
+                    return;
+                }
+                const parts = ids.map(id => {
+                    const f = feeders[id];
+                    const name = f.name || id;
+                    const peak = f.peak_mw;
+                    return id + " – " + name + " (" + peak + " MW peak)";
+                });
+                el.innerHTML = parts.map(p => "<div><code>" + p + "</code></div>").join("");
+            } catch (e) {
+                el.textContent = "Error loading feeders: " + e;
+            }
+        }
+
+        async function sendQuery() {
+            const textarea = document.getElementById("query");
+            const btn = document.getElementById("ask-btn");
+            const label = document.getElementById("btn-label");
+            const spinner = document.getElementById("btn-spinner");
+            const answerBox = document.getElementById("answer");
+            const answerText = document.getElementById("answer-text");
+            const stepsEl = document.getElementById("steps");
+
+            const query = textarea.value.trim();
+            if (!query) {
+                alert("Please enter a scenario or question.");
+                return;
+            }
+
+            btn.disabled = true;
+            spinner.style.display = "inline-block";
+            label.textContent = "Running...";
+
+            try {
+                const resp = await fetch("/api/ask", {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ query })
+                });
+                const data = await resp.json();
+
+                if (!resp.ok) {
+                    answerBox.style.display = "block";
+                    answerText.textContent = "Error: " + (data.error || resp.statusText);
+                    stepsEl.style.display = "none";
+                    return;
+                }
+
+                answerBox.style.display = "block";
+                answerText.textContent = data.answer || "(No answer returned)";
+
+                stepsEl.innerHTML = "";
+                if (Array.isArray(data.steps)) {
+                    stepsEl.style.display = "block";
+                    data.steps.forEach(step => {
+                        const div = document.createElement("div");
+                        div.className = "step";
+                        const role = step.role || "agent";
+                        const meta = step.meta || {};
+                        const intent = meta.intent || "";
+                        const feeder = meta.feeder || "";
+                        let badgesHtml = "";
+                        if (intent) {
+                            badgesHtml += "<span class=\"badge\">" + intent + "</span>";
+                        }
+                        if (feeder) {
+                            badgesHtml += "<span class=\"badge badge-secondary\">" + feeder + "</span>";
+                        }
+                        div.innerHTML = "<div><strong>" + role + "</strong> " + badgesHtml + "</div>" +
+                                        "<div>" + step.content + "</div>";
+                        stepsEl.appendChild(div);
+                    });
+                } else {
+                    stepsEl.style.display = "none";
+                }
+            } catch (err) {
+                answerBox.style.display = "block";
+                answerText.textContent = "Request failed: " + err;
+                stepsEl.style.display = "none";
+            } finally {
+                btn.disabled = false;
+                spinner.style.display = "none";
+                label.textContent = "Run Grid-Gent";
+            }
+        }
+
+        async function uploadGrid() {
+            const input = document.getElementById("grid-file");
+            const status = document.getElementById("upload-status");
+            const btn = document.getElementById("upload-btn");
+            const label = document.getElementById("upload-label");
+            const spinner = document.getElementById("upload-spinner");
+
+            const file = input.files[0];
+            if (!file) {
+                alert("Please choose a JSON or CSV file first.");
+                return;
+            }
+
+            let fmt = "json";
+            if (file.name.toLowerCase().endsWith(".csv")) {
+                fmt = "csv";
+            } else if (file.name.toLowerCase().endsWith(".json")) {
+                fmt = "json";
+            } else {
+                alert("File extension must be .json or .csv");
+                return;
+            }
+
+            btn.disabled = true;
+            spinner.style.display = "inline-block";
+            label.textContent = "Uploading...";
+
+            const reader = new FileReader();
+            reader.onload = async () => {
+                const raw = reader.result;
+                try {
+                    const resp = await fetch("/api/upload-grid", {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({ raw, format: fmt })
+                    });
+                    const data = await resp.json();
+                    if (!resp.ok) {
+                        status.textContent = "Upload failed: " + (data.error || resp.statusText);
+                    } else {
+                        status.textContent = "Upload succeeded. Feeders loaded: " + (data.feeders_loaded || []).join(", ");
+                        refreshFeeders();
+                    }
+                } catch (e) {
+                    status.textContent = "Upload failed: " + e;
+                } finally {
+                    btn.disabled = false;
+                    spinner.style.display = "none";
+                    label.textContent = "Upload model";
+                }
+            };
+            reader.onerror = () => {
+                status.textContent = "Could not read file.";
+                btn.disabled = false;
+                spinner.style.display = "none";
+                label.textContent = "Upload model";
+            };
+            reader.readAsText(file);
+        }
+
+        refreshFeeders();
+    </script>
+</body>
+</html>

config/feeders.json

@@ -0,0 +1,25 @@
+{
+  "feeders": {
+    "F1": {
+      "name": "Feeder F1 - Downtown Core",
+      "base_kv": 13.8,
+      "num_customers": 4200,
+      "peak_mw": 18.5,
+      "pv_mw": 3.2
+    },
+    "F2": {
+      "name": "Feeder F2 - Residential West",
+      "base_kv": 13.8,
+      "num_customers": 5100,
+      "peak_mw": 14.3,
+      "pv_mw": 4.7
+    },
+    "F3": {
+      "name": "Feeder F3 - Industrial Park",
+      "base_kv": 13.8,
+      "num_customers": 830,
+      "peak_mw": 22.1,
+      "pv_mw": 0.8
+    }
+  }
+}

config/uploaded_feedermodel.json

@@ -0,0 +1,11 @@
+{
+  "feeders": {
+    "Q1": {
+      "name": "Feeder Q1",
+      "base_kv": 13.8,
+      "num_customers": 100,
+      "peak_mw": 5.0,
+      "pv_mw": 0.5
+    }
+  }
+}

gridgent/__init__.py

@@ -0,0 +1 @@
+# package

gridgent/agents.py

@@ -0,0 +1,146 @@
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Dict, Any, List, Literal, Tuple
+from . import tools
+
+StepRole = Literal["user", "intent_agent", "planning_agent", "narrator_agent", "tool"]
+
+
+@dataclass
+class Step:
+    role: StepRole
+    content: str
+    meta: Dict[str, Any]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "role": self.role,
+            "content": self.content,
+            "meta": self.meta,
+        }
+
+
+class IntentAgent:
+    def classify(self, query: str) -> Dict[str, Any]:
+        text = query.lower()
+        if any(k in text for k in ["what if", "simulate", "scenario", "contingency", "impact of"]):
+            intent = "simulation"
+        elif any(k in text for k in ["host", "hosting capacity", "add pv", "add ev", "der"]):
+            intent = "hosting_capacity"
+        elif any(k in text for k in ["explain", "why", "how does"]):
+            intent = "explanation"
+        else:
+            intent = "simulation"
+
+        feeder = "F1"
+        if "f2" in text or "feeder 2" in text:
+            feeder = "F2"
+        elif "f3" in text or "feeder 3" in text:
+            feeder = "F3"
+
+        added_pv = 0.0
+        added_load = 0.0
+        import re
+
+        mw_matches = re.findall(r"(\d+(?:\.\d+)?)\s*mw", text)
+        if mw_matches:
+            value = float(mw_matches[0])
+            if "pv" in text or "solar" in text:
+                added_pv = value
+            else:
+                added_load = value
+
+        return {
+            "intent": intent,
+            "feeder": feeder,
+            "added_pv_mw": added_pv,
+            "added_load_mw": added_load,
+        }
+
+
+class PlanningAgent:
+    def plan_and_analyze(self, query: str, intent_info: Dict[str, Any]) -> Tuple[str, Dict[str, Any], List[Step]]:
+        feeder = intent_info["feeder"]
+        added_pv = float(intent_info.get("added_pv_mw", 0.0))
+        added_load = float(intent_info.get("added_load_mw", 0.0))
+
+        steps: List[Step] = []
+        summary = (
+            f"Analyzing feeder {feeder} with added PV={added_pv:.1f} MW, "
+            f"added load={added_load:.1f} MW using a simplified power-flow stub."
+        )
+        steps.append(Step(role="planning_agent", content=summary, meta={"feeder": feeder}))
+
+        pf_result = tools.run_power_flow_scenario(feeder, added_pv_mw=added_pv, added_load_mw=added_load)
+        steps.append(
+            Step(
+                role="tool",
+                content="Ran simplified power-flow scenario.",
+                meta=pf_result.to_dict(),
+            )
+        )
+
+        feeder_meta = tools.get_feeder_summary(feeder)
+        steps.append(
+            Step(
+                role="tool",
+                content="Retrieved static feeder metadata.",
+                meta=feeder_meta,
+            )
+        )
+
+        technical_summary = {
+            "intent": intent_info["intent"],
+            "feeder": feeder,
+            "added_pv_mw": added_pv,
+            "added_load_mw": added_load,
+            "power_flow": pf_result.to_dict(),
+            "feeder_meta": feeder_meta,
+        }
+
+        return "ok", technical_summary, steps
+
+
+class NarratorAgent:
+    def narrate(self, query: str, technical: Dict[str, Any]) -> str:
+        pf = technical["power_flow"]
+        meta = technical["feeder_meta"]
+
+        lines: List[str] = []
+        lines.append(f"You asked: {query.strip()}")
+        lines.append("")
+        lines.append(f"Here's what Grid-Gent found for {meta['name']}:")
+        lines.append(
+            f"- Base peak demand (demo data): {meta['peak_mw']} MW with about {meta['num_customers']} customers."
+        )
+        lines.append(
+            f"- In this scenario, we assumed +{technical['added_load_mw']:.1f} MW of extra load and "
+            f"+{technical['added_pv_mw']:.1f} MW of additional PV."
+        )
+        lines.append("")
+        lines.append("Simplified power-flow-style results (demo model):")
+        lines.append(f"- Peak loading: {pf['peak_loading_pct']:.1f}% of an approximate rating.")
+        lines.append(f"- Minimum voltage: {pf['min_voltage_pu']:.3f} pu")
+        lines.append(f"- Maximum voltage: {pf['max_voltage_pu']:.3f} pu")
+
+        if pf["overload_elements"]:
+            lines.append("")
+            lines.append("Potential issues flagged:")
+            for item in pf["overload_elements"]:
+                lines.append(f"  • {item}")
+        else:
+            lines.append("")
+            lines.append("No major issues were flagged in this simplified view.")
+
+        lines.append("")
+        lines.append(pf["notes"])
+
+        lines.append("")
+        lines.append(
+            "Note: this is a deliberately simplified demo model. A real deployment would "
+            "use your actual network model, load/DER data, and planning criteria, and would "
+            "treat these results as advisory, subject to engineer review."
+        )
+
+        return "\n".join(lines)

gridgent/agents/__init__.py

@@ -0,0 +1 @@
+# package

gridgent/agents/intent.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+from typing import Dict, Any
+import re
+
+
+class IntentAgent:
+    """Deterministic intent classifier for demo."""
+
+    def classify(self, query: str) -> Dict[str, Any]:
+        text = (query or "").lower().strip()
+
+        smalltalk_tokens = {
+            "hi",
+            "hello",
+            "hey",
+            "yo",
+            "thanks",
+            "thank you",
+            "thx",
+            "ok",
+            "okay",
+            "k",
+        }
+        if text in smalltalk_tokens or text in {"why", "?", "??"} or len(text) <= 2:
+            return {
+                "intent": "unknown",
+                "feeder": None,
+                "added_pv_mw": 0.0,
+                "added_load_mw": 0.0,
+                "has_mw": False,
+                "has_feeder": False,
+                "has_grid_keywords": False,
+            }
+
+        has_mw = bool(re.search(r"(\d+(?:\.\d+)?)\s*mw", text))
+        mentions_feeder = any(
+            tok in text for tok in ["feeder f1", "feeder f2", "feeder f3", "f1", "f2", "f3", "feeder"]
+        )
+        grid_keywords = any(
+            k in text
+            for k in [
+                "load",
+                "pv",
+                "solar",
+                "rooftop",
+                "substation",
+                "transformer",
+                "grid",
+                "voltage",
+                "hosting capacity",
+                "hosting",
+                "scenario",
+                "contingency",
+            ]
+        )
+
+        if not (has_mw or mentions_feeder or grid_keywords):
+            return {
+                "intent": "unknown",
+                "feeder": None,
+                "added_pv_mw": 0.0,
+                "added_load_mw": 0.0,
+                "has_mw": False,
+                "has_feeder": False,
+                "has_grid_keywords": False,
+            }
+
+        if any(k in text for k in ["host", "hosting capacity", "add pv", "rooftop pv", "solar"]):
+            intent = "hosting_capacity"
+        elif any(k in text for k in ["explain", "how does"]):
+            intent = "explanation"
+        elif "why" in text:
+            intent = "explanation"
+        else:
+            intent = "simulation"
+
+        feeder = None
+        if "feeder f2" in text or "feeder 2" in text or "f2" in text:
+            feeder = "F2"
+        elif "feeder f3" in text or "feeder 3" in text or "f3" in text:
+            feeder = "F3"
+        elif "feeder f1" in text or "feeder 1" in text or "f1" in text:
+            feeder = "F1"
+
+        added_pv = 0.0
+        added_load = 0.0
+        mw_matches = re.findall(r"(\d+(?:\.\d+)?)\s*mw", text)
+        if mw_matches:
+            value = float(mw_matches[0])
+            if "pv" in text or "solar" in text or "rooftop" in text:
+                added_pv = value
+            else:
+                added_load = value
+
+        return {
+            "intent": intent,
+            "feeder": feeder,
+            "added_pv_mw": added_pv,
+            "added_load_mw": added_load,
+            "has_mw": has_mw,
+            "has_feeder": feeder is not None,
+            "has_grid_keywords": grid_keywords,
+        }

gridgent/agents/narrator.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+from typing import Dict, Any, List
+
+
+class NarratorAgent:
+    def narrate(self, query: str, technical: Dict[str, Any]) -> str:
+        intent = technical.get("intent", "simulation")
+
+        if intent == "unknown":
+            msg = technical.get(
+                "message",
+                "I couldn't recognize a specific grid scenario in your question.",
+            )
+            lines: List[str] = []
+            lines.append(f"You asked: {query.strip()}")
+            lines.append("")
+            lines.append("I didn't see enough detail to run a grid scenario.")
+            lines.append(msg)
+            lines.append("")
+            lines.append("Try asking something like:")
+            lines.append("- What happens on feeder F2 if we add 5 MW of rooftop PV?")
+            lines.append("- Simulate adding 3 MW of load on feeder F1.")
+            lines.append("- What is the impact on voltages if load grows by 2 MW on feeder F3?")
+            return "\n".join(lines)
+
+        if intent == "explanation" and "power_flow" not in technical:
+            topic = technical.get("topic_hint", "").lower()
+            lines = []
+            lines.append(f"You asked: {query.strip()}")
+            lines.append("")
+            lines.append("This looks like a high-level explanation request rather than a specific feeder scenario.")
+            lines.append(
+                "Grid-Gent is a demo of an agentic assistant for distribution grids. It can explore simplified "
+                "scenarios like adding MW of load or PV on a feeder and report approximate loading and voltage impacts."
+            )
+            if "hosting" in topic or "capacity" in topic:
+                lines.append("")
+                lines.append(
+                    "In real systems, 'hosting capacity' refers to how much additional DER (like rooftop PV) can be "
+                    "connected without violating voltage, thermal, protection, or power quality limits. "
+                    "Utilities usually study this using detailed feeder models and time-series simulations."
+                )
+            lines.append("")
+            lines.append("To see the demo in action, try asking things like:")
+            lines.append("- What happens on feeder F2 if we add 5 MW of rooftop PV?")
+            lines.append("- Simulate adding 3 MW of load on feeder F1.")
+            return "\n".join(lines)
+
+        pf = technical["power_flow"]
+        meta = technical["feeder_meta"]
+        loading_margin = float(technical.get("loading_margin_pct", 0.0))
+
+        lines: List[str] = []
+        lines.append(f"You asked: {query.strip()}")
+        lines.append("")
+        lines.append(f"Here's what Grid-Gent found for {meta['name']}:")
+        lines.append(
+            f"- Base peak demand (demo data): {meta['peak_mw']} MW with about {meta['num_customers']} customers."
+        )
+        lines.append(
+            f"- In this scenario, we assumed +{technical['added_load_mw']:.1f} MW of extra load and "
+            f"+{technical['added_pv_mw']:.1f} MW of additional PV."
+        )
+        lines.append("")
+        lines.append("Simplified power-flow-style results (demo model):")
+        lines.append(f"- Peak loading: {pf['peak_loading_pct']:.1f}% of an approximate rating.")
+        lines.append(f"- Loading margin to 100% (approx): {loading_margin:.1f}% points.")
+        lines.append(f"- Minimum voltage: {pf['min_voltage_pu']:.3f} pu")
+        lines.append(f"- Maximum voltage: {pf['max_voltage_pu']:.3f} pu")
+
+        if pf["overload_elements"]:
+            lines.append("")
+            lines.append("Potential issues flagged in this simplified view:")
+            for item in pf["overload_elements"]:
+                lines.append(f"  • {item}")
+        else:
+            lines.append("")
+            lines.append("No major issues were flagged in this simplified view.")
+
+        if intent == "hosting_capacity":
+            lines.append("")
+            lines.append(
+                "Hosting capacity interpretation (demo-only): In this toy model, we look at loading and "
+                "voltage margins as a proxy for how much additional PV the feeder might host. "
+                "Here, the approximate loading and voltage range suggest whether the added PV appears acceptable "
+                "in this simplified analysis. Real hosting capacity studies must use detailed feeder models, "
+                "time-series behavior, and utility planning criteria, and are typically performed by power "
+                "system engineers."
+            )
+
+        lines.append("")
+        lines.append(pf["notes"])
+
+        lines.append("")
+        lines.append(
+            "Important: This is a deliberately simplified demonstration model. A real deployment would "
+            "use your actual network model, load/DER data, and planning criteria, and would treat all outputs "
+            "as advisory, subject to engineer review and formal studies. Do not use this demo for operational "
+            "or investment decisions."
+        )
+
+        return "\n".join(lines)

gridgent/agents/planning.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+from typing import Dict, Any, List, Tuple
+
+from gridgent.core.types import Step
+from gridgent.tools.grid_stub import run_power_flow_scenario, get_feeder_summary
+
+
+class PlanningAgent:
+    def plan_and_analyze(self, query: str, intent_info: Dict[str, Any]) -> Tuple[str, Dict[str, Any], List[Step]]:
+        intent = intent_info["intent"]
+        steps: List[Step] = []
+
+        if intent == "unknown":
+            msg = (
+                "Received an underspecified or conversational query; no grid scenario was run. "
+                "Please mention at least a feeder (F1/F2/F3) and a change in MW load or PV."
+            )
+            steps.append(
+                Step(
+                    role="planning_agent",
+                    content=msg,
+                    meta={"intent": intent},
+                )
+            )
+            technical_summary: Dict[str, Any] = {
+                "intent": intent,
+                "message": msg,
+            }
+            return "no_scenario", technical_summary, steps
+
+        has_mw = bool(intent_info.get("has_mw"))
+        has_feeder = bool(intent_info.get("has_feeder"))
+
+        if intent == "explanation" and not has_mw and not has_feeder:
+            steps.append(
+                Step(
+                    role="planning_agent",
+                    content="No specific feeder or MW change detected; treating as conceptual explanation request.",
+                    meta={"intent": intent},
+                )
+            )
+            technical_summary = {
+                "intent": intent,
+                "topic_hint": query.strip(),
+            }
+            return "conceptual", technical_summary, steps
+
+        feeder = intent_info.get("feeder")
+        defaulted_feeder = False
+        if not feeder:
+            feeder = "F1"
+            defaulted_feeder = True
+
+        added_pv = float(intent_info.get("added_pv_mw", 0.0))
+        added_load = float(intent_info.get("added_load_mw", 0.0))
+
+        summary = (
+            f"Analyzing feeder {feeder} with added PV={added_pv:.1f} MW, "
+            f"added load={added_load:.1f} MW using a simplified power-flow stub."
+        )
+        steps.append(
+            Step(
+                role="planning_agent",
+                content=summary,
+                meta={"feeder": feeder, "defaulted_feeder": defaulted_feeder},
+            )
+        )
+
+        pf_result = run_power_flow_scenario(feeder, added_pv_mw=added_pv, added_load_mw=added_load)
+        pf_dict = pf_result.to_dict()
+        steps.append(
+            Step(
+                role="tool",
+                content="Ran simplified power-flow scenario (demo).",
+                meta=pf_dict,
+            )
+        )
+
+        feeder_meta = get_feeder_summary(feeder)
+        steps.append(
+            Step(
+                role="tool",
+                content="Retrieved static feeder metadata from config.",
+                meta=feeder_meta,
+            )
+        )
+
+        technical_summary: Dict[str, Any] = {
+            "intent": intent,
+            "feeder": feeder,
+            "added_pv_mw": added_pv,
+            "added_load_mw": added_load,
+            "power_flow": pf_dict,
+            "feeder_meta": feeder_meta,
+        }
+
+        rating_pct = pf_dict["peak_loading_pct"]
+        technical_summary["loading_margin_pct"] = max(0.0, 100.0 - rating_pct)
+
+        return "ok", technical_summary, steps

gridgent/core/__init__.py

@@ -0,0 +1 @@
+# package

gridgent/core/orchestrator.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+import uuid
+from typing import List
+
+from gridgent.core.types import Step, OrchestratorResult
+from gridgent.agents.intent import IntentAgent
+from gridgent.agents.planning import PlanningAgent
+from gridgent.agents.narrator import NarratorAgent
+
+
+class GridGentOrchestrator:
+    def __init__(self) -> None:
+        self.intent_agent = IntentAgent()
+        self.planning_agent = PlanningAgent()
+        self.narrator_agent = NarratorAgent()
+
+    def run(self, query: str) -> OrchestratorResult:
+        task_id = str(uuid.uuid4())
+        steps: List[Step] = []
+
+        intent_info = self.intent_agent.classify(query)
+        steps.append(
+            Step(
+                role="intent_agent",
+                content=(
+                    f"Classified intent as '{intent_info['intent']}'"
+                    + (f" and selected feeder {intent_info['feeder']}." if intent_info.get("feeder") else ".")
+                ),
+                meta=intent_info,
+            )
+        )
+
+        status, technical_summary, planning_steps = self.planning_agent.plan_and_analyze(query, intent_info)
+        steps.extend(planning_steps)
+
+        answer = self.narrator_agent.narrate(query, technical_summary)
+        steps.append(
+            Step(
+                role="narrator_agent",
+                content="Generated human-readable explanation for planner/operator.",
+                meta={"status": status},
+            )
+        )
+
+        return OrchestratorResult(task_id=task_id, answer=answer, steps=steps)

gridgent/core/types.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Dict, Any, List, Literal
+
+StepRole = Literal["user", "intent_agent", "planning_agent", "narrator_agent", "tool"]
+
+
+@dataclass
+class Step:
+    role: StepRole
+    content: str
+    meta: Dict[str, Any]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "role": self.role,
+            "content": self.content,
+            "meta": self.meta,
+        }
+
+
+@dataclass
+class OrchestratorResult:
+    task_id: str
+    answer: str
+    steps: List[Step]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "answer": self.answer,
+            "steps": [s.to_dict() for s in self.steps],
+        }

gridgent/orchestrator.py

@@ -0,0 +1,55 @@
+
+from __future__ import annotations
+import uuid
+from dataclasses import dataclass
+from typing import List, Dict, Any
+
+from .agents import IntentAgent, PlanningAgent, NarratorAgent, Step
+
+
+@dataclass
+class OrchestratorResult:
+    task_id: str
+    answer: str
+    steps: List[Step]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "answer": self.answer,
+            "steps": [s.to_dict() for s in self.steps],
+        }
+
+
+class GridGentOrchestrator:
+    def __init__(self) -> None:
+        self.intent_agent = IntentAgent()
+        self.planning_agent = PlanningAgent()
+        self.narrator_agent = NarratorAgent()
+
+    def run(self, query: str) -> OrchestratorResult:
+        task_id = str(uuid.uuid4())
+        steps: List[Step] = []
+
+        intent_info = self.intent_agent.classify(query)
+        steps.append(
+            Step(
+                role="intent_agent",
+                content=f"Classified intent as '{intent_info['intent']}' and selected feeder {intent_info['feeder']}.",
+                meta=intent_info,
+            )
+        )
+
+        status, technical_summary, planning_steps = self.planning_agent.plan_and_analyze(query, intent_info)
+        steps.extend(planning_steps)
+
+        answer = self.narrator_agent.narrate(query, technical_summary)
+        steps.append(
+            Step(
+                role="narrator_agent",
+                content="Generated human-readable explanation for operator/planner.",
+                meta={},
+            )
+        )
+
+        return OrchestratorResult(task_id=task_id, answer=answer, steps=steps)

gridgent/tools.py

@@ -0,0 +1,108 @@
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Dict, Any, List
+
+
+@dataclass
+class PowerFlowResult:
+    feeder: str
+    peak_loading_pct: float
+    min_voltage_pu: float
+    max_voltage_pu: float
+    overload_elements: List[str]
+    notes: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "feeder": self.feeder,
+            "peak_loading_pct": round(self.peak_loading_pct, 1),
+            "min_voltage_pu": round(self.min_voltage_pu, 3),
+            "max_voltage_pu": round(self.max_voltage_pu, 3),
+            "overload_elements": self.overload_elements,
+            "notes": self.notes,
+        }
+
+
+def get_feeder_summary(feeder: str) -> Dict[str, Any]:
+    feeder = feeder.upper().strip()
+    data = {
+        "F1": {
+            "name": "Feeder F1 - Downtown Core",
+            "base_kv": 13.8,
+            "num_customers": 4200,
+            "peak_mw": 18.5,
+            "pv_mw": 3.2,
+        },
+        "F2": {
+            "name": "Feeder F2 - Residential West",
+            "base_kv": 13.8,
+            "num_customers": 5100,
+            "peak_mw": 14.3,
+            "pv_mw": 4.7,
+        },
+        "F3": {
+            "name": "Feeder F3 - Industrial Park",
+            "base_kv": 13.8,
+            "num_customers": 830,
+            "peak_mw": 22.1,
+            "pv_mw": 0.8,
+        },
+    }
+    return data.get(
+        feeder,
+        {
+            "name": f"Feeder {feeder} (demo placeholder)",
+            "base_kv": 13.8,
+            "num_customers": 3000,
+            "peak_mw": 10.0,
+            "pv_mw": 1.0,
+        },
+    )
+
+
+def run_power_flow_scenario(
+    feeder: str,
+    added_pv_mw: float = 0.0,
+    added_load_mw: float = 0.0,
+) -> PowerFlowResult:
+    meta = get_feeder_summary(feeder)
+    base_peak = float(meta.get("peak_mw", 10.0))
+    base_pv = float(meta.get("pv_mw", 1.0))
+
+    new_peak = base_peak + added_load_mw - 0.5 * added_pv_mw
+    if new_peak < 0:
+        new_peak = 0.0
+
+    rating_mva = base_peak * 1.2 if base_peak > 0 else 12.0
+    peak_loading_pct = 100.0 * (new_peak / rating_mva)
+
+    min_voltage = 0.97 - 0.01 * (added_load_mw / max(base_peak, 1.0))
+    max_voltage = 1.03 + 0.01 * (added_pv_mw / max(base_pv, 0.5))
+
+    min_voltage = max(min_voltage, 0.9)
+    max_voltage = min(max_voltage, 1.10)
+
+    overload_elements: List[str] = []
+    if peak_loading_pct > 100.0:
+        overload_elements.append("Main transformer overloaded")
+    if peak_loading_pct > 95.0:
+        overload_elements.append("One or more line segments near thermal limit")
+    if min_voltage < 0.95:
+        overload_elements.append("Low voltage at end-of-line customers")
+    if max_voltage > 1.05:
+        overload_elements.append("Risk of over-voltage near PV clusters")
+
+    if overload_elements:
+        notes = "Potential issues detected; further detailed study recommended."
+    else:
+        notes = "Scenario appears within normal operating limits in this simplified model."
+
+    return PowerFlowResult(
+        feeder=feeder,
+        peak_loading_pct=peak_loading_pct,
+        min_voltage_pu=min_voltage,
+        max_voltage_pu=max_voltage,
+        overload_elements=overload_elements,
+        notes=notes,
+    )

gridgent/tools/__init__.py

@@ -0,0 +1 @@
+# package

gridgent/tools/grid_stub.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Dict, Any, List
+from pathlib import Path
+import json
+import csv
+import io
+
+_CONFIG_CACHE: Dict[str, Any] | None = None
+_BASE_DIR = Path(__file__).resolve().parents[2]
+
+
+def _default_feeder_config() -> Dict[str, Any]:
+    return {
+        "feeders": {
+            "F1": {
+                "name": "Feeder F1 - Downtown Core",
+                "base_kv": 13.8,
+                "num_customers": 4200,
+                "peak_mw": 18.5,
+                "pv_mw": 3.2,
+            },
+            "F2": {
+                "name": "Feeder F2 - Residential West",
+                "base_kv": 13.8,
+                "num_customers": 5100,
+                "peak_mw": 14.3,
+                "pv_mw": 4.7,
+            },
+            "F3": {
+                "name": "Feeder F3 - Industrial Park",
+                "base_kv": 13.8,
+                "num_customers": 830,
+                "peak_mw": 22.1,
+                "pv_mw": 0.8,
+            },
+        }
+    }
+
+
+def _load_feeder_config() -> Dict[str, Any]:
+    """Load feeder configuration with upload override."""
+    global _CONFIG_CACHE
+    if _CONFIG_CACHE is not None:
+        return _CONFIG_CACHE
+
+    uploaded_path = _BASE_DIR / "config" / "uploaded_feedermodel.json"
+    base_path = _BASE_DIR / "config" / "feeders.json"
+
+    if uploaded_path.exists():
+        try:
+            with uploaded_path.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+            if isinstance(data, dict) and "feeders" in data:
+                _CONFIG_CACHE = data
+                return _CONFIG_CACHE
+        except Exception:
+            pass
+
+    if base_path.exists():
+        try:
+            with base_path.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+            if isinstance(data, dict) and "feeders" in data:
+                _CONFIG_CACHE = data
+                return _CONFIG_CACHE
+        except Exception:
+            pass
+
+    _CONFIG_CACHE = _default_feeder_config()
+    return _CONFIG_CACHE
+
+
+def reload_feeder_config() -> None:
+    global _CONFIG_CACHE
+    _CONFIG_CACHE = None
+
+
+def get_feeder_summary(feeder: str) -> Dict[str, Any]:
+    feeder_key = (feeder or "").upper().strip()
+    cfg = _load_feeder_config()
+    feeders = cfg.get("feeders", {})
+    if feeder_key and feeder_key in feeders:
+        return feeders[feeder_key]
+    return {
+        "name": f"Feeder {feeder_key or 'F?'} (demo placeholder)",
+        "base_kv": 13.8,
+        "num_customers": 3000,
+        "peak_mw": 10.0,
+        "pv_mw": 1.0,
+    }
+
+
+def get_all_feeders() -> Dict[str, Dict[str, Any]]:
+    cfg = _load_feeder_config()
+    feeders = cfg.get("feeders", {})
+    out: Dict[str, Dict[str, Any]] = {}
+    for k, v in feeders.items():
+        out[str(k).upper()] = v
+    return out
+
+
+@dataclass
+class PowerFlowResult:
+    feeder: str
+    peak_loading_pct: float
+    min_voltage_pu: float
+    max_voltage_pu: float
+    overload_elements: List[str]
+    notes: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "feeder": self.feeder,
+            "peak_loading_pct": round(self.peak_loading_pct, 1),
+            "min_voltage_pu": round(self.min_voltage_pu, 3),
+            "max_voltage_pu": round(self.max_voltage_pu, 3),
+            "overload_elements": self.overload_elements,
+            "notes": self.notes,
+        }
+
+
+def run_power_flow_scenario(
+    feeder: str,
+    added_pv_mw: float = 0.0,
+    added_load_mw: float = 0.0,
+) -> PowerFlowResult:
+    meta = get_feeder_summary(feeder)
+    base_peak = float(meta.get("peak_mw", 10.0))
+    base_pv = float(meta.get("pv_mw", 1.0))
+
+    new_peak = base_peak + added_load_mw - 0.5 * added_pv_mw
+    if new_peak < 0:
+        new_peak = 0.0
+
+    rating_mva = base_peak * 1.2 if base_peak > 0 else 12.0
+    peak_loading_pct = 100.0 * (new_peak / rating_mva) if rating_mva > 0 else 0.0
+
+    min_voltage = 0.97 - 0.01 * (added_load_mw / max(base_peak, 1.0))
+    max_voltage = 1.03 + 0.01 * (added_pv_mw / max(base_pv, 0.5))
+
+    min_voltage = max(min_voltage, 0.9)
+    max_voltage = min(max_voltage, 1.10)
+
+    overload_elements: List[str] = []
+    if peak_loading_pct > 100.0:
+        overload_elements.append("Main transformer overloaded (demo flag)")
+    if peak_loading_pct > 95.0:
+        overload_elements.append("Line segments near thermal limit (demo flag)")
+    if min_voltage < 0.95:
+        overload_elements.append("Low voltage at end-of-line customers (demo flag)")
+    if max_voltage > 1.05:
+        overload_elements.append("Risk of over-voltage near PV clusters (demo flag)")
+
+    if overload_elements:
+        notes = "Potential issues detected; a detailed engineering study is recommended."
+    else:
+        notes = "Scenario appears within normal operating limits in this simplified model."
+
+    return PowerFlowResult(
+        feeder=(feeder or "").upper().strip() or "F?",
+        peak_loading_pct=peak_loading_pct,
+        min_voltage_pu=min_voltage,
+        max_voltage_pu=max_voltage,
+        overload_elements=overload_elements,
+        notes=notes,
+    )
+
+
+def parse_uploaded_grid(raw: str, fmt: str) -> Dict[str, Any]:
+    fmt = (fmt or "").lower().strip()
+    if fmt not in {"json", "csv"}:
+        raise ValueError("Unsupported format; expected 'json' or 'csv'.")
+
+    if fmt == "json":
+        try:
+            data = json.loads(raw)
+        except Exception as exc:
+            raise ValueError(f"Invalid JSON: {exc}") from exc
+
+        if isinstance(data, dict) and "feeders" in data and isinstance(data["feeders"], dict):
+            feeders_in = data["feeders"]
+        elif isinstance(data, list):
+            feeders_in = {}
+            for row in data:
+                if not isinstance(row, dict):
+                    raise ValueError("JSON list must contain objects with feeder fields.")
+                fid = row.get("feeder_id") or row.get("id") or row.get("name")
+                if not fid:
+                    raise ValueError("Each feeder row must contain a 'feeder_id' or 'id' or 'name'.")
+                feeders_in[str(fid).upper()] = {
+                    "name": row.get("name", str(fid)),
+                    "base_kv": float(row.get("base_kv", 13.8)),
+                    "num_customers": int(row.get("num_customers", 1000)),
+                    "peak_mw": float(row.get("peak_mw", 10.0)),
+                    "pv_mw": float(row.get("pv_mw", 1.0)),
+                }
+        else:
+            raise ValueError("JSON must be an object with 'feeders' or a list of feeders.")
+
+        feeders_out: Dict[str, Any] = {}
+        for k, v in feeders_in.items():
+            fid = str(k).upper()
+            if not isinstance(v, dict):
+                raise ValueError("Each feeder entry must be an object.")
+            feeders_out[fid] = {
+                "name": v.get("name", fid),
+                "base_kv": float(v.get("base_kv", 13.8)),
+                "num_customers": int(v.get("num_customers", 1000)),
+                "peak_mw": float(v.get("peak_mw", 10.0)),
+                "pv_mw": float(v.get("pv_mw", 1.0)),
+            }
+        if not feeders_out:
+            raise ValueError("No feeders found in uploaded JSON.")
+        return {"feeders": feeders_out}
+
+    # CSV
+    f = io.StringIO(raw)
+    reader = csv.DictReader(f)
+    required = ["feeder_id", "name", "base_kv", "num_customers", "peak_mw", "pv_mw"]
+    if reader.fieldnames is None:
+        raise ValueError("CSV appears to have no header.")
+    for r in required:
+        if r not in reader.fieldnames:
+            raise ValueError(f"CSV missing required column '{r}'")
+
+    feeders_out: Dict[str, Any] = {}
+    for row in reader:
+        fid = row.get("feeder_id")
+        if not fid:
+            raise ValueError("CSV row missing feeder_id.")
+        fid_u = str(fid).upper()
+        feeders_out[fid_u] = {
+            "name": row.get("name") or fid_u,
+            "base_kv": float(row.get("base_kv") or 13.8),
+            "num_customers": int(row.get("num_customers") or 1000),
+            "peak_mw": float(row.get("peak_mw") or 10.0),
+            "pv_mw": float(row.get("pv_mw") or 1.0),
+        }
+
+    if not feeders_out:
+        raise ValueError("No feeders found in uploaded CSV.")
+    return {"feeders": feeders_out}
+
+
+def save_uploaded_grid(config: Dict[str, Any]) -> None:
+    if not isinstance(config, dict) or "feeders" not in config:
+        raise ValueError("Uploaded config must be a dict with 'feeders'.")
+    path = _BASE_DIR / "config" / "uploaded_feedermodel.json"
+    path.write_text(json.dumps(config, indent=2), encoding="utf-8")
+    reload_feeder_config()

main.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+import os
+from app.server import run_server
+
+if __name__ == "__main__":
+    port_str = os.environ.get("GRID_GENT_PORT", "8000")
+    try:
+        port = int(port_str)
+    except ValueError:
+        port = 8000
+    run_server(port=port)

templates/index.html

@@ -0,0 +1,209 @@
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <title>Grid-Gent Demo</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+        :root {
+            font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+            background-color: #0f172a;
+            color: #e5e7eb;
+        }
+        body { margin: 0; padding: 0; }
+        .page { max-width: 960px; margin: 0 auto; padding: 24px 16px 48px; }
+        .card {
+            background: #020617;
+            border-radius: 16px;
+            padding: 20px;
+            box-shadow: 0 18px 40px rgba(15,23,42,0.8);
+            border: 1px solid rgba(148, 163, 184, 0.2);
+        }
+        h1 { font-size: 1.8rem; margin-bottom: 0.25rem; }
+        h2 { font-size: 1.1rem; margin: 0; color: #9ca3af; }
+        textarea {
+            width: 100%;
+            min-height: 90px;
+            padding: 10px 12px;
+            border-radius: 10px;
+            border: 1px solid #4b5563;
+            background: #020617;
+            color: #e5e7eb;
+            resize: vertical;
+            font-family: inherit;
+            font-size: 0.95rem;
+        }
+        textarea:focus {
+            outline: none;
+            border-color: #38bdf8;
+            box-shadow: 0 0 0 1px #0ea5e9;
+        }
+        button {
+            margin-top: 10px;
+            padding: 9px 16px;
+            border-radius: 999px;
+            border: none;
+            background: linear-gradient(135deg, #0ea5e9, #22c55e);
+            color: white;
+            font-weight: 600;
+            cursor: pointer;
+            font-size: 0.95rem;
+            display: inline-flex;
+            align-items: center;
+            gap: 6px;
+        }
+        button:disabled { opacity: 0.5; cursor: not-allowed; }
+        .answer {
+            margin-top: 18px;
+            white-space: pre-wrap;
+            background: #020617;
+            border-radius: 10px;
+            padding: 12px 14px;
+            border: 1px solid #4b5563;
+            font-size: 0.9rem;
+        }
+        .steps { margin-top: 16px; font-size: 0.8rem; }
+        .step {
+            padding: 8px 10px;
+            border-radius: 8px;
+            border: 1px solid rgba(75,85,99,0.7);
+            background: rgba(15,23,42,0.8);
+            margin-bottom: 6px;
+        }
+        .step strong { color: #a5b4fc; }
+        .badge {
+            display: inline-block;
+            padding: 2px 7px;
+            border-radius: 999px;
+            font-size: 0.7rem;
+            background: rgba(15,118,110,0.3);
+            color: #a7f3d0;
+            margin-left: 6px;
+        }
+        .header-row {
+            display: flex;
+            justify-content: space-between;
+            align-items: baseline;
+            gap: 12px;
+            flex-wrap: wrap;
+        }
+        .pill {
+            font-size: 0.75rem;
+            padding: 4px 10px;
+            border-radius: 999px;
+            border: 1px solid rgba(148,163,184,0.5);
+            color: #e5e7eb;
+        }
+        .examples {
+            margin-top: 10px;
+            font-size: 0.8rem;
+            color: #9ca3af;
+        }
+        .examples code {
+            background: rgba(15,23,42,0.8);
+            padding: 2px 6px;
+            border-radius: 6px;
+            font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+        }
+    </style>
+</head>
+<body>
+    <div class="page">
+        <div class="card">
+            <div class="header-row">
+                <div>
+                    <h1>Grid-Gent Demo</h1>
+                    <h2>Agentic assistant for city distribution grid scenarios (simplified)</h2>
+                </div>
+                <div class="pill">Offline demo · no real grid connection</div>
+            </div>
+
+            <div style="margin-top:18px;">
+                <label for="query">Describe a grid scenario or question:</label>
+                <textarea id="query" placeholder="Example: What happens on feeder F2 if we add 5 MW of rooftop PV?"></textarea>
+                <button id="ask-btn" onclick="sendQuery()">
+                    <span id="btn-label">Run Grid-Gent</span>
+                    <span id="btn-spinner" style="display:none;">⏳</span>
+                </button>
+            </div>
+
+            <div class="examples">
+                Try things like:
+                <div><code>What happens on feeder F2 if we add 5 MW of rooftop PV?</code></div>
+                <div><code>Simulate adding 3 MW of load on feeder F1.</code></div>
+            </div>
+
+            <div id="answer" class="answer" style="display:none;"></div>
+            <div id="steps" class="steps" style="display:none;"></div>
+        </div>
+    </div>
+
+    <script>
+        async function sendQuery() {
+            const textarea = document.getElementById("query");
+            const btn = document.getElementById("ask-btn");
+            const label = document.getElementById("btn-label");
+            const spinner = document.getElementById("btn-spinner");
+            const answerEl = document.getElementById("answer");
+            const stepsEl = document.getElementById("steps");
+
+            const query = textarea.value.trim();
+            if (!query) {
+                alert("Please enter a scenario or question.");
+                return;
+            }
+
+            btn.disabled = true;
+            spinner.style.display = "inline-block";
+            label.textContent = "Running...";
+
+            try {
+                const resp = await fetch("/api/ask", {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ query })
+                });
+                const data = await resp.json();
+
+                if (!resp.ok) {
+                    answerEl.style.display = "block";
+                    stepsEl.style.display = "none";
+                    answerEl.textContent = "Error: " + (data.error || resp.statusText);
+                    return;
+                }
+
+                answerEl.style.display = "block";
+                answerEl.textContent = data.answer || "(No answer returned)";
+
+                stepsEl.innerHTML = "";
+                if (Array.isArray(data.steps)) {
+                    stepsEl.style.display = "block";
+                    data.steps.forEach(step => {
+                        const div = document.createElement("div");
+                        div.className = "step";
+                        const role = step.role || "agent";
+                        const metaIntent = step.meta && step.meta.intent ? step.meta.intent : "";
+                        const metaFeeder = step.meta && step.meta.feeder ? step.meta.feeder : "";
+                        const badgeText = metaIntent || metaFeeder;
+                        div.innerHTML = "<strong>" + role + "</strong>" +
+                            (badgeText ? "<span class=\"badge\">" + badgeText + "</span>" : "") +
+                            "<div>" + step.content + "</div>";
+                        stepsEl.appendChild(div);
+                    });
+                } else {
+                    stepsEl.style.display = "none";
+                }
+            } catch (err) {
+                answerEl.style.display = "block";
+                stepsEl.style.display = "none";
+                answerEl.textContent = "Request failed: " + err;
+            } finally {
+                btn.disabled = false;
+                spinner.style.display = "none";
+                label.textContent = "Run Grid-Gent";
+            }
+        }
+    </script>
+</body>
+</html>

tests/test_http_api.py

@@ -0,0 +1,57 @@
+import unittest
+import threading
+import time
+import json
+import urllib.request
+
+from app.server import run_server
+
+
+class TestHTTPAPI(unittest.TestCase):
+    _server_started = False
+
+    @classmethod
+    def setUpClass(cls):
+        if not cls._server_started:
+            t = threading.Thread(target=run_server, kwargs={"host": "127.0.0.1", "port": 8765}, daemon=True)
+            t.start()
+            time.sleep(1.0)
+            cls._server_started = True
+
+    def test_api_ask(self):
+        body = json.dumps({"query": "Simulate adding 3 MW of load on feeder F1"}).encode("utf-8")
+        req = urllib.request.Request(
+            "http://127.0.0.1:8765/api/ask",
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            self.assertEqual(resp.status, 200)
+            data = json.loads(resp.read().decode("utf-8"))
+            self.assertIn("answer", data)
+            self.assertIn("steps", data)
+            self.assertIsInstance(data["steps"], list)
+
+    def test_api_upload_grid(self):
+        payload = {
+            "raw": "feeder_id,name,base_kv,num_customers,peak_mw,pv_mw\n"
+                   "U1,Feeder U1,13.8,100,7.0,1.0\n",
+            "format": "csv",
+        }
+        body = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            "http://127.0.0.1:8765/api/upload-grid",
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            self.assertEqual(resp.status, 200)
+            data = json.loads(resp.read().decode("utf-8"))
+            self.assertEqual(data["status"], "ok")
+            self.assertIn("U1", data["feeders_loaded"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_intent_agent.py

@@ -0,0 +1,26 @@
+import unittest
+from gridgent.agents.intent import IntentAgent
+
+
+class TestIntentAgent(unittest.TestCase):
+    def setUp(self):
+        self.agent = IntentAgent()
+
+    def test_hosting_capacity_intent(self):
+        info = self.agent.classify("What happens on feeder F2 if we add 5 MW of rooftop PV?")
+        self.assertEqual(info["intent"], "hosting_capacity")
+        self.assertEqual(info["feeder"], "F2")
+        self.assertAlmostEqual(info["added_pv_mw"], 5.0, places=3)
+
+    def test_simulation_intent_load_growth(self):
+        info = self.agent.classify("Simulate load growth of 3 MW on feeder F1")
+        self.assertEqual(info["intent"], "simulation")
+        self.assertAlmostEqual(info["added_load_mw"], 3.0, places=3)
+
+    def test_unknown_for_smalltalk(self):
+        info = self.agent.classify("hi")
+        self.assertEqual(info["intent"], "unknown")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_orchestrator.py

@@ -0,0 +1,24 @@
+import unittest
+from gridgent.core.orchestrator import GridGentOrchestrator
+
+
+class TestOrchestrator(unittest.TestCase):
+    def setUp(self):
+        self.orch = GridGentOrchestrator()
+
+    def test_run_basic_query(self):
+        result = self.orch.run("What happens on feeder F2 if we add 5 MW of rooftop PV?")
+        self.assertTrue(result.task_id)
+        self.assertIn("You asked:", result.answer)
+        roles = [s.role for s in result.steps]
+        self.assertEqual(roles[0], "intent_agent")
+        self.assertIn("planning_agent", roles)
+        self.assertIn("narrator_agent", roles)
+
+    def test_run_unknown_query(self):
+        result = self.orch.run("hi")
+        self.assertIn("didn't see enough detail", result.answer.lower())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tools.py

@@ -0,0 +1,68 @@
+import unittest
+from gridgent.tools.grid_stub import (
+    run_power_flow_scenario,
+    get_feeder_summary,
+    parse_uploaded_grid,
+    save_uploaded_grid,
+    reload_feeder_config,
+    get_all_feeders,
+)
+from pathlib import Path
+import json
+
+
+class TestTools(unittest.TestCase):
+    def test_feeder_summary_exists(self):
+        meta = get_feeder_summary("F1")
+        self.assertIn("peak_mw", meta)
+        self.assertGreater(meta["peak_mw"], 0)
+
+    def test_power_flow_baseline(self):
+        result = run_power_flow_scenario("F1", added_pv_mw=0.0, added_load_mw=0.0)
+        self.assertIsInstance(result.peak_loading_pct, float)
+        self.assertGreater(result.peak_loading_pct, 0)
+        self.assertGreaterEqual(result.min_voltage_pu, 0.9)
+        self.assertLessEqual(result.max_voltage_pu, 1.1)
+
+    def test_power_flow_high_load_flags_issue(self):
+        result = run_power_flow_scenario("F1", added_pv_mw=0.0, added_load_mw=20.0)
+        self.assertTrue(any("overloaded" in x.lower() for x in result.overload_elements))
+
+    def test_parse_uploaded_json(self):
+        raw = json.dumps({
+            "feeders": {
+                "X1": {"name": "Custom Feeder", "base_kv": 11.0, "num_customers": 100, "peak_mw": 5.0, "pv_mw": 0.5}
+            }
+        })
+        cfg = parse_uploaded_grid(raw, "json")
+        self.assertIn("feeders", cfg)
+        self.assertIn("X1", cfg["feeders"])
+
+    def test_parse_uploaded_csv(self):
+        raw = "feeder_id,name,base_kv,num_customers,peak_mw,pv_mw\n"               "Y1,Feeder Y1,13.8,200,8.0,1.2\n"
+        cfg = parse_uploaded_grid(raw, "csv")
+        self.assertIn("Y1", cfg["feeders"])
+
+    def test_save_uploaded_overrides(self):
+        raw = json.dumps({
+            "feeders": {
+                "Z1": {"name": "Uploaded Feeder Z1", "base_kv": 13.8, "num_customers": 999, "peak_mw": 50.0, "pv_mw": 5.0}
+            }
+        })
+        cfg = parse_uploaded_grid(raw, "json")
+        save_uploaded_grid(cfg)
+        reload_feeder_config()
+        feeders = get_all_feeders()
+        self.assertIn("Z1", feeders)
+        meta = get_feeder_summary("Z1")
+        self.assertEqual(meta["peak_mw"], 50.0)
+        # Clean up uploaded file
+        base_dir = Path(__file__).resolve().parents[1]
+        up = base_dir / "config" / "uploaded_feedermodel.json"
+        if up.exists():
+            up.unlink()
+        reload_feeder_config()
+
+
+if __name__ == "__main__":
+    unittest.main()