O.R.I.O.N

Operador de Redes Inteligentes y Optimización Neural

Asistente de IA personal multimodal, local-first y open source — voz en tiempo real, visión, control del sistema, IoT y biometría. Sin suscripciones, sin cuentas, sin datos en cloud.

---

Tabla de contenidos

• ¿Qué es Orion?
• Capacidades
• Quick Start
• Configuración
• Arquitectura
• Requisitos
• Troubleshooting
• Licencia

---

🧠 ¿Qué es Orion?

Orion es un asistente de IA personal multimodal local-first: corre íntegro en tu propia máquina, persiste tus datos en SQLite local y publica todo su código bajo licencia MIT para que cualquiera pueda auditar, modificar y verificar qué hace el sistema. A diferencia de Alexa, Siri o Google Home — cajas negras que centralizan tus datos en la nube — Orion mantiene la soberanía de los datos del lado del usuario.

A través de diálogo natural, analiza tu pantalla, procesa documentos cargados y ejecuta flujos de trabajo complejos sobre una interfaz web adaptativa servida en local. Integra control del sistema operativo, IoT (ESP32/Arduino), control de acceso biométrico (huella AS608) y un puente con Telegram organizado por topics. Todo bajo tu control, en tu hardware.

Principios de diseño

• Local-first: SQLite, IoT, control de PC, acceso biométrico y memoria funcionan sin conexión a internet. La voz (Gemini Live) y las integraciones Google (Gmail/Classroom/Drive) son opt-in y opcionales.
• Soberanía de datos: nada se persiste en cloud por defecto. Toda la data — conversaciones, notas, sensores, eventos de acceso — vive en data/orion.sqlite en tu disco.
• Open source verificable: licencia MIT, código auditable, sin binarios opacos. Si no confiás en lo que decimos, leelo.
• Extensible: agregar una tool nueva al LLM = un archivo con decorador @tool. Auto-discovery. Integración con MCP (Model Context Protocol) para skills/agents externos.
• Hardware propio: ESP32 + AS608 para biometría, Arduino para IoT. Cero dependencia de devices propietarios (Echo, HomePod, Nest).

---

🚀 Capacidades

Feature	Descripción
🎙️ Voz en tiempo real	Conversación con latencia ultra-baja (Gemini Live)
🖥️ Control del sistema	Lanza apps, gestiona archivos, ejecuta comandos
🧩 Tareas autónomas	Planificación multi-paso con agentes especializados
👁️ Conciencia visual	Procesado de pantalla y webcam en tiempo real
🧠 Memoria persistente	Recuerda proyectos, preferencias y contexto
📬 Bandeja unificada	Gmail · Classroom · Drive (OAuth opcional)
🏠 IoT integrado	Control de dispositivos ESP32/Arduino con CRUD
🛡️ Acceso por huella	ESP32 + AS608 → Telegram con notificación por entrada
📲 Telegram bot	Notificaciones por supergrupo con topics
🔌 Ecosistema MCP	Skills, Agents y Notifications vía Model Context Protocol
📁 Diagnóstico in-app	Panel para ver logs y rutas sin abrir el CMD

---

⚡ Quick Start

Prerrequisitos

• Python 3.11 o 3.12 — py -3 --version
• Node.js LTS (18+) — node --version
• Git

Setup en un solo comando

git clone https://github.com/Zero0889/Orion-AI.git
cd Orion-AI
setup.bat

setup.bat hace:

1. Crear .venv con Python.
2. pip install -r requirements.txt + requirements-dev.txt.
3. cd web && npm install && npm run build.
4. Avisarte qué hacer después.

Arrancar Orion

orion.bat

orion.bat valida prerrequisitos en cada arranque — si falta web/dist/ lo compila, si falta .venv lo crea. No hace falta volver a correr setup.bat salvo que borres algo a mano.

La primera vez aparece un wizard de bienvenida pidiendo tu API key de Gemini. Conseguila gratis en aistudio.google.com/app/apikey.

Frontend con HMR

Si vas a tocar React, corré Vite en paralelo:

REM Terminal 1: backend
python -m orion

REM Terminal 2: frontend con HMR
cd web
npm run dev

Abrí http://localhost:5173. El proxy de Vite redirige /api/* y /ws al backend en :8765.

---

⚙️ Configuración

Modo	Ubicación
Desarrollo	<repo>/config/, <repo>/data/

Forzá otra ubicación con ORION_DATA_HOME=C:\Path.

API key de Gemini (obligatoria)

Tres formas (por prioridad):

1. Pegarla en el wizard de bienvenida (lo más fácil).
2. Env var ORION_GEMINI_KEY — tiene prioridad sobre el archivo.
3. Editar config/api_keys.json a mano:

   { "gemini_api_key": "AIza..." }

Conseguila gratis en aistudio.google.com/app/apikey.

Google OAuth (opcional)

Para Gmail / Classroom / Drive / Calendar / Sheets — setup completo (~5 min) documentado en docs/SETUP_GOOGLE_OAUTH.md.

Variables de entorno

Var	Default	Uso
ORION_GEMINI_KEY	(vacía)	API key de Gemini. Prioridad sobre el archivo.
ORION_DATA_HOME	(auto)	Forzar ruta de config/data.
ORION_PROJECTS_DIR	~/Desktop/OrionProjects	Carpeta del agente Coder.
ORION_UPLOADS_DIR	<repo>/uploads	Drop-zone para uploads.
ORION_GOOGLE_CLIENT_SECRET	(auto)	Path al client_secret.json custom.

---

🏗️ Arquitectura

       ┌────────────────────────────────────────────┐
       │ Backend Python (FastAPI + uvicorn, :8765)  │
       │  ├─ orion/server/    FastAPI app + WS      │
       │  ├─ orion/runtime.py  OrionLive (Gemini)   │
       │  ├─ orion/agent/      planner + executor   │
       │  ├─ orion/adapters/   tools por dominio    │
       │  ├─ orion/domain/     memory + notas       │
       │  └─ orion/storage/    SQLite (WAL)         │
       └───────────┬────────────────────────────────┘
                   │
       ┌───────────▼────────────────────────────────┐
       │ Frontend React (web/, servido por FastAPI) │
       │  ├─ Vite + Tailwind + Zustand + TanStack Q │
       │  ├─ Tipos autogenerados desde OpenAPI      │
       │  └─ Paneles: Chat, IoT, Acceso, MCP, …     │
       └────────────────────────────────────────────┘

Sin Tauri, sin .exe, sin .msi. Orion corre como python -m orion y se abre en el navegador. Si querés acceder desde otros dispositivos (celular, tablet) podés exponerlo vía Tailscale — el toggle "Compartir vía Tailscale" en Ajustes lo hace bindeo seguro a tu tailnet.

Stack principal:

• Backend: Python 3.11+ · FastAPI · uvicorn · WebSocket · structlog
• Frontend: React 18 · TypeScript · Vite · Tailwind · Zustand · TanStack Query
• LLM: Gemini Live (multi-provider vía abstracción)
• Extensiones: MCP (Model Context Protocol) · Skills · Agents
• Hardware: ESP32 (sketches en arduino/) — sensores IoT, control de acceso por huella

---

📋 Requisitos

Requisito	Detalle
SO	Windows 10/11 x64, macOS, o Linux
Python	3.11 o 3.12
Node.js	18+ (para el frontend)
RAM	4 GB mínimo, 8 GB recomendado
Micrófono	Opcional (solo si querés voz)
API Key	Clave gratuita de Gemini

---

🐛 Troubleshooting

"Puerto 8765 ocupado"

Otro proceso de Orion (o cualquier app) está usando el puerto. Cerralo con el Task Manager o cambiá el puerto si tu setup lo permite.

"deleted_client" o "invalid_client" en logs de Gmail/Classroom

El OAuth Client ID que registraste fue borrado/invalidado en Google Cloud Console. Seguí los pasos del paso "Errores comunes" en docs/SETUP_GOOGLE_OAUTH.md.

Quiero ver los logs

• Desde la UI: panel Diagnóstico (sidebar) muestra el tail vivo + botones para abrir la carpeta y copiar al portapapeles.
• Archivo: logs/orion.log en el repo.

Los logs rotan cada 5 MB con 3 archivos de backup.

"npm run build" falla con error de memoria

Node 18 a veces se queda corto con vendor-react + vendor-katex. Probá:

set NODE_OPTIONS=--max-old-space-size=4096
cd web && npm run build

---

📄 Licencia

Orion se distribuye bajo licencia MIT.

Esto significa que tenés libertad total para:

• Usar Orion para cualquier propósito (personal, académico, comercial).
• Modificar el código y adaptarlo a tus necesidades.
• Redistribuir copias originales o modificadas.
• Sublicenciar o integrarlo en otros proyectos.

La única condición es mantener el aviso de copyright y el texto de la licencia en las copias o porciones sustanciales del software.

El código es auditable y verificable: cualquier afirmación que hagamos sobre el comportamiento del sistema (por ejemplo, "tus datos no salen de tu máquina") puede ser comprobada leyendo el código fuente. Esa es la diferencia esencial frente a asistentes propietarios.

---

👤 Créditos

Desarrollado como un asistente de IA personal de nueva generación.

Tecnologías: Gemini Live · FastAPI · Vite · React · Tailwind