mirror of
https://github.com/pewdiepie-archdaemon/odysseus.git
synced 2026-10-23 23:32:22 +02:00
docs(discovery): publish provisional feature baseline
This commit is contained in:
Alexandre Teixeira
@@ -0,0 +1,153 @@
|
||||
# Agent
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## AGENT-001 — Autonomous Agent Loop & Tool Execution Engine
|
||||
|
||||
- **Domain**: `agent`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Executes multi-step agent reasoning loops, tool invocation parsing, and automated response generation.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/agent_loop.py` — `run_agent_loop` — Core loop evaluating model tool requests and executing handlers.
|
||||
- `src/tool_execution.py` — `execute_tool_call` — Dispatches tool invocation requests to underlying tool handlers.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Infinite tool loop if termination condition fails.
|
||||
|
||||
## AGENT-002 — Scheduled Tasks & Event Bus Dispatcher
|
||||
|
||||
- **Domain**: `agent`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Schedules background recurring or delayed tasks, emits event bus triggers, and executes automated flows.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/task_routes.py` — `@router.get('')` — Fetches active scheduled tasks.
|
||||
- `src/task_scheduler.py` — `TaskScheduler` — Async task scheduler dispatching cron and delay triggers.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Task execution failure handling on system restart.
|
||||
|
||||
## AGENT-003 — Webhook Event Subscriptions & Trigger Processing
|
||||
|
||||
- **Domain**: `agent`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Manages incoming/outgoing webhook subscriptions, endpoint authentication tokens, and event triggers.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/webhook_routes.py` — `@router.get('/webhooks')` — Returns list of registered webhooks.
|
||||
- `src/webhook_manager.py` — `WebhookManager` — Handles payload delivery and signature verification.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- SSRF risks when contacting external webhook URLs if unvalidated.
|
||||
|
||||
## AGENT-004 — Assistant Settings, Task Check-Ins & Background Job Monitor
|
||||
|
||||
- **Domain**: `agent`
|
||||
- **Status**: `partial`
|
||||
- **Evidence Maturity**: `E1`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Manages per-user assistant sessions and scheduled check-in settings, drains background job completions, and retains a legacy no-op activity logging shim.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/assistant_routes.py` — `setup_assistant_routes` — Active assistant session, settings, manual check-in, run-status and timezone-list endpoints, including the owner-scoping guards.
|
||||
- `src/bg_monitor.py` — `_drain_agent` — Runs the agent loop headless against a session to produce the background-job follow-up turn.
|
||||
- `src/bg_monitor.py` — `_run_followup` — Drains completed background jobs and auto-continues the owning session, deferring while a live turn is in progress.
|
||||
- `src/assistant_log.py` — `log_to_assistant` — Legacy no-op activity logging shim retained for existing callers; documented as inactive rather than as current behaviour.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Route `/api/assistant/logs` cited in legacy docs is absent from assistant router.
|
||||
- Existing unit test `tests/cli/test_logs_cli_resolve_nonstring.py` tests CLI target-name resolution logic, not active assistant routes or bg_monitor execution loop.
|
||||
|
||||
## AGENT-005 — Model Context Protocol (MCP) Server Integration
|
||||
|
||||
- **Domain**: `agent`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Integrates external MCP servers over stdio/SSE to expand agent capabilities dynamically.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/mcp_routes.py` — `setup_mcp_routes` — Exposes management endpoints for external MCP servers.
|
||||
- `src/mcp_manager.py` — `McpManager` — Manages MCP server subprocess lifecycles.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Subprocess leaks if external MCP server process fails to terminate clean.
|
||||
|
||||
## AGENT-006 — AI Interaction Tools & Pipeline Orchestration
|
||||
|
||||
- **Domain**: `agent`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides specialized AI interaction tools for agent self-debugging, debate, and multi-model collaboration.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/ai_interaction.py` — `init_ai_interaction_tools` — Registers specialized multi-agent interaction primitives.
|
||||
- `src/builtin_actions.py` — `execute_builtin_action` — Executes pre-built action intent sequences.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- High API token consumption during extended agent debates.
|
||||
|
||||
## AGENT-007 — Subprocess & Background Job Execution Tools
|
||||
|
||||
- **Domain**: `agent`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides sandboxed bash/shell tool execution capabilities with output streaming and background tracking.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/agent_tools/subprocess_tools.py` — `run_command` — Executes shell commands in background/foreground.
|
||||
- `src/bg_jobs.py` — `JobManager` — Tracks async background subprocess tasks.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Arbitrary shell command execution permissions if sandbox confinement fails.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Calendar
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## CALENDAR-001 — CalDAV Calendar Synchronization & Account Setup
|
||||
|
||||
- **Domain**: `calendar`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires a controlled external CalDAV server.
|
||||
|
||||
### Purpose
|
||||
|
||||
Connects to remote CalDAV servers (Apple iCloud, Nextcloud, Google) to sync calendar event feeds.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/calendar_routes.py` — `setup_calendar_routes` — Exposes CalDAV setup and manual sync trigger routes.
|
||||
- `src/caldav_sync.py` — `CalDavSync` — Fetches and parses remote iCalendar VEVENT objects.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Invalid SSL certificates on self-hosted CalDAV servers.
|
||||
|
||||
## CALENDAR-002 — Calendar Event Operations & iCalendar Parsing
|
||||
|
||||
- **Domain**: `calendar`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Creates, updates, deletes, and displays calendar events with timezone conversion and reminder notifications.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/calendar_routes.py` — `@router.get('/events')` — Fetches calendar events for requested date window.
|
||||
- `src/tools/calendar.py` — `CalendarTool` — Agent tool for creating and modifying calendar entries.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Recurring RRULE event expansion calculation bugs across leap years.
|
||||
@@ -0,0 +1,197 @@
|
||||
# Chat
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## CHAT-001 — Core Chat Streaming & SSE Message Generation
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E2`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires access to a live LLM provider endpoint (OpenAI API key or local Ollama server).
|
||||
|
||||
### Purpose
|
||||
|
||||
Handles real-time Server-Sent Events (SSE) chat streaming, token rendering, and model response generation.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/chat_routes.py` — `chat_stream` — POST /api/chat_stream SSE endpoint; builds the shared chat context, then dispatches to the chat-mode or agent-mode streaming path.
|
||||
- `routes/chat_helpers.py` — `build_chat_context` — Shared context builder invoked by chat_stream; runs message preprocessing and assembles the memory/RAG/web context preface.
|
||||
- `src/chat_handler.py` — `ChatHandler.preprocess_message` — Message preprocessing (attachments, URLs, tool preprocessing) reached from build_chat_context via routes/chat_helpers.py:preprocess.
|
||||
- `src/chat_processor.py` — `ChatProcessor.build_context_preface` — Builds the retrieval and web-source context preface injected into the streamed request.
|
||||
- `src/llm_core.py` — `stream_llm_with_fallback` — Chat-mode streaming dispatcher called from chat_stream; wraps stream_llm with an ordered provider fallback chain.
|
||||
- `src/llm_core.py` — `stream_llm` — Per-request streaming entry wrapped by stream_llm_with_fallback; acquires the local model slot and delegates to _stream_llm_inner.
|
||||
- `src/agent_loop.py` — `stream_agent_loop` — Agent-mode streaming path called from chat_stream when the request selects agent mode.
|
||||
- `tests/test_chat_metrics.py` — `test_stream_llm_passes_through_llamacpp_timings` — Inspected unit test asserting stream_llm forwards backend generation timings into the emitted metrics chunk.
|
||||
- `tests/test_resend_message_nondestructive.py` — `test_resend_message_does_not_truncate_by_default` — Inspected unit test asserting the frontend resend path does not truncate prior conversation turns.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Stream interruption on connection drops requires retry logic.
|
||||
|
||||
## CHAT-002 — Session Management & Conversation State
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Manages session creation, listing, switching, renaming, and persistence of conversation metadata.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/session_routes.py` — `@router.get('/api/sessions')` — Lists active sessions filtered by user owner scope.
|
||||
- `core/session_manager.py` — `SessionManager` — Provides thread-safe session storage operations.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Concurrent file writes to sessions.json under high load.
|
||||
|
||||
## CHAT-003 — Chat History & Message Editing/Truncation
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides history retrieval, message content updating, message deletion, and history branch truncation.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/history/history_routes.py` — `@router.get('/api/history/{session_id}')` — Fetches message history timeline for a session.
|
||||
- `routes/history_routes.py` — `_sys.modules[__name__] = _canonical` — Backward-compatibility shim module.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Truncating messages re-indexes context window and clears cached tool calls.
|
||||
|
||||
## CHAT-004 — File & Multimodal Attachment Handling
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Handles uploading, mime validation, image preview, vision encoding, and file attachments in chat messages.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/upload_routes.py` — `@router.post('')` — Accepts multi-part file uploads and generates vision metadata.
|
||||
- `src/upload_handler.py` — `UploadHandler.save_file` — Validates upload size and atomicity on disk.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Large file uploads may consume server disk space if cleanup task fails.
|
||||
|
||||
## CHAT-005 — Chat Message Search
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Enables full-text keyword search across stored chat messages and sessions.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/search_routes.py` — `setup_search_routes` — Registers chat message search endpoint.
|
||||
- `src/session_search.py` — `search_sessions` — Executes query matching against session transcripts.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Full table scans on un-indexed text columns for very large databases.
|
||||
|
||||
## CHAT-006 — System Prompts & Preset Management
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides creation, selection, and customization of system prompt presets for chat sessions.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/preset_routes.py` — `setup_preset_routes` — API routes for listing and modifying system prompt presets.
|
||||
- `src/preset_manager.py` — `PresetManager` — Disk-backed manager for prompt presets.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Invalid JSON syntax in user presets file can corrupt preset loading.
|
||||
|
||||
## CHAT-007 — Emoji Rendering & Twemoji SVG Proxy
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Proxies Twemoji SVG icons locally to render flat SVG emojis in message text without external CDN dependencies.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/emoji_routes.py` — `setup_emoji_routes` — Serves locally cached Twemoji SVGs.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- First request fetches SVG from remote CDN before caching locally.
|
||||
|
||||
## CHAT-008 — Input History Recall (Arrow Up)
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Allows users to cycle through previously sent prompt messages in the chat composer input using Arrow-Up/Down keys.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `static/js/composerArrowUpRecall.js` — `initComposerRecall` — Listens for ArrowUp keypress on composer textarea.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Client-side browser storage limits.
|
||||
|
||||
## CHAT-009 — Context Window Compaction & Truncation
|
||||
|
||||
- **Domain**: `chat`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Compacts session transcript history when prompt size exceeds context limits using summarization.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/history/history_routes.py` — `@router.post('/api/session/{session_id}/compact')` — Triggers context summarization and compaction.
|
||||
- `src/context_compactor.py` — `compact_context` — Executes context token pruning and summary generation.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Aggressive compaction may discard subtle user instructions.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Contact
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## CONTACT-001 — CardDAV Contact Management & Address Book Integration
|
||||
|
||||
- **Domain**: `contact`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Connects to CardDAV servers, imports VCard contacts, and provides contact lookup for email/calendar autocomplete.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/contacts/contacts_routes.py` — `@router.get('/list')` — Returns contact list filtered by search query.
|
||||
- `src/tools/contacts.py` — `ContactsTool` — Agent tool for querying user address book contacts.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- VCard 3.0 vs 4.0 property parsing mismatches.
|
||||
@@ -0,0 +1,85 @@
|
||||
# Cookbook
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## COOKBOOK-001 — Local Model Download & Recipe Lifecycle Management
|
||||
|
||||
- **Domain**: `cookbook`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Downloads HuggingFace models, configures execution parameters, and manages local GGUF/MLX model servers.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/cookbook_routes.py` — `setup_cookbook_routes` — Exposes model downloading and process serving endpoints.
|
||||
- `static/js/cookbook.js` — `initCookbook` — UI manager for local model library.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Disk space exhaustion during multi-gigabyte GGUF weights downloads.
|
||||
|
||||
## COOKBOOK-002 — Hardware Model Fitting ('What Fits?') Analysis Engine
|
||||
|
||||
- **Domain**: `cookbook`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Calculates RAM/VRAM requirements, quantized size, and context overhead to determine model compatibility.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/hwfit_routes.py` — `setup_hwfit_routes` — Calculates hardware model compatibility.
|
||||
- `services/hwfit/fit.py` — `calculate_fit` — Performs parameter and memory fit calculations.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Inaccurate VRAM estimation for non-standard KV-cache quantization.
|
||||
|
||||
## COOKBOOK-003 — HuggingFace & MLX Model Discovery Services
|
||||
|
||||
- **Domain**: `cookbook`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Searches HuggingFace Hub and local MLX model repositories for compatible GGUF and MLX weights.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `services/hwfit/hf_discovery.py` — `search_hf_models` — Queries HuggingFace API for model tags and files.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- HuggingFace API rate limits when searching without an API token.
|
||||
|
||||
## COOKBOOK-004 — Host Docker Access for Inference Container Runtimes
|
||||
|
||||
- **Domain**: `cookbook`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires Docker access and supported physical GPU hardware.
|
||||
|
||||
### Purpose
|
||||
|
||||
Detects and connects to host Docker engine to launch containerized Ollama, vLLM, or SGLang runtimes.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/host_docker_access.py` — `HostDockerAccess` — Interacts with host docker daemon.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Permission denied accessing docker socket on non-root setups.
|
||||
@@ -0,0 +1,108 @@
|
||||
# Document
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## DOCUMENT-001 — Document & Canvas Artifact Management
|
||||
|
||||
- **Domain**: `document`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Renders dynamic canvas documents, handles live editing, markdown preview, and side-by-side artifact display.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/document_routes.py` — `setup_document_routes` — Registers document artifact CRUD routes.
|
||||
- `static/js/document.js` — `initDocumentView` — Renders interactive canvas document panel.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Concurrent edits on the same document artifact.
|
||||
|
||||
## DOCUMENT-002 — PDF Form Processing & High-Fidelity Rendering
|
||||
|
||||
- **Domain**: `document`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E1`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires optional PyMuPDF (`fitz`) or pypdf runtime dependency.
|
||||
|
||||
### Purpose
|
||||
|
||||
Extracts form fields from PDF files, fills dynamic values, and generates PDF previews.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/pdf_runtime.py` — `load_pymupdf_for_pdf_viewer` — Loads optional PyMuPDF runtime for PDF viewing.
|
||||
- `src/pdf_forms.py` — `extract_form_fields` — Handles PDF form field extraction and filling.
|
||||
- `tests/test_document_pdf_marker.py` — `test_marker_removed_without_eating_following_text` — Tests PDF text extraction wrapper stripping without content corruption.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Complex XFA PDF forms may not extract cleanly with standard pdf parsers.
|
||||
|
||||
## DOCUMENT-003 — Personal Document Indexing & RAG Retrieval
|
||||
|
||||
- **Domain**: `document`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Indexes local user documents (PDF, DOCX, TXT) into ChromaDB for semantic vector retrieval.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/personal_routes.py` — `setup_personal_routes` — Personal document RAG indexing and search API endpoints.
|
||||
- `src/personal_docs.py` — `PersonalDocsManager` — Handles file text chunking and vector storage.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Slow vector embedding indexing step for massive multi-thousand page documents.
|
||||
|
||||
## DOCUMENT-004 — Document Conversion & Text Extraction Engine
|
||||
|
||||
- **Domain**: `document`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Converts office formats (.docx, .xlsx, .pptx) and HTML into clean Markdown text representations.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/markitdown_runtime.py` — `convert_to_markdown` — Converts binary office documents into structured Markdown text.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Formatting loss when parsing legacy binary doc/xls files.
|
||||
|
||||
## DOCUMENT-005 — Document Library UI Navigation
|
||||
|
||||
- **Domain**: `document`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides dedicated UI view for browsing, filtering, and organizing saved user documents.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `static/js/documentLibrary.js` — `initDocumentLibrary` — Renders document library navigation grid.
|
||||
- `app.py` — `serve_library` — Serves SPA shell for /library route.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Large folder trees may cause initial DOM render slowdown.
|
||||
@@ -0,0 +1,87 @@
|
||||
# Email
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## EMAIL-001 — Email Account Setup, IMAP/SMTP Connection & Polling
|
||||
|
||||
- **Domain**: `email`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E1`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires a controlled live IMAP account and network access.
|
||||
|
||||
### Purpose
|
||||
|
||||
Configures IMAP/SMTP email accounts, validates TLS certificates, and polls background inbox updates.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/email_routes.py` — `setup_email_routes` — Sets up email account management and synchronization routes.
|
||||
- `routes/email_pollers.py` — `_start_poller` — Background poller for email inbox synchronization.
|
||||
- `tests/test_service_health_email.py` — `test_email_ok_all_connect` — Tests IMAP connection health probing and status reporting.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Account lockouts if bad credentials are repeatedly polled.
|
||||
|
||||
## EMAIL-002 — Email Searching, Threading & Message Operations
|
||||
|
||||
- **Domain**: `email`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Parses email headers, folds signatures, groups messages into threads, and executes full-text email search.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/email_routes.py` — `@router.get('/search')` — Executes search across cached email headers and text.
|
||||
- `src/email_thread_parser.py` — `parse_email_thread` — Builds conversation tree from Message-ID and In-Reply-To headers.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Malformed MIME email structures failing HTML sanitization.
|
||||
|
||||
## EMAIL-003 — Email Composition, Draft Management & Sending
|
||||
|
||||
- **Domain**: `email`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires a controlled live SMTP account and network access.
|
||||
|
||||
### Purpose
|
||||
|
||||
Creates, saves, and dispatches HTML/plaintext email messages via SMTP.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/email_routes.py` — `@router.post('/send')` — Sends email message via user SMTP credentials.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- SMTP connection drop mid-send causing unsent mail state.
|
||||
|
||||
## EMAIL-004 — Email MCP Server & Codex Integration Bridge
|
||||
|
||||
- **Domain**: `email`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Exposes constrained email reading and draft capabilities to external Codex / MCP agents with scope checks.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `mcp_servers/email_server.py` — `EmailMcpServer` — MCP server exposing email tools over stdio/SSE.
|
||||
- `routes/codex_routes.py` — `setup_codex_routes` — Bridge endpoints for external Codex plugin integration.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Unauthorized mail sending if token scopes are improperly scoped.
|
||||
@@ -0,0 +1,149 @@
|
||||
# Frontend
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## FRONTEND-001 — Single Page Application Shell & Client Router
|
||||
|
||||
- **Domain**: `frontend`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Main HTML5 SPA shell, DOM lifecycle initializers, tab navigation, and deep-link route handlers.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `static/index.html` — `index.html` — Main SPA entry point containing modal roots and CSS bundles.
|
||||
- `app.py` — `serve_index` — Serves index.html with dynamically generated CSP nonces.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Stale browser static cache if asset hashing is omitted during deployment.
|
||||
|
||||
## FRONTEND-002 — Dynamic Theme, Color System & Custom Fonts
|
||||
|
||||
- **Domain**: `frontend`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Supports dark/light themes, custom CSS variables, color picker controls, and user font uploads.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `static/js/theme.js` — `applyTheme` — Applies custom HSL theme variables to DOM document root.
|
||||
- `routes/font_routes.py` — `setup_font_routes` — Allows uploading and serving custom WOFF2 font files.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Flash of unstyled content (FOUC) on slow connections.
|
||||
|
||||
## FRONTEND-003 — Window Manager, Tile Layout & Modal Control System
|
||||
|
||||
- **Domain**: `frontend`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Manages draggable tool windows, snapped multi-tile viewports, modal dialog Z-ordering, and ESC key stacks.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `static/js/modalManager.js` — `ModalManager` — Controls modal open/close transitions and focus trapping.
|
||||
- `static/js/tileManager.js` — `TileManager` — Handles viewport split-pane grid arrangements.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Overlap artifacts when opening many simultaneous tool floating windows.
|
||||
|
||||
## FRONTEND-004 — Global Keyboard Shortcuts & Accessibility Controls
|
||||
|
||||
- **Domain**: `frontend`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides configurable hotkeys (Ctrl+K search, Esc close, Alt+1-9 tabs) and high-contrast accessibility options.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `static/js/keyboard-shortcuts.js` — `initShortcuts` — Binds global keydown handlers for system shortcuts.
|
||||
- `static/js/a11y.js` — `initA11y` — Applies ARIA roles and dyslexic font toggles.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Browser keybinding collisions with browser default hotkeys.
|
||||
|
||||
## FRONTEND-005 — Markdown, LaTeX & Code Block Streaming Renderer
|
||||
|
||||
- **Domain**: `frontend`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Parses incoming SSE markdown streams, renders KaTeX math formulas, syntax-highlighted code, and interactive runners.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `static/js/markdown.js` — `renderMarkdown` — Converts markdown prose to HTML nodes with syntax highlighting.
|
||||
- `static/js/streamingSegmenter.js` — `Segmenter` — Parses un-closed markdown fences during live stream.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- DOM thrashing if streaming segmenter updates UI too frequently.
|
||||
|
||||
## FRONTEND-006 — Interactive Tour & Guided Onboarding System
|
||||
|
||||
- **Domain**: `frontend`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Presents interactive step-by-step feature tours and UI tooltip hints for new users.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `static/js/tourHints.js` — `startTour` — Renders guided feature tour overlays over target UI elements.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Tour step misalignment if window is resized mid-tour.
|
||||
|
||||
## FRONTEND-007 — Background Effects Prototyping Sandbox
|
||||
|
||||
- **Domain**: `frontend`
|
||||
- **Status**: `dead-code-candidate`
|
||||
- **Evidence Maturity**: `E1`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Standalone sandbox page for prototyping visual background animations, waves, and whirlpool effects.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `app.py` — `serve_backgrounds` — Serves visual background sandbox HTML page route.
|
||||
- `static/wave-variants.html` — `wave-variants.html` — Interactive background effect prototyping sandbox variant.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Route `/backgrounds` in app.py L918 attempts to serve `static/backgrounds.html` which is missing from disk; variant templates `wave-variants.html` and `whirlpool-variants.html` exist.
|
||||
@@ -0,0 +1,170 @@
|
||||
# Media
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## MEDIA-001 — Gallery Image Library & Album Operations
|
||||
|
||||
- **Domain**: `media`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Organizes images into custom albums, provides grid browsing, tagging, and album metadata management.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/gallery/gallery_routes.py` — `@router.get('/api/gallery/library')` — Fetches image library list with tag filters.
|
||||
- `static/js/gallery.js` — `initGallery` — Main gallery grid renderer and uploader.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Thumbnail generation overhead for high-resolution RAW camera images.
|
||||
|
||||
## MEDIA-002 — Image Processing, AI Upscaling & Style Transfer
|
||||
|
||||
- **Domain**: `media`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Executes local image enhancement, background removal, face sharpening, and AI upscaling operations.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/gallery/gallery_routes.py` — `@router.post('/api/gallery/ai-upscale')` — Runs RealESRGAN image upscaling.
|
||||
- `routes/gallery/gallery_routes.py` — `@router.post('/api/image/remove-bg')` — Executes background removal pass.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- High GPU memory allocation when upscaling 4K images.
|
||||
|
||||
## MEDIA-003 — Interactive Image Canvas Editor & Persisted Drafts
|
||||
|
||||
- **Domain**: `media`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides full multi-layer raster canvas editor, brush tools, transforms, masks, and draft project persistence.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/editor_draft_routes.py` — `setup_editor_draft_routes` — API routes for saving and loading canvas project drafts.
|
||||
- `static/js/editor/history-panel.js` — `HistoryManager` — Canvas undo/redo stack manager.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Browser memory leak if multi-gigabyte layer undo buffers are kept indefinitely.
|
||||
|
||||
## MEDIA-004 — Text-to-Speech (TTS) Synthesis Service
|
||||
|
||||
- **Domain**: `media`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Synthesizes spoken audio from text using local Kokoro, EdgeTTS, or OpenAI TTS engines.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/tts_routes.py` — `@router.post('/synthesize')` — Synthesizes TTS audio clip.
|
||||
- `services/tts/tts_service.py` — `TTSService` — Provider abstraction layer for audio speech generation.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Audio synthesis latency on CPU-only hardware setups.
|
||||
|
||||
## MEDIA-005 — Speech-to-Text (STT) Audio Transcription Service
|
||||
|
||||
- **Domain**: `media`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Transcribes user audio recordings into text using faster-whisper or local speech models.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/stt_routes.py` — `@router.post('/transcribe')` — Accepts multipart audio file and returns transcription text.
|
||||
- `services/stt/stt_service.py` — `STTService` — Whisper audio transcription engine wrapper.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Missing ffmpeg system dependency prevents audio format decoding.
|
||||
|
||||
## MEDIA-006 — Digital Signature Stamp Storage & Placement
|
||||
|
||||
- **Domain**: `media`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Stores transparent PNG user signatures and stamps for placement onto PDF forms and documents.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/signature_routes.py` — `setup_signature_routes` — CRUD endpoints for managing user signature PNG stamps.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Cross-site scripting if signature image titles contain unescaped user input.
|
||||
|
||||
## MEDIA-007 — Generated Image Artifact Route & MCP Integration
|
||||
|
||||
- **Domain**: `media`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Serves generated AI artwork artifacts and integrates with image generation MCP server.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `app.py` — `serve_generated_image` — Serves generated image artifacts with cache headers.
|
||||
- `src/generated_images.py` — `resolve_generated_image_path` — Confines requested image path within artifacts directory.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Path traversal vulnerability if filename parameter is un-sanitized.
|
||||
|
||||
## MEDIA-008 — Native MLX Image Bridge (macOS Apple Silicon)
|
||||
|
||||
- **Domain**: `media`
|
||||
- **Status**: `experimental`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires Apple Silicon, macOS tooling, and the compiled MLX bridge.
|
||||
|
||||
### Purpose
|
||||
|
||||
Native Apple Swift bridge for hardware-accelerated diffusion and MLX image colorization on macOS.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `swift/odysseus-mlx-image-bridge/Package.swift` — `Package` — Swift package manifest for native MLX image bridge.
|
||||
- `scripts/mlx_image_server.py` — `main` — Python daemon wrapping native Swift MLX binary.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Binary build requires Xcode command line tools build step (`build-macos-app.sh`).
|
||||
@@ -0,0 +1,24 @@
|
||||
# Memory
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## MEMORY-001 — Persistent Long-Term Memory & Vector Indexing
|
||||
|
||||
- **Domain**: `memory`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Extracts facts, user preferences, and temporal memories from chat sessions into vector/relational storage.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/memory/memory_routes.py` — `@router.get('')` — Fetches long-term user memory timeline.
|
||||
- `services/memory/memory_extractor.py` — `MemoryExtractor` — LLM-driven fact extraction from conversation transcripts.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Conflicting memory facts extracted from contradictory user prompts.
|
||||
@@ -0,0 +1,177 @@
|
||||
# Model
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## MODEL-001 — Multi-Provider LLM Model Discovery & Metadata Management
|
||||
|
||||
- **Domain**: `model`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Discovers models from OpenAI, Anthropic, Ollama, vLLM, LMStudio, OpenRouter, and Google AI Studio endpoints.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/model_routes.py` — `@router.get('/api/models')` — Returns unified list of available models across providers.
|
||||
- `src/model_discovery.py` — `ModelDiscovery.discover_all` — Queries connected provider endpoints for available model IDs.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Remote endpoint timeouts may slow down full discovery refresh.
|
||||
|
||||
## MODEL-002 — Model Capability & Context Limits Detection
|
||||
|
||||
- **Domain**: `model`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Detects vision, tool calling, reasoning, and context window limits for connected model endpoints.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/model_capabilities.py` — `get_model_capabilities` — Maps model names to vision and tool support flags.
|
||||
- `src/endpoint_resolver.py` — `resolve_endpoint_headers` — Resolves auth headers and target URLs for model endpoints.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Incorrect context limit metadata for unlisted custom fine-tunes.
|
||||
|
||||
## MODEL-003 — LLM Core Provider Communication & Fallback Routing
|
||||
|
||||
- **Domain**: `model`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Provider dispatch, header injection and fallback advancement are only observable against a reachable LLM provider endpoint; not exercised in this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Manages HTTP request dispatching, authorization header injection, and fallback provider routing for LLM calls.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/llm_core.py` — `llm_call_async` — Non-streaming provider request dispatcher: resolves the endpoint, injects authorization headers and executes the HTTP call.
|
||||
- `src/llm_core.py` — `llm_call_async_with_fallback` — Ordered fallback wrapper that retries llm_call_async across the configured candidate endpoints.
|
||||
- `src/llm_core.py` — `stream_llm_with_fallback` — Ordered fallback wrapper for the streaming path; advances to the next candidate when a provider yields an empty completion.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Unexpected API changes in upstream third-party model providers.
|
||||
|
||||
## MODEL-004 — Model Selection & Display Ordering Preferences
|
||||
|
||||
- **Domain**: `model`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Allows pinning, sorting, and hiding specific models in the UI selection dropdown.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/model_routes.py` — `@router.post('/order')` — Saves custom model display order preference.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Stale model IDs in custom order lists after model endpoints are removed.
|
||||
|
||||
## MODEL-005 — Side-by-Side Model Comparison (A/B Testing)
|
||||
|
||||
- **Domain**: `model`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Enables dual-model side-by-side response evaluation, arena scoring, and latency comparison.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/compare/compare_routes.py` — `@router.post('/start')` — Starts a parallel dual-model comparison stream.
|
||||
- `static/js/compare/index.js` — `initCompareView` — Renders side-by-side model chat panes.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- High memory and network usage when streaming two model responses simultaneously.
|
||||
|
||||
## MODEL-006 — GitHub Copilot Device Flow Authentication
|
||||
|
||||
- **Domain**: `model`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E2`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires an interactive GitHub Copilot OAuth device-flow account.
|
||||
|
||||
### Purpose
|
||||
|
||||
Authenticates with GitHub Copilot via OAuth device flow to use Copilot models directly.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/copilot_routes.py` — `setup_copilot_routes` — Builds the Copilot device-flow router at prefix /api/copilot, wiring _start_device_flow and _poll_device_flow.
|
||||
- `routes/device_flow.py` — `create_device_flow_router` — Shared factory registering POST /device/start and POST /device/poll under the caller-supplied prefix.
|
||||
- `src/copilot.py` — `request_device_code` — Issues the GitHub device-code request that begins the Copilot OAuth device flow.
|
||||
- `src/copilot.py` — `poll_access_token` — Polls GitHub for the access token once the user has authorized the device code.
|
||||
- `tests/test_provider_device_flow_js.py` — `test_copilot_success_uses_complete_verification_uri` — Inspected unit test asserting the Copilot device-flow runner surfaces the complete verification URI returned by the backend.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Token expiration requires manual device re-authentication.
|
||||
|
||||
## MODEL-007 — ChatGPT Subscription Device Flow Authentication
|
||||
|
||||
- **Domain**: `model`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E2`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires an interactive ChatGPT subscription OAuth flow.
|
||||
|
||||
### Purpose
|
||||
|
||||
Authenticates with ChatGPT Pro/Plus subscription tokens via device login flow.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/chatgpt_subscription_routes.py` — `setup_chatgpt_subscription_routes` — Builds the ChatGPT subscription device-flow router at prefix /api/chatgpt-subscription.
|
||||
- `routes/device_flow.py` — `create_device_flow_router` — Shared factory registering POST /device/start and POST /device/poll under the caller-supplied prefix.
|
||||
- `src/chatgpt_subscription.py` — `request_device_code` — Issues the ChatGPT device-authorization request that begins the subscription OAuth device flow.
|
||||
- `src/chatgpt_subscription.py` — `poll_device_auth` — Polls the ChatGPT device-authorization endpoint for completion using the stored device_auth_id and user_code.
|
||||
- `tests/test_provider_device_flow_js.py` — `test_chatgpt_success_uses_plain_verification_uri` — Inspected unit test asserting the ChatGPT device-flow runner uses the plain verification URI rather than the Copilot complete-URI form.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Changes in OpenAI auth endpoint security challenges.
|
||||
|
||||
## MODEL-008 — Embedding Model Lane & Vector Provider Setup
|
||||
|
||||
- **Domain**: `model`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Configures local sentence-transformers, FastEmbed, or remote OpenAI embedding model lanes.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/embedding_routes.py` — `setup_embedding_routes` — Provides embedding provider configuration endpoints.
|
||||
- `src/embeddings.py` — `EmbeddingManager` — Generates dense vector embeddings for RAG and memory.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- First-time download of heavy PyTorch model weights on CPU-only machines.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Note
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## NOTE-001 — Interactive Notes & Checklist Management
|
||||
|
||||
- **Domain**: `note`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides Google Keep-style notes, rich markdown text, checklist items, pinning, color tags, and reminders.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/note/note_routes.py` — `@router.get('')` — Lists all user notes with pin and archive states.
|
||||
- `static/js/notes.js` — `initNotesView` — Main interactive notes grid and modal manager.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Concurrent edits on note item checkboxes.
|
||||
@@ -0,0 +1,213 @@
|
||||
# Platform
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## PLATFORM-001 — Application Initialization & Lifespan Management
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Orchestrates server startup, database table migration, background daemon initialization, and clean shutdown.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `app.py` — `_lifespan` — FastAPI lifespan context manager executing startup tasks.
|
||||
- `src/app_initializer.py` — `initialize_app` — Initializes app directories, DB schemas, and logging.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Un-handled exceptions during startup halt application launch.
|
||||
|
||||
## PLATFORM-002 — System Health, Readiness & Version Monitoring APIs
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Exposes Liveness (/api/health), Readiness (/api/ready), App Version (/api/version), and Client Perf APIs.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `app.py` — `readiness_check` — Performs system component integrity check.
|
||||
- `src/readiness.py` — `check_readiness` — Checks database, storage, and key paths for read/write access.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Readiness check delays if verifying connectivity to offline remote endpoints.
|
||||
|
||||
## PLATFORM-003 — Database Schema, Migrations & SQLite Persistence
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Defines core relational tables (users, tokens, tasks, sessions) and executes automated SQLite schema upgrades.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `core/database.py` — `init_db` — Creates ORM tables and establishes connection pool.
|
||||
- `scripts/update_database.py` — `run_migrations` — Applies missing schema columns and indices.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- SQLite file lock contention under high concurrent write loads.
|
||||
|
||||
## PLATFORM-004 — User Data Export & Import Backup Infrastructure
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Exports complete user workspace state (sessions, memory, skills, notes, presets) into a zip archive.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/backup_routes.py` — `setup_backup_routes` — Handles workspace data export and import upload unpack.
|
||||
- `docs/backup-restore.md` — `Documentation` — Backup and restore operational documentation.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Corrupt archive files causing partial data restore.
|
||||
|
||||
## PLATFORM-005 — File Cleanup & Storage Maintenance Engine
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Scans data directories for orphaned files, old uploads, temporary vision images, and frees disk space.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/cleanup/cleanup_routes.py` — `@router.get('/preview')` — Previews reclaimable disk space across storage directories.
|
||||
- `src/cleanup_service.py` — `CleanupService` — Executes filesystem purge of orphaned asset files.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Deletes files uploaded in active sessions if retention window is set too short.
|
||||
|
||||
## PLATFORM-006 — System Health & RAG Diagnostic Suite
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Executes real-time integrity diagnostics across ChromaDB, SearXNG, local models, and network interfaces.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/diagnostics_routes.py` — `setup_diagnostics_routes` — Runs subsystem health check suite.
|
||||
- `src/service_health.py` — `collect_health_status` — Inspects vector database, email, search, and local provider status.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Diagnostic timeout if external search provider is unreachable.
|
||||
|
||||
## PLATFORM-007 — Desktop CLI Utilities & Shell Integration Tools
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides command-line interface tools (`odysseus`, `odysseus-mcp`, `odysseus-mail`) for terminal usage.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `scripts/_lib/cli.py` — `main` — Shared CLI framework for terminal helper commands.
|
||||
- `scripts/odysseus` — `odysseus` — Main terminal launcher script.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Outdated CLI scripts if backend API schemas change.
|
||||
|
||||
## PLATFORM-008 — Desktop Companion App Integration
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides API routes and pairing mechanisms for the native macOS/desktop menu bar companion app.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `companion/routes.py` — `setup_companion_routes` — Endpoints for pairing and status sync with desktop companion.
|
||||
- `companion/pairing.py` — `PairingManager` — Generates and validates companion pairing codes.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Pairing code expiration timing window.
|
||||
|
||||
## PLATFORM-009 — Docker Containerization & GPU Hardware Manifests
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires Docker GPU pass-through and compatible host drivers.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides multi-stage Dockerfile and Docker Compose manifests for CPU, NVIDIA CUDA, and AMD ROCm GPUs.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `Dockerfile` — `multi-stage-build` — Multi-stage container build environment.
|
||||
- `docker-compose.gpu-nvidia.yml` — `nvidia-gpu-manifest` — NVIDIA GPU pass-through container specification.
|
||||
- `scripts/check-docker-gpu.sh` — `check-docker-gpu` — Automated diagnostic test script for host NVIDIA GPU passthrough.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Driver version incompatibility with host NVIDIA/AMD kernel drivers.
|
||||
|
||||
## PLATFORM-010 — Legacy FAISS Vector Index Migration Script
|
||||
|
||||
- **Domain**: `platform`
|
||||
- **Status**: `legacy`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Legacy utility script to migrate older FAISS vector indices into ChromaDB.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `scripts/migrate_faiss_to_chroma.py` — `migrate_faiss` — Reads FAISS vector index files and writes to ChromaDB collection.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Superseded by native ChromaDB vector index pipeline.
|
||||
@@ -0,0 +1,86 @@
|
||||
# Research
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## RESEARCH-001 — Deep Research Execution Engine & SSE Progress Streaming
|
||||
|
||||
- **Domain**: `research`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Executes multi-step recursive deep research tasks, web page scraping, synthesis, and streams live progress.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/research/research_routes.py` — `@router.post('/api/research/start')` — Initiates deep research job.
|
||||
- `src/deep_research.py` — `DeepResearchEngine` — Recursive search and summary crawler.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- High memory consumption when parsing multi-megabyte HTML target pages.
|
||||
|
||||
## RESEARCH-002 — Research Library, Detail View & Image Controls
|
||||
|
||||
- **Domain**: `research`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Stores completed research reports, generated diagrams, reference links, and manages image visibility.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/research/research_routes.py` — `@router.get('/api/research/library')` — Returns all saved research reports.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Orphaned report files if storage directory is modified out-of-band.
|
||||
|
||||
## RESEARCH-003 — Web Search Engine Integration (SearXNG & Multi-Provider)
|
||||
|
||||
- **Domain**: `research`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E1`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires an active SearXNG instance or external search API provider.
|
||||
|
||||
### Purpose
|
||||
|
||||
Queries SearXNG, DuckDuckGo, or Google Search instances to retrieve web search snippets.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/search_routes.py` — `setup_search_routes` — Defines /api/search, /api/search/config, and /api/search/query endpoints.
|
||||
- `src/search/core.py` — `SearchEngine` — Compatibility module aliasing services.search.core.
|
||||
- `tests/test_search_ranking.py` — `test_news_queries_prefer_news_sources_over_sports_and_social_results` — Tests search result domain ranking and scoring.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Search provider IP throttling or rate-limiting.
|
||||
|
||||
## RESEARCH-004 — Research Result Peeking & Topic Spinoff Generation
|
||||
|
||||
- **Domain**: `research`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Extracts preliminary research snippets and spawns child research sessions focused on specific sub-topics.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/research/research_routes.py` — `@router.post('/api/research/spinoff/{session_id}')` — Spawns child research session for specific query.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Deep recursion tree depth when spawning multiple nested spinoffs.
|
||||
@@ -0,0 +1,154 @@
|
||||
# Security
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## SECURITY-001 — Authentication, Session Cookies & User Management
|
||||
|
||||
- **Domain**: `security`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Handles bcrypt password hashing, session cookie issuance, authentication enforcement, and user administration.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/auth_routes.py` — `@router.post('/login')` — Authenticates credentials and sets session cookie.
|
||||
- `core/auth.py` — `AuthManager` — Handles user creation, password verification, and session tokens.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Cookie session hijack if deployed over unencrypted HTTP without HTTPS cookie flags.
|
||||
|
||||
## SECURITY-002 — System Vault Encrypted Secret Storage
|
||||
|
||||
- **Domain**: `security`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E1`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: pending — Requires installed Bitwarden CLI (`bw`) executable.
|
||||
|
||||
### Purpose
|
||||
|
||||
Encrypts API keys, passphrases, and third-party secrets on disk using AES-GCM / PBKDF2 key derivation.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/vault_routes.py` — `setup_vault_routes` — Admin routes for vault configuration, login, unlock, lock, and logout.
|
||||
- `src/secret_storage.py` — `SecretStorage` — Fernet symmetric key DB secret encryption.
|
||||
- `tests/test_vault_password_not_in_argv.py` — `test_bw_password_not_in_argv` — Verifies master password is fed via stdin and never appears in process argv.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Loss of vault master passphrase renders all encrypted secrets permanently unrecoverable.
|
||||
|
||||
## SECURITY-003 — API Token Management & Scope Access Control
|
||||
|
||||
- **Domain**: `security`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Generates scoped API bearer tokens (read/write/admin) for external tool and script authentication.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/api_token_routes.py` — `setup_api_token_routes` — Exposes API token creation, scope assignment, and revocation.
|
||||
- `core/database.py` — `ApiToken` — SQLAlchemy ORM schema for API tokens and permissions.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Leaked API bearer tokens with excessive permission scopes.
|
||||
|
||||
## SECURITY-004 — Prompt Security & Injection Defense Engine
|
||||
|
||||
- **Domain**: `security`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E1`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Scans system prompts and external inputs for prompt injection attempts, jailbreaks, and sensitive data leaks.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/prompt_security.py` — `untrusted_context_message` — Wraps untrusted context with guard delimiters and sets metadata.trusted = False.
|
||||
- `src/tool_security.py` — `NON_ADMIN_BLOCKED_TOOLS` — Enforces tool execution safety for non-admin user roles.
|
||||
- `tests/test_skill_index_prompt_injection.py` — `test_skill_index` — Verifies skill index descriptions cannot leak into trusted system prompts.
|
||||
- `tests/test_tool_output_prompt_injection.py` — `test_tool_output` — Tool output injection guards.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- False positives blocking legitimate complex coding or security prompts.
|
||||
|
||||
## SECURITY-005 — URL & Path Confinement Security Guards
|
||||
|
||||
- **Domain**: `security`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E1`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Prevents SSRF attacks and path traversal by validating target IP addresses and resolving symlinks.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `src/url_safety.py` — `check_outbound_url` — Rejects non-HTTP(S) schemes, link-local, cloud metadata SSRF addresses.
|
||||
- `src/url_security.py` — `validate_public_http_url` — Validates public-facing endpoints.
|
||||
- `tests/test_url_safety.py` — `test_url_safety` — Scheme validation, cloud metadata SSRF rejection, IP classification.
|
||||
- `tests/test_tool_path_confinement.py` — `test_path_confinement` — Path traversal checks.
|
||||
- `tests/test_workspace_confine.py` — `test_workspace_confine` — Workspace confinement checks.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- DNS rebinding attacks if IP address is re-resolved post-validation.
|
||||
|
||||
## SECURITY-006 — HTTP Security Headers Middleware
|
||||
|
||||
- **Domain**: `security`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Injects standard OWASP HTTP security headers (CSP, HSTS, X-Content-Type-Options, X-Frame-Options).
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `core/middleware.py` — `SecurityHeadersMiddleware` — Sets strict security headers and CSP nonces on HTTP responses.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Strict Content Security Policy (CSP) blocking third-party embedded web resources.
|
||||
|
||||
## SECURITY-007 — Admin System Data Wipe ('Danger Zone')
|
||||
|
||||
- **Domain**: `security`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Provides administrative reset operations to wipe sessions, cache, uploaded files, or factory reset state.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/admin_wipe/admin_wipe_routes.py` — `@router.delete('/wipe/{kind}')` — Executes systemic data wipe based on requested scope.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Accidental catastrophic data loss if triggered without user confirmation.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Skill
|
||||
|
||||
Features in this document are generated from [`../feature-catalog.json`](../feature-catalog.json), the canonical inventory.
|
||||
|
||||
## SKILL-001 — Dynamic Skill Management & Code Execution Engine
|
||||
|
||||
- **Domain**: `skill`
|
||||
- **Status**: `verified`
|
||||
- **Evidence Maturity**: `E0`
|
||||
- **Commit Verified**: `d8a2059df8e53bc7275c45339849d14c8651e73c`
|
||||
- **Runtime Validation**: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.
|
||||
|
||||
### Purpose
|
||||
|
||||
Allows users to create, import, edit, test, and execute custom Python/Markdown skills dynamically.
|
||||
|
||||
### Evidence summary
|
||||
|
||||
- `routes/skills_routes.py` — `setup_skills_routes` — Exposes CRUD and remote import routes for user skills.
|
||||
- `services/memory/skills.py` — `SkillsManager` — Handles skill storage, parsing, and execution.
|
||||
|
||||
### Unknowns
|
||||
|
||||
- Arbitrary code execution risks if skill import URL is untrusted.
|
||||
Reference in New Issue
Block a user