Study Odyseus → Adapt to Proteus
Use this skill when the user asks to study, check, compare, or reference the Odyseus project (D:\Fresh_Start\Testing stuff\Odyseus) for a feature they want to understand or build in Proteus.
Procedure
- Identify the feature the user wants to study (memory, cookbook, agents, tools, auth, providers, UI, etc.)
- Look up file paths in the Odyseus map below
- Read the relevant source files (code first, not markdown)
- Compare with Proteus — what exists, what's missing, what's different
- Present findings as a concise diff/summary, then recommend next steps
Odyseus Codebase Map
Root: D:\Fresh_Start\Testing stuff\Odyseus
Core Architecture
| Area |
Key Files |
What's There |
| App entry |
app.py |
FastAPI app, router mounting, static files |
| Config |
src/config.py |
Settings, env vars, feature flags |
| Auth |
core/auth.py |
JWT creation/verification, Fernet encryption |
| Database |
core/database.py |
SQLAlchemy engine, session, TypeDecorators |
| Models |
core/models.py |
All SQLAlchemy models (User, Session, Memory, etc.) |
Memory System
| Area |
Key Files |
What's There |
| Memory manager |
services/memory/ |
CRUD, recall, pin, dedup, context injection |
| Memory extractor |
services/memory_extractor.py |
LLM-based fact extraction from chat |
| Vector store |
src/vector_store.py |
Chroma PersistentClient, collection management |
| Embeddings |
src/embeddings.py |
fastembed wrapper, @lru_cache singleton |
| Memory routes |
routes/memory_routes.py |
/api/memory CRUD, /recall endpoint |
Cookbook / Model Management
| Area |
Key Files |
What's There |
| Catalog builder |
scripts/add_hwfit_models.py |
HF Hub fetch, 5-layer param extraction, JSON merge |
| Catalog data |
data/cookbook_catalog.json |
911+ model entries with fit scores |
| Fit scoring |
services/hwfit/fit.py |
GPU bandwidth table, use-case weights, 4-component scoring |
| Hardware detection |
services/hardware.py |
nvidia-smi, RAM, CPU, 24h cache |
| Cookbook routes |
routes/cookbook_routes.py |
/api/cookbook/hf-trending, /hardware |
| Local scanner |
services/local_scanner.py |
HF cache + Ollama + user dirs, 4-source scan |
Agent / Tool System
| Area |
Key Files |
What's There |
| Tool schemas |
src/tool_schemas.py |
~60+ tool definitions (1372 lines) |
| Tool implementations |
src/tool_implementations.py |
do_* functions (4457 lines) |
| Tool execution |
src/tool_execution.py |
Dispatcher, admin checks, MCP routing (1557 lines) |
| Agent loop |
services/agent_loop.py |
ReAct loop, tool dispatch, streaming |
| Goal system |
services/goal_manager.py |
Goal condition, attempts, pause/resume |
Provider / Model Endpoints
| Area |
Key Files |
What's There |
| Provider presets |
routes/model_endpoints.py |
Known providers (Groq, OpenAI, etc.), /presets |
| Provider probe |
services/provider_probe.py |
Test API key, list models, honest error reporting |
| Model picker |
static/js/modelPicker.js |
Client-side model selection UI (720 lines) |
| Models list |
static/js/models.js |
Model list with favorites, usage tracking (642 lines) |
| Provider logos |
static/js/providers.js |
Regex → SVG logo mapping (140 lines) |
Frontend / UI
| Area |
Key Files |
What's There |
| Chat UI |
static/js/chat.js |
Main chat logic, SSE streaming, tool rendering |
| CSS |
static/css/style.css |
All styles, dialog system, provider forms |
| HTML |
templates/chat.html |
Chat page, dialogs, auth overlay |
| Static mount |
app.py |
DevStaticFiles with cache-control headers |
Sessions / Goals
| Area |
Key Files |
What's There |
| Session routes |
routes/session_routes.py |
CRUD, goal CRUD, history |
| Goal events |
SSE in chat_routes.py |
goal_started, goal_progress, goal_achieved, goal_failed, goal_paused |
Testing
| Area |
Key Files |
What's There |
| Test config |
tests/conftest.py |
In-memory SQLite, temp Chroma, JWT secret |
| Memory tests |
tests/test_memory.py |
32 unit tests with mock embedder |
| Route tests |
tests/test_memory_routes.py |
13 route tests with dep overrides |
| Chat integration |
tests/test_chat_memory_integration.py |
6 tests with mocked stream_chat |
| Goal tests |
tests/test_goal.py |
10+ dispatch tests with async generator stubs |
| Secret storage |
tests/test_secret_storage.py |
7 Fernet encryption tests |
Proteus vs Odyseus — Quick Reference
| Feature |
Odyseus |
Proteus |
Status |
| Memory |
3-layer (SQL + Chroma + extractor) |
Memory manager + Chroma + React UI |
✅ Built |
| Cookbook catalog |
add_hwfit_models.py + cookbook_catalog.json |
cookbook_routes.py + data/cookbook_catalog.json |
✅ Built |
| Local scanner |
local_scanner.py (4 sources) |
local_scanner.py (4 sources) |
✅ Built |
| Hardware detection |
services/hardware.py |
services/hardware.py |
✅ Built |
| Provider presets |
routes/model_endpoints.py |
routes/model_endpoints.py |
✅ Built |
| Auth |
JWT + localStorage + auto-refresh + modal |
JWT + localStorage + auto-refresh + modal |
✅ Built |
| Agent tools |
60+ tools (tool_schemas.py) |
9 tools (agent_loop.py) |
⚠️ Gap |
| MCP integration |
Full MCP routing |
Not implemented |
❌ Gap |
| Goal system |
Goal condition + attempts + pause |
Goal condition + attempts + pause |
✅ Built |
| UI framework |
Vanilla JS + CSS |
React + Vite + Tailwind + Radix |
✅ Built |
Usage Examples
User says: "parent directory mai odyseus hai, usme memory kis tarhan kaam krti hai"
→ Look up Memory section, read services/memory/ files, compare with Proteus memory
User says: "odyseus ka cookbook logic check kro"
→ Look up Cookbook section, read scripts/add_hwfit_models.py + services/hwfit/fit.py
User says: "check odysseus tools, which can we add?"
→ Look up Agent/Tool section, read src/tool_schemas.py, compare with Proteus agent_loop.py
User says: "odyseus ka UI dekho, clean hai"
→ Look up Frontend section, read static/js/chat.js + static/css/style.css, note design patterns
Notes
- Odyseus is a multi-user production app; Proteus is single-user MVP
- Odyseus uses vanilla JS + CSS; Proteus uses React + Tailwind
- Always read code first, not markdown files, for accurate comparison
- Odyseus's
src/ is the Python backend; static/ and templates/ are the frontend
- When adapting features, simplify for single-user (no owner/tenant fields, no admin checks)
1---2name: proteus-study-odyseus3description: Navigate the Odyseus reference project (parent directory) to study a specific feature, compare it with Proteus, and adapt the implementation. Use when the user asks to check/learn/compare/reference Odyseus for any feature.4---56# Study Odyseus → Adapt to Proteus78Use this skill when the user asks to study, check, compare, or reference the Odyseus project (`D:\Fresh_Start\Testing stuff\Odyseus`) for a feature they want to understand or build in Proteus.910## Procedure11121. **Identify the feature** the user wants to study (memory, cookbook, agents, tools, auth, providers, UI, etc.)132. **Look up file paths** in the Odyseus map below143. **Read the relevant source files** (code first, not markdown)154. **Compare with Proteus** — what exists, what's missing, what's different165. **Present findings** as a concise diff/summary, then recommend next steps1718## Odyseus Codebase Map1920Root: `D:\Fresh_Start\Testing stuff\Odyseus`2122### Core Architecture2324| Area | Key Files | What's There |25|------|-----------|-------------|26| **App entry** | `app.py` | FastAPI app, router mounting, static files |27| **Config** | `src/config.py` | Settings, env vars, feature flags |28| **Auth** | `core/auth.py` | JWT creation/verification, Fernet encryption |29| **Database** | `core/database.py` | SQLAlchemy engine, session, TypeDecorators |30| **Models** | `core/models.py` | All SQLAlchemy models (User, Session, Memory, etc.) |3132### Memory System3334| Area | Key Files | What's There |35|------|-----------|-------------|36| **Memory manager** | `services/memory/` | CRUD, recall, pin, dedup, context injection |37| **Memory extractor** | `services/memory_extractor.py` | LLM-based fact extraction from chat |38| **Vector store** | `src/vector_store.py` | Chroma PersistentClient, collection management |39| **Embeddings** | `src/embeddings.py` | fastembed wrapper, `@lru_cache` singleton |40| **Memory routes** | `routes/memory_routes.py` | `/api/memory` CRUD, `/recall` endpoint |4142### Cookbook / Model Management4344| Area | Key Files | What's There |45|------|-----------|-------------|46| **Catalog builder** | `scripts/add_hwfit_models.py` | HF Hub fetch, 5-layer param extraction, JSON merge |47| **Catalog data** | `data/cookbook_catalog.json` | 911+ model entries with fit scores |48| **Fit scoring** | `services/hwfit/fit.py` | GPU bandwidth table, use-case weights, 4-component scoring |49| **Hardware detection** | `services/hardware.py` | nvidia-smi, RAM, CPU, 24h cache |50| **Cookbook routes** | `routes/cookbook_routes.py` | `/api/cookbook/hf-trending`, `/hardware` |51| **Local scanner** | `services/local_scanner.py` | HF cache + Ollama + user dirs, 4-source scan |5253### Agent / Tool System5455| Area | Key Files | What's There |56|------|-----------|-------------|57| **Tool schemas** | `src/tool_schemas.py` | ~60+ tool definitions (1372 lines) |58| **Tool implementations** | `src/tool_implementations.py` | `do_*` functions (4457 lines) |59| **Tool execution** | `src/tool_execution.py` | Dispatcher, admin checks, MCP routing (1557 lines) |60| **Agent loop** | `services/agent_loop.py` | ReAct loop, tool dispatch, streaming |61| **Goal system** | `services/goal_manager.py` | Goal condition, attempts, pause/resume |6263### Provider / Model Endpoints6465| Area | Key Files | What's There |66|------|-----------|-------------|67| **Provider presets** | `routes/model_endpoints.py` | Known providers (Groq, OpenAI, etc.), `/presets` |68| **Provider probe** | `services/provider_probe.py` | Test API key, list models, honest error reporting |69| **Model picker** | `static/js/modelPicker.js` | Client-side model selection UI (720 lines) |70| **Models list** | `static/js/models.js` | Model list with favorites, usage tracking (642 lines) |71| **Provider logos** | `static/js/providers.js` | Regex → SVG logo mapping (140 lines) |7273### Frontend / UI7475| Area | Key Files | What's There |76|------|-----------|-------------|77| **Chat UI** | `static/js/chat.js` | Main chat logic, SSE streaming, tool rendering |78| **CSS** | `static/css/style.css` | All styles, dialog system, provider forms |79| **HTML** | `templates/chat.html` | Chat page, dialogs, auth overlay |80| **Static mount** | `app.py` | `DevStaticFiles` with cache-control headers |8182### Sessions / Goals8384| Area | Key Files | What's There |85|------|-----------|-------------|86| **Session routes** | `routes/session_routes.py` | CRUD, goal CRUD, history |87| **Goal events** | SSE in `chat_routes.py` | `goal_started`, `goal_progress`, `goal_achieved`, `goal_failed`, `goal_paused` |8889### Testing9091| Area | Key Files | What's There |92|------|-----------|-------------|93| **Test config** | `tests/conftest.py` | In-memory SQLite, temp Chroma, JWT secret |94| **Memory tests** | `tests/test_memory.py` | 32 unit tests with mock embedder |95| **Route tests** | `tests/test_memory_routes.py` | 13 route tests with dep overrides |96| **Chat integration** | `tests/test_chat_memory_integration.py` | 6 tests with mocked stream_chat |97| **Goal tests** | `tests/test_goal.py` | 10+ dispatch tests with async generator stubs |98| **Secret storage** | `tests/test_secret_storage.py` | 7 Fernet encryption tests |99100## Proteus vs Odyseus — Quick Reference101102| Feature | Odyseus | Proteus | Status |103|---------|---------|---------|--------|104| Memory | 3-layer (SQL + Chroma + extractor) | Memory manager + Chroma + React UI | ✅ Built |105| Cookbook catalog | `add_hwfit_models.py` + `cookbook_catalog.json` | `cookbook_routes.py` + `data/cookbook_catalog.json` | ✅ Built |106| Local scanner | `local_scanner.py` (4 sources) | `local_scanner.py` (4 sources) | ✅ Built |107| Hardware detection | `services/hardware.py` | `services/hardware.py` | ✅ Built |108| Provider presets | `routes/model_endpoints.py` | `routes/model_endpoints.py` | ✅ Built |109| Auth | JWT + localStorage + auto-refresh + modal | JWT + localStorage + auto-refresh + modal | ✅ Built |110| Agent tools | 60+ tools (tool_schemas.py) | 9 tools (agent_loop.py) | ⚠️ Gap |111| MCP integration | Full MCP routing | Not implemented | ❌ Gap |112| Goal system | Goal condition + attempts + pause | Goal condition + attempts + pause | ✅ Built |113| UI framework | Vanilla JS + CSS | React + Vite + Tailwind + Radix | ✅ Built |114115## Usage Examples116117**User says:** "parent directory mai odyseus hai, usme memory kis tarhan kaam krti hai"118→ Look up Memory section, read `services/memory/` files, compare with Proteus memory119120**User says:** "odyseus ka cookbook logic check kro"121→ Look up Cookbook section, read `scripts/add_hwfit_models.py` + `services/hwfit/fit.py`122123**User says:** "check odysseus tools, which can we add?"124→ Look up Agent/Tool section, read `src/tool_schemas.py`, compare with Proteus `agent_loop.py`125126**User says:** "odyseus ka UI dekho, clean hai"127→ Look up Frontend section, read `static/js/chat.js` + `static/css/style.css`, note design patterns128129## Notes130131- Odyseus is a **multi-user production app**; Proteus is **single-user MVP**132- Odyseus uses **vanilla JS + CSS**; Proteus uses **React + Tailwind**133- Always **read code first**, not markdown files, for accurate comparison134- Odyseus's `src/` is the Python backend; `static/` and `templates/` are the frontend135- When adapting features, simplify for single-user (no owner/tenant fields, no admin checks)
MuhammadMustafa18