https://github.com/vero-code/spatial-optician
AI-powered facility lighting audit and ROI optimization platform. Powered by Gemini 3.5, Google ADK, MCP & MongoDB. Supported by MongoDB for Startups.
https://github.com/vero-code/spatial-optician
artificial-intelligence energy-efficiency-startup fastapi gemini google-adk lighting-audit mcp-server model-context-protocol mongodb react typescript
Last synced: 9 days ago
JSON representation
AI-powered facility lighting audit and ROI optimization platform. Powered by Gemini 3.5, Google ADK, MCP & MongoDB. Supported by MongoDB for Startups.
- Host: GitHub
- URL: https://github.com/vero-code/spatial-optician
- Owner: vero-code
- License: mit
- Created: 2026-05-23T19:13:26.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-06-09T08:28:04.000Z (20 days ago)
- Last Synced: 2026-06-09T09:12:08.152Z (20 days ago)
- Topics: artificial-intelligence, energy-efficiency-startup, fastapi, gemini, google-adk, lighting-audit, mcp-server, model-context-protocol, mongodb, react, typescript
- Language: TypeScript
- Homepage: https://devpost.com/software/spatial-optician
- Size: 451 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Spatial Optician
[](https://www.mongodb.com/startups)
[](https://www.mongodb.com/)
[](https://react.dev/)
[](https://fastapi.tiangolo.com/)
[](https://www.typescriptlang.org/)
[](https://www.python.org/)
[](https://deepmind.google/technologies/gemini/)
**Spatial Optician** is an intelligent analytical platform designed for performing energy-efficient facility lighting audits, calculating retrofitting Return on Investment (ROI), and conducting automated fixture selection. Supported by the **MongoDB for Startups** program, the system leverages high-performance cloud databases and a custom Model Context Protocol (MCP) gateway to deliver real-time, data-driven recommendations powered by an AI Agent (Gemini 3.5 Flash) integrated via **Google ADK (Agent Development Kit)**.
The user interface is uniquely styled as an interactive engineering blueprint workspace, catering to facility managers and optics engineers alike.
## 🏛️ Project Architecture
A comprehensive breakdown of components, databases, data structures, and multi-agent interaction flows can be found in the:
👉 **[ARCHITECTURE.md](./ARCHITECTURE.md)**
> [!TIP]
> **Key Showcase: Agentic Self-Healing Catalog Expansion**
> If a requested lighting fixture is missing from the database, our Gemini agent dynamically triggers a live web search (via the `GoogleSearchTool`), extracts the precise engineering specifications, and uses the custom MCP `insert_document` tool to **dynamically write the new fixture back into the MongoDB database**, completing the ROI calculations on the fly!
## 🚀 Quick Start Guide
### 1. Database Configuration (MongoDB)
Ensure you have a running MongoDB database or provide your connection string using the `MONGODB_URI` environment variable inside your backend configuration.
### 2. Backend (FastAPI Server)
Navigate to the `backend` folder and run the following commands:
```bash
cd backend
# Synchronize environment and install dependencies
uv sync
# Start the development server
uv run fastapi dev main.py
```
Alternatively, launch using the PowerShell utility script:
```powershell
.\run.ps1
```
### 3. Frontend (React + Vite)
Navigate to the `frontend` folder and launch the local development environment:
```bash
cd frontend
npm install
npm run dev
```
### 4. MongoDB MCP Server
If you need to run the Model Context Protocol database gateway locally:
```bash
cd mcp-mongo
npm install
npm run build
npm start
```
*Note: In production, the backend is configured to connect to the deployed SSE MCP endpoint at `https://spatial-optician-mcp-601334765015.europe-west1.run.app/sse`.*
## 🛠️ Technology Stack
* **Frontend**: React 19, Vite, TypeScript, Tailwind CSS v4, Motion, Lucide Icons.
* **Backend**: Python, FastAPI, PyMongo, Pydantic, Google ADK (Agent Development Kit).
* **MCP Server**: Node.js, Express, TypeScript, Model Context Protocol SDK, MongoDB Driver.
## 🆕 Recent Updates
* **Backend Modularization & Refactoring**: Reorganized the backend code from a monolithic `main.py` into a highly decoupled, modular structure:
* `config.py` — Centralized environment variables (`GEMINI_MODEL`, `MONGODB_URI`, etc.).
* `prompts.py` Isolated AI agent and Vision prompt constants.
* `schemas.py` — Organized Pydantic request and response data models.
* `database.py` — Managed MongoDB client setup.
* `agent.py` — Constructed Google ADK agents and lifecycle hooks.
* **Dashboard Streamlining & Live MCP Controls**: Removed the external floating chat window and replaced it with a dedicated **"Optical Analysis Output"** tabbed console directly in the dashboard's center console. Below this console, a new panel of **live MCP actions** was added to interact with MongoDB:
* **🔍 Find Fixtures** — Directs the Gemini agent to query the `equipment_catalog` collection in the database via MCP and recommend suitable fixture models based on the scan description.
* **⚡ Calculate ROI** — Triggers the agent to fetch electricity rates from `energy_tariffs` and calculate estimated power draw reduction, financial savings, and the exact payback period (ROI).
* **💾 Save Audit** — Invokes the `insert_document` MCP tool to save the new spatial audit findings into the `audit_history` collection, returning the resulting MongoDB insertion ID.
* **Dynamic Auditing & UI Polish (June 9, 2026)**:
* **Multi-Facility Profiling**: Added dynamic space classification supporting warehouses (`NY-HUD-01`), residential spaces (`NY-LIV-01`), and commercial offices (`NY-OFF-01`) live via Gemini Vision.
* **Dynamic Parameter Estimation**: Replaced hardcoded audit sizes. The AI agent dynamically calculates and saves the appropriate facility dimensions, ceiling heights, lux levels, and timestamps.
* **Zero Fallbacks**: Removed silent fallback mocks from the API to guarantee live, authentic Gemini Vision diagnostics and explicit error reporting.
* **Polished Save Notification**: Redesigned the MongoDB response panel with a blueprint-style border, real-time `insertedId` display, and an expandable `[+] View System Report` toggle that renders the AI's registration report in rich markdown.