{"id":50994650,"url":"https://github.com/vero-code/spatial-optician","last_synced_at":"2026-06-20T07:31:55.708Z","repository":{"id":360768421,"uuid":"1247779795","full_name":"vero-code/spatial-optician","owner":"vero-code","description":"AI-powered facility lighting audit and ROI optimization platform. Powered by Gemini 3.5, Google ADK, MCP \u0026 MongoDB. Supported by MongoDB for Startups.","archived":false,"fork":false,"pushed_at":"2026-06-09T08:28:04.000Z","size":462,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-09T09:12:08.152Z","etag":null,"topics":["artificial-intelligence","energy-efficiency-startup","fastapi","gemini","google-adk","lighting-audit","mcp-server","model-context-protocol","mongodb","react","typescript"],"latest_commit_sha":null,"homepage":"https://devpost.com/software/spatial-optician","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vero-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T19:13:26.000Z","updated_at":"2026-06-09T08:28:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vero-code/spatial-optician","commit_stats":null,"previous_names":["vero-code/spatial-optician"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vero-code/spatial-optician","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-code%2Fspatial-optician","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-code%2Fspatial-optician/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-code%2Fspatial-optician/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-code%2Fspatial-optician/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vero-code","download_url":"https://codeload.github.com/vero-code/spatial-optician/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-code%2Fspatial-optician/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34561766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","energy-efficiency-startup","fastapi","gemini","google-adk","lighting-audit","mcp-server","model-context-protocol","mongodb","react","typescript"],"created_at":"2026-06-20T07:31:55.610Z","updated_at":"2026-06-20T07:31:55.703Z","avatar_url":"https://github.com/vero-code.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spatial Optician\n\n[![MongoDB for Startups](https://img.shields.io/badge/MongoDB_for_Startups-Supported-emerald?style=for-the-badge\u0026logo=mongodb\u0026logoColor=white)](https://www.mongodb.com/startups)\n[![MongoDB](https://img.shields.io/badge/MongoDB-%234ea94b.svg?style=for-the-badge\u0026logo=mongodb\u0026logoColor=white)](https://www.mongodb.com/)\n[![React 19](https://img.shields.io/badge/React%2019-%2320232a.svg?style=for-the-badge\u0026logo=react\u0026logoColor=%2361DAFB)](https://react.dev/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-%23009688.svg?style=for-the-badge\u0026logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-%23007acc.svg?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Python](https://img.shields.io/badge/Python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)](https://www.python.org/)\n[![Gemini](https://img.shields.io/badge/Gemini%203.5%20Flash-121011?style=for-the-badge\u0026logo=google-gemini\u0026logoColor=white)](https://deepmind.google/technologies/gemini/)\n\n**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)**.\n\nThe user interface is uniquely styled as an interactive engineering blueprint workspace, catering to facility managers and optics engineers alike.\n\n## 🏛️ Project Architecture\n\nA comprehensive breakdown of components, databases, data structures, and multi-agent interaction flows can be found in the:\n👉 **[ARCHITECTURE.md](./ARCHITECTURE.md)**\n\n\u003e [!TIP]\n\u003e **Key Showcase: Agentic Self-Healing Catalog Expansion**\n\u003e 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!\n\n## 🚀 Quick Start Guide\n\n### 1. Database Configuration (MongoDB)\nEnsure you have a running MongoDB database or provide your connection string using the `MONGODB_URI` environment variable inside your backend configuration.\n\n### 2. Backend (FastAPI Server)\nNavigate to the `backend` folder and run the following commands:\n```bash\ncd backend\n# Synchronize environment and install dependencies\nuv sync\n# Start the development server\nuv run fastapi dev main.py\n```\nAlternatively, launch using the PowerShell utility script:\n```powershell\n.\\run.ps1\n```\n\n### 3. Frontend (React + Vite)\nNavigate to the `frontend` folder and launch the local development environment:\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\n### 4. MongoDB MCP Server\nIf you need to run the Model Context Protocol database gateway locally:\n```bash\ncd mcp-mongo\nnpm install\nnpm run build\nnpm start\n```\n*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`.*\n\n## 🛠️ Technology Stack\n* **Frontend**: React 19, Vite, TypeScript, Tailwind CSS v4, Motion, Lucide Icons.\n* **Backend**: Python, FastAPI, PyMongo, Pydantic, Google ADK (Agent Development Kit).\n* **MCP Server**: Node.js, Express, TypeScript, Model Context Protocol SDK, MongoDB Driver.\n\n## 🆕 Recent Updates\n\n* **Backend Modularization \u0026 Refactoring**: Reorganized the backend code from a monolithic `main.py` into a highly decoupled, modular structure:\n  * `config.py` — Centralized environment variables (`GEMINI_MODEL`, `MONGODB_URI`, etc.).\n  * `prompts.py` Isolated AI agent and Vision prompt constants.\n  * `schemas.py` — Organized Pydantic request and response data models.\n  * `database.py` — Managed MongoDB client setup.\n  * `agent.py` — Constructed Google ADK agents and lifecycle hooks.\n* **Dashboard Streamlining \u0026 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:\n  * **🔍 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.\n  * **⚡ 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).\n  * **💾 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.\n* **Dynamic Auditing \u0026 UI Polish (June 9, 2026)**:\n  * **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.\n  * **Dynamic Parameter Estimation**: Replaced hardcoded audit sizes. The AI agent dynamically calculates and saves the appropriate facility dimensions, ceiling heights, lux levels, and timestamps.\n  * **Zero Fallbacks**: Removed silent fallback mocks from the API to guarantee live, authentic Gemini Vision diagnostics and explicit error reporting.\n  * **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.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvero-code%2Fspatial-optician","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvero-code%2Fspatial-optician","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvero-code%2Fspatial-optician/lists"}