Spatial Optician
vero-code/spatial-optician
Auditoria inteligente de iluminação com IA e cálculo de ROI em tempo real
Ver no GitHubPlataforma de auditoria de iluminação em instalações com cálculo automático de ROI para retrofit. Integra Gemini 3.5 Flash, MongoDB e um MCP server customizado para gerar recomendações de fixtures otimizadas energeticamente. O agente IA é capaz de realizar buscas web dinâmicas e expandir o catálogo de produtos automaticamente.
Instalação
npx convez-ai vero-code/spatial-optician1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Análise de eficiência energética em edifícios comerciais
- Cálculo de retorno de investimento para retrofit de iluminação
- Seleção automática de fixtures de iluminação otimizadas
- Catalogação dinâmica de produtos com extração de specs via IA
Veredito

MCP server bem arquitetado que combina análise de dados com agência de IA. A capacidade de auto-healing do catálogo (busca web dinâmica + inserção MongoDB) é um diferencial técnico legítimo, embora o foco principal seja analytics para decisões de retrofit. Ideal para gerentes de facilities que precisam de recomendações data-driven.
README
A tradução para o português deste README ainda está na fila.
Spatial Optician
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
[!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 MCPinsert_documenttool 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:
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:
.\run.ps1
3. Frontend (React + Vite)
Navigate to the frontend folder and launch the local development environment:
cd frontend
npm install
npm run dev
4. MongoDB MCP Server
If you need to run the Model Context Protocol database gateway locally:
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.pyinto a highly decoupled, modular structure:config.py— Centralized environment variables (GEMINI_MODEL,MONGODB_URI, etc.).prompts.pyIsolated 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_catalogcollection 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_tariffsand calculate estimated power draw reduction, financial savings, and the exact payback period (ROI). - 💾 Save Audit — Invokes the
insert_documentMCP tool to save the new spatial audit findings into theaudit_historycollection, returning the resulting MongoDB insertion ID.
- 🔍 Find Fixtures — Directs the Gemini agent to query the
- 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
insertedIddisplay, and an expandable[+] View System Reporttoggle that renders the AI's registration report in rich markdown.
- Multi-Facility Profiling: Added dynamic space classification supporting warehouses (