# Odysseus — Docker kasutusjuhend

Self-hosted AI töölaud. Vestlus, agendid, veebiotsing, dokumendid, e-post, märkmed, pilditöötlus.
Kataloog: `/opt/docker-compose/third/server/odysseus/`

## Arhitektuur

| Komponent | Asukoht | Ühendus |
|-----------|---------|---------|
| **Odysseus** | Docker konteiner (`odysseus_odysseus_1`) | port 3004 |
| **Ollama** (LLM) | Native systemd teenus | `host.docker.internal:11434` |
| **llama.cpp** (LLM) | Native protsess | `host.docker.internal:8070` |
| **ChromaDB** | Docker konteiner (`odysseus_chromadb_1`) | `chromadb:8000` (sisevõrk) |
| **SearXNG** | Docker konteiner (`odysseus_searxng_1`) | `searxng:8080` (sisevõrk) |
| **Ntfy** | Docker konteiner (`odysseus_ntfy_1`) | `ntfy:80` (sisevõrk) |
| **MCP Filesystem** | Docker konteiner (`mcp-filesystem-sse`) | `mcp-filesystem-sse:3100/mcp` |
| **GPU** | ROCm 7.2.2, gfx1151 (Radeon 8060S) | hostil |
| **Docker socket** | Hostilt mountitud | `/var/run/docker.sock` (ro) |

## Ligipääs

| Teenus | URL |
|--------|-----|
| Odysseus UI | http://100.87.1.24:3004 |
| Ollama API | http://100.87.1.24:11434 |
| llama.cpp API | http://100.87.1.24:8070/v1 |
| N8N | http://100.87.1.24:5678 |

## Sisselogimine

- **Kasutaja:** ardo
- **Parool:** failis `.env` (`ODYSSEUS_ADMIN_PASSWORD`)

## Chat vs Agent — millal kumba kasutada?

Odysseusel on kaks vestlusrežiimi, mida saab vahetada vestlusakna ülaosas olevast rippmenüüst:

### Chat režiim
Lihtne küsimus-vastus. LLM vastab ainult oma teadmistele tuginedes. Ei kasuta tööriistu.

**Kasuta kui:** tahad selgitust, kokkuvõtet, ideed. Ei vaja väliseid tööriistu.

### Agent režiim
LLM saab kasutada 60+ tööriista — veebiotsing, kalender, email, failid, brauser, käsurida. Mõtleb, planeerib, tegutseb.

**Kasuta kui:** vajad reaalset infot internetist, tahad kalendrisse lisada, soovid kirju lugeda, vajad failide lugemist/kirjutamist.

**Kumb on vaikimisi:** Kui valid vestluses "Web Search" linnukese, lülitub automaatselt Agent režiimi.

## MCP serverid

| Server | Transport | Tööriistu | Staatus |
|--------|-----------|-----------|--------|
| Built-in: Email | stdio | 14 | ✅ |
| Built-in: Browser | stdio | 29 | ✅ |
| Built-in: Memory | stdio | 1 | ✅ |
| Built-in: RAG | stdio | 1 | ✅ |
| Built-in: Image Gen | stdio | 1 | ✅ |
| **Filesystem** | **http (Streamable)** | **14** | ✅ |
| **Kokku** | | **60+** | |

### Browser MCP — kuidas kasutada?

Browser MCP annab Odysseusesse täisväärtusliku brauseri (Chromium). Chat aknast saad anda käsklusi Agent režiimis:

```
"Mine lehele ilm.ee ja ütle mis ilm homme Tallinnas tuleb"
"Tee ekraanipilt lehest [url]"
"Otsi Google'ist 'Eesti teadusfond' ja võta kokku esimene tulemus"
```

Brauser avaneb konteineris, külastab lehte, loeb sisu ja annab selle LLM-ile töötlemiseks.

### Filesystem MCP

| Tööriist | Näide |
|----------|-------|
| `list_directory` | "Näita mis failid on kataloogis /data" |
| `read_file` | "Loe faili /backups/log.txt" |
| `write_file` | "Kirjuta fail /backups/memo.txt sisuga: koosolek homme" |
| `search_files` | "Otsi kõiki .md faile /projects kaustast" |
| `create_directory` | "Loo uus kataloog /backups/2026" |

Lubatud kataloogid: `/data`, `/scripts`, `/backups`, `/projects/data`, `/projects/n8n`, `/projects/anythingllm`, `/projects/open-webui`

## Google Calendar + Gmail (CalDAV + IMAP)

| Konto | Tüüp | Staatus |
|-------|------|--------|
| `ardo.kubjas@gmail.com` | IMAP (email) | ✅ kirjade lugemine, vastamine |
| AI Calendar (`@group.calendar.google.com`) | CalDAV | ✅ sünkroonitud |
| Ardo isiklik (`ardokubjas@gmail.com`) | CalDAV | ✅ sünkroonitud |

**Kalendri sünkroonimine:** Ava Calendar leht → vajuta Sync. Odysseus tõmbab sündmused Google'ist ning edaspidi sünkivad muudatused kahesuunaliselt.

**NB!** Google CalDAV URL peab olema legacy formaadis:
```
https://www.google.com/calendar/dav/{calendar_id}/user
```
Uuem `apidata.googleusercontent.com` URL ei tööta App Passwordiga (401 Login Required).

**Kuidas kasutada:**
- "Lisa koosolek homme kell 14" → sündmus luuakse ja sünkib Google'sse
- "Mis mul neljapäeval plaanis on?" → loeb kalendrist
- "Tee kokkuvõte tänastest kirjadest" → emailide kokkuvõte

## Notes — märkmete süsteem

Odysseuse sisseehitatud märkmete ja nimekirjade süsteem (Google Keep stiilis).

### Kuidas kasutada

1. **Notes lehel (UI)** — ava `http://100.87.1.24:3004` → Notes (ikoon) → + uus märge
2. **Agent režiimis** — kirjuta: "manage_notes: add checklist with title 'Ostunimekiri' and items [{text: 'Piim'}, {text: 'Leib'}]"

**⚠️ Teadaolev piirang:** Agent eelistab MCP Filesystem tööriistu `manage_notes` asemel. Kui agent kirjutab faili `/projects/` asemel et kasutada Notes süsteemi, kasuta Notes lehte otse või kirjuta selgesõnaliselt `manage_notes` tool call.

### Toetatud tegevused

| Tegevus | Näide |
|---------|-------|
| Loo märge | `manage_notes add title="Ostunimekiri" content="osta piim"` |
| Loo checklist | `manage_notes add note_type="checklist" items=[...]` |
| Meeldetuletus | `manage_notes add title="Koosolek" due_date="homme kell 14"` |
| List kõik | `manage_notes action="list"` |
| Otsi | `manage_notes action="search" query="ostunimekiri"` |
| Kustuta | `manage_notes action="delete" id="e821b60f"` |

## N8N integratsioon

N8N jookseb aadressil `http://n8n:5678` (Odysseuse konteinerist).

**Kuidas kasutada:**
1. Loo N8N-s Webhook triggeriga workflow
2. Kopeeri webhook URL
3. Odysseusest Agent režiimis: "Käivita webhook http://n8n:5678/webhook/abc123"

## Dokumendid + RAG

Odysseuse Documents on sisseehitatud dokumendiredaktor.

1. Ava Documents → New Document → kirjuta Markdown formaadis
2. Vestluses ava dokument või kasuta `@` mainimist
3. RAG MCP tuvastab dokumendi sisu ja kasutab seda vastamisel

## Perioodilised ülesanded (Tasks)

| # | Task | Sagedus | Kell (EET) | Mudel |
|---|------|---------|-----------|-------|
| 1 | Task Runs puhastus | Esmaspäev | 06:00 | deepseek-v4-flash |
| 2 | Süsteemi tervisekontroll | Pühapäev | 09:00 | deepseek-v4-flash |
| 3 | Hommikune päevakava | Iga päev | 10:00 | deepseek-v4-flash |
| 4 | Hiiumaa ilmaennustus | Pühapäev | 11:00 | deepseek-v4-flash |

### Taskide käivitamine

- **Automaatselt** — jooksevad määratud kellaajal
- **Käsitsi webhook** — `curl -X POST http://localhost:7000/api/tasks/{task_id}/webhook/{token}`
- **UI Run now** — vajuta Tasks lehel Run now, aga **ära puutu Odysseuset** 1-2 minutit pärast seda (foreground monitor katkestab)

**NB!** `BACKGROUND_TASK_FOREGROUND_GATE=false` on seadistatud compose failis — taskid jooksevad ka siis kui Odysseus on kasutuses. Aga foreground monitor võib ikkagi katkestada kui brauseris on aktiivne tegevus.

### Taskide tulemuste vaatamine

- **Success** — tulemus `task_runs.result` väljas ja Reminders paneelis (kui output_target=reminder)
- **Aborted** — "Stopped by user" tähendab tavaliselt foreground monitori katkestust
- **Queued** — ootab vaba sloti või idle olekut

## Mudelid

| Mudel | Asukoht | Suurus | Kiirendus | Soovitus |
|-------|--------|--------|-----------|----------|
| qwen3:30b-fast | Ollama | 18 GB | ROCm GPU | ✅ igapäevane |
| deepseek-v4-flash | DeepSeek API | - | pilv | ✅ kiire, tool calling |
| ggml_gpt-oss-120b | llama.cpp | 59 GB | CPU | ⚠️ liiga suur, ainult lihtsad päringud |

**120B mudeli hoiatus:** 59 GB mudel 30 GB RAM-iga arvutil — swäpib tugevalt, vastused aeglased või tühjad. Soovitatav kasutada qwen3:30b-fast.

### DeepSeek mudelid taskides

DeepSeek mudelid olid peidetud, sest need ei ilmu `models_extra` listis (kuriteerimata mudelid). Fix: `pinned_models = ["deepseek-v4-flash", "deepseek-v4-pro"]` DeepSeek endpointil.

## CookBook

CookBook on mudelite halduse töölaud (HF allalaadimine, serveerimine). Hetkel seadistatud ainult kohalik server.

- **Server:** Local (`host=""`, `modelDir="/app/.cache/huggingface/hub"`)
- **Mudelid:** näitab ainult Ollama mudeleid (5 tk)
- **llama.cpp mudelid:** ei ilmu CookBookis — see on ootuspärane, CookBook on Ollama mudelite jaoks

**NB!** Ära muuda `endpoint_kind` väärtust `proxy` → `local` — see lõhub CookBooki SSH skaneeringu.

## Docker käsud

```bash
cd /opt/docker-compose/third/server/odysseus/

# Käivita
docker-compose up -d

# Peata
docker-compose down

# Taaskäivita
docker-compose restart odysseus

# Ehita uuesti + käivita (peale koodimuudatusi)
docker-compose up -d --build odysseus

# Logid
docker-compose logs -f odysseus
```

**NB!** docker-compose v1.29.2 `ContainerConfig` vea puhul kasuta:
```bash
docker stop odysseus_odysseus_1 && docker rm odysseus_odysseus_1
docker-compose up -d odysseus
```

## Vead ja tõrkeotsing

### "Internal server error" veebiotsinguga
Parandus: `chat_routes.py` real 590 lisatud `_explicit_web_intent = _search_enabled`

### "No model servers found" scanimisel
Kontrolli võrguühendust, `host.docker.internal` lahenduvust

### Browser MCP "not available"
`npx -y @playwright/mcp@latest --version` + restart

### 120B mudel ei vasta
Liiga suur RAM-i jaoks. Kasuta qwen3:30b-fast.

### Google CalDAV 401 Login Required
Kasuta legacy URLi: `https://www.google.com/calendar/dav/{id}/user` (mitte `apidata.googleusercontent.com`)

### Task "Stopped by user" / "Queued"
- Foreground monitor katkestab kui brauseris on tegevus
- Webhook trigger töötab usaldusväärsemalt kui UI Run now
- `BACKGROUND_TASK_FOREGROUND_GATE=false` aitab aga ei lahenda kõiki juhtumeid

### Notes — agent ei loo märget
Agent eelistab MCP Filesystem tööriistu. Lahendus:
1. Kasuta Notes lehte otse (UI)
2. Kirjuta selgesõnaline `manage_notes` tool call
3. Kui agent kirjutas faili `/projects/`, kustuta see käsitsi

### docker-compose v1 ContainerConfig viga
docker-compose v1.29.2 bug. Lahendus: eemalda konteiner käsitsi enne `up -d`.

## Portide konfliktid

| Port | Algne (upstream) | Meil | Põhjus |
|------|-----------------|------|--------|
| 7000 → host | 3004 | 3004 | 3003 oli playwright |
| SearXNG | 8080 | **8088** | 8080 oli weaviate |

## Olulised kataloogid

| Asukoht | Sisu |
|---------|------|
| `/opt/docker-compose/third/server/odysseus/` | Compose failid, .env, LOEMIND |
| `/opt/docker-compose/third/server/odysseus/repo/` | Git repo (dev branch) |
| `/opt/docker-compose/third/server/odysseus/.env` | Keskkonnamuutujad (paroolid, URL-id) |
| `/data/docker/odysseus/data/` | SQLite, seaded, sessioonid, üleslaadimised |
| `/data/docker/odysseus/logs/` | Logid |
| `/data/docker/odysseus/data/huggingface/` | Cookbook mudeli cache |
| `/data/docker/odysseus/data/cookbook_state.json` | CookBook serveri seadistus |
| `/data/docker/odysseus/data/user_prefs.json` | Kasutaja seaded (sh CalDAV kontod) |
| `/data/docker/odysseus/data/app.db` | Peamine andmebaas (SQLite) |

## Ajalugu

| Kuupäev | Muudatus |
|---------|----------|
| 2025-07-07 | Paigaldatud — kloonitud repo, ehitatud Docker pilt |
| 2025-07-07 | Võrk parandatud: `odysseus_default` → `main_ai_network` |
| 2025-07-07 | `_explicit_web_intent` bug parandatud chat_routes.py-s |
| 2025-07-07 | OLLAMA_BASE_URL + EMBEDDING seadistatud native ollama jaoks |
| 2025-07-07 | MCP Filesystem server lisatud (14 tools) |
| 2025-07-07 | Google CalDAV — AI kalender sünkroonitud |
| 2025-07-08 | Google CalDAV parandatud: URL legacy formaati (`google.com/calendar/dav`) |
| 2025-07-08 | Gmail IMAP kontrollitud — juba töötas |
| 2025-07-08 | Isiklik Google Calendar CalDAV lisatud |
| 2025-07-08 | Browser MCP (Playwright) paigaldatud — 29 tools |
| 2025-07-08 | N8N ühendus kontrollitud (`http://n8n:5678`) |
| 2025-07-12 | Hommikune päevakava + Süsteemi tervisekontroll taskid loodud |
| 2025-07-12 | Hiiumaa ilmaennustus task loodud (deepseek-v4-flash, native tool calling) |
| 2025-07-12 | `qwen3:30b-fast` num_ctx tõstetud 49152 → 131072 |
| 2025-07-16 | CookBook server seadistatud (Local, modelDir=/app/.cache/huggingface) |
| 2025-07-16 | Docker socket mountitud + `ODYSSEUS_ENABLE_HOST_DOCKER=true` |
| 2025-07-16 | Süsteemi tervisekontroll: `docker ps` töötab konteinerist |
| 2025-07-16 | Task Runs puhastus task loodud (iga esmaspäev) |
| 2025-07-16 | `_KEYWORD_HINTS` — eestikeelsed võtmesõnad lisatud (märge, märkme, jne) |
| 2025-07-16 | DeepSeek mudelid `pinned_models` kaudu taskide dropdownis nähtavaks |
| 2025-07-16 | `BACKGROUND_TASK_FOREGROUND_GATE=false` + foreground monitor fix |