# Proteus Study Odyseus

> 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.

- Skill: `muhammadmustafa18/proteus-study-odyseus` (Agent Skill)
- Install (CLI): `npx skillmds@latest add muhammadmustafa18/proteus-study-odyseus`
- Raw SKILL.md: https://api.skillmd.com/api/skills/muhammadmustafa18/proteus-study-odyseus/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MuhammadMustafa18 (https://skillmd.com/u/muhammadmustafa18)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/muhammadmustafa18/proteus-study-odyseus

---


# 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

1. **Identify the feature** the user wants to study (memory, cookbook, agents, tools, auth, providers, UI, etc.)
2. **Look up file paths** in the Odyseus map below
3. **Read the relevant source files** (code first, not markdown)
4. **Compare with Proteus** — what exists, what's missing, what's different
5. **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)