$ show odysseus-dev/odysseus
Odysseus is a self-hosted, full-stack AI assistant platform built with FastAPI (Python) and vanilla JavaScript. It provides a unified workspace for chat with multiple LLM providers (OpenAI, Anthropic, Ollama, local models), deep research with multi-step web analysis, RAG-based memory and document indexing, email/calendar/contacts management via IMAP/CalDAV/CardDAV, an image editor with layers and AI tools, task scheduling, web search, and MCP (Model Context Protocol) server integration. The architecture follows a modular route-per-domain pattern with backward-compatibility shims, a shared SQLite database via SQLAlchemy, and ChromaDB for vector storage. The frontend is a single-page application with streaming markdown rendering, live thinking display, and extensive keyboard shortcuts. The system is designed for multi-user operation with owner-scoped data isolation, atomic file writes for state persistence, and comprehensive security measures including SSRF protection, prompt injection hardening, and secret encryption. It includes a hardware-fit recommendation engine (cookbook) for selecting optimal LLM inference backends (llama.cpp, vLLM, diffusers) based on local GPU capabilities. While primarily an application, it incorporates significant data engineering patterns: embedding lanes with fallback, search result ranking, memory consolidation with near-duplicate removal, and deep research synthesis pipelines. The codebase demonstrates strong engineering practices with extensive regression testing (over 400 test files), CI/CD pipelines, and security scanning. However, it shows signs of technical drift with duplicate code paths (e.g., search ranking in both `src/search` and `services/search`), heavy monkeypatching in tests, and some legacy migration complexity. The project is actively maintained with frequent commits and issue triage.
The LLM identified 5 files worth highlighting for reuse:
Provides `atomic_write_json` and `atomic_write_text` functions that write to a temporary file, fsync, then atomically replace the target. Used across presets, prefs, API keys, and cookbook state to prevent data corruption from crashes or concurrent writes. The pattern is self-contained and can be extracted into any Python project needing safe file writes.
Implements a generic sliding-window rate limiter keyed by IP address. Uses a deque of timestamps for O(1) cleanup and supports configurable limits and windows. The class is isolated (no internal imports beyond standard library) and can be reused in any FastAPI or asyncio application for request throttling.
Exports pure functions (`snapPoint`, `snapRect`) that compute magnetic snap positions for canvas layers based on proximity to grid lines, layer edges, and center points. No DOM dependencies, fully testable in Node.js. Demonstrates clean separation of geometry logic from UI state.
Implements a multi-factor search result ranking system that adjusts scores based on recency (with configurable half-life), domain authority (hardcoded high-trust domains), and news quality. The ranking logic is parameterized and could be extracted for any search aggregation service. Includes unit tests for edge cases like sports substrings and word boundaries.
Defines an abstract base class `ModelCapabilityReader` with a registry pattern for vendor-specific readers (OpenAI, Google, Ollama, LM Studio, etc.). Each reader implements `get_capabilities()` to report tool call support, vision, audio, etc. The pattern allows adding new providers without modifying core logic and is reusable for any multi-provider LLM system.