1316 lines
131 KiB
Markdown
1316 lines
131 KiB
Markdown
# Fabled Assistant - Project Context
|
||
|
||
> **Purpose:** This file is the canonical reference for re-initializing Claude Code
|
||
> context on this project. **Update this file after every change session.**
|
||
|
||
## Session Checklist
|
||
> **IMPORTANT:** At the end of every change session, you MUST:
|
||
> 1. **Update this file** (`summary.md`) to reflect all architectural, data model,
|
||
> API, file structure, and roadmap changes made during the session.
|
||
> 2. **Commit all changes** with a descriptive commit message summarizing what was
|
||
> done (e.g., "Merge tasks into notes: single table with task attributes").
|
||
> Include file-level details in the commit body when the change is non-trivial.
|
||
|
||
## Last Updated
|
||
2026-03-16 — Fuzzy project resolution, accidental project creation guard, task embedding, briefing CalDAV fix, notes count query fix.
|
||
|
||
---
|
||
|
||
**2026-03-16 — Fuzzy project resolution + create_project guard:**
|
||
|
||
- `services/tools.py` — `_resolve_project` rewritten with 4-step lookup: (1) exact DB match, (2) `query in title` substring, (3) `title in query` reverse substring, (4) SequenceMatcher ≥ 0.55 fallback. Partial names like "Famous Supply" now reliably resolve to "Famous Supply Co." without the model creating a duplicate project.
|
||
- `services/tools.py` — `create_project` handler: similar-project checks (threshold 0.55) now run **before** the `confirmed` gate, so `confirmed=true` cannot bypass them. All call sites that duplicated the old inline substring logic replaced with `_resolve_project`.
|
||
- `services/tools.py` — Error messages on project-not-found no longer say "or create_project to create one"; they direct the model to `list_projects` instead. Tool description explicitly says never call `create_project` in response to a lookup failure.
|
||
- `routes/tasks.py` — Fire-and-forget `upsert_note_embedding` added to create and update task routes (was missing; tasks created via REST API weren't getting embeddings).
|
||
- `services/briefing_pipeline.py` — `await is_caldav_configured()` (was called without await — was a latent bug since `is_caldav_configured` became async).
|
||
- `services/notes.py` — Removed erroneous duplicate `count_query.where(Note.parent_id == parent_id)` that was applied inside the `no_project` branch.
|
||
|
||
---
|
||
|
||
**CI release process (2026-03-12):**
|
||
- `.forgejo/workflows/ci.yml`: removed `main` from `branches` push trigger. CI now fires only on `dev` pushes, `v*` tags, and pull requests. Main branch merges no longer trigger a run — the PR check covers pre-merge safety. Production release process: create a release via Forgejo UI on `main` with a `v*` tag → tag push event fires CI → build job pushes `:latest` + `:<version>` Docker images to registry. Branch protection is not an obstacle because the UI release creates the tag through the API.
|
||
|
||
---
|
||
|
||
**Daily Briefing — full feature (2026-03-11):**
|
||
|
||
Backend:
|
||
- Migration `0026_add_briefing_tables.py`: `rss_feeds` (url, name, user_id), `rss_items` (feed_id FK, guid, title, url, summary, pub_date), `weather_cache` (user_id UNIQUE, lat, lon, location_name, forecast_json, fetched_at); added `conversation_type` TEXT and `briefing_date` DATE to `conversations`.
|
||
- `models/rss_feed.py`, `models/rss_item.py`, `models/weather_cache.py`: SQLAlchemy models with `to_dict()`.
|
||
- `services/weather.py`: geocoding via Nominatim (Open-Meteo), forecast fetch via Open-Meteo API, per-user DB cache with change detection. `get_weather(user_id)` returns structured dict with location, current, and 5-day forecast.
|
||
- `services/rss.py`: feedparser-based fetch, per-feed DB cache with prune-to-100. `get_rss_items(user_id, limit)` returns recent items across all user feeds.
|
||
- `services/briefing_profile.py`: service that reads user briefing config (CalDAV, weather, RSS, office days, tasks) and composes a profile note used as context for generation.
|
||
- `services/briefing_pipeline.py`: two-lane parallel gather (async `asyncio.gather` over weather, RSS, tasks, calendar) → LLM synthesis. Streams result into a `GenerationBuffer` using the same SSE infrastructure as chat.
|
||
- `routes/briefing.py`: RSS CRUD at `/api/briefing/feeds`, weather config at `/api/briefing/weather`, briefing config at `/api/briefing/config`, `POST /api/briefing/trigger` to manually fire a slot. Registered as `briefing_bp` in `app.py`.
|
||
- `routes/chat.py`: `GET /api/briefing/conversations/today` — creates the day's briefing conversation if absent (type=`briefing`, `briefing_date=today`); `GET /api/briefing/conversations` — lists all past briefing conversations.
|
||
- `services/generation_task.py` / `routes/chat.py`: `conversation_type` filter support so briefing conversations are excluded from the main chat list and vice versa.
|
||
- APScheduler integration: `services/scheduler.py` runs briefing slots (morning, midday, evening) on schedule with catch-up logic — if a slot was missed while the server was down, it runs immediately on next startup.
|
||
- LLM tools: `get_weather` and `get_rss_items` added to `_CORE_TOOLS` in `services/tools.py`.
|
||
|
||
Frontend:
|
||
- `frontend/src/views/BriefingView.vue` (new): primary briefing page. Soft chat-style layout. Top section shows the digest card (expandable) followed by the conversation thread. Reply bar at bottom — sends via standard chat endpoints and streams via SSE. Manual "Refresh" button triggers a new briefing generation. Conversation history dropdown (past briefing dates) in header.
|
||
- `frontend/src/components/BriefingSetupWizard.vue` (new): 4-step setup wizard shown on first visit when briefing is not configured (welcome → location → office days → RSS feeds). Completes by enabling briefing in settings.
|
||
- `frontend/src/views/SettingsView.vue`: Briefing tab added (`briefing` in `VALID_TABS`): enable toggle, location geocoding input (live preview), office days checkboxes, time slot toggles (morning/midday/evening), RSS feed CRUD (add URL + name, list, delete), push notification toggle for briefing completion.
|
||
- `frontend/src/router/index.ts`: `/briefing` route added → `BriefingView`.
|
||
- `frontend/src/components/AppHeader.vue`: "Briefing" nav link added.
|
||
|
||
---
|
||
|
||
**Previous session (2026-03-11):**
|
||
|
||
**Version footer + CalVer tracking:**
|
||
- `4636c9a` Add CalVer build-time version tracking: `Dockerfile` injects `BUILD_VERSION` ARG as `VITE_APP_VERSION` env var during frontend build. Frontend reads `import.meta.env.VITE_APP_VERSION` and displays it in the Settings footer. Docker image tags include `:<version>` on release builds.
|
||
- `2cb4e6d` Version footer, task history UI, note version retention policy: Settings page shows `v<version>` in footer. Task history now displays inline in a sidebar within the task editor (previously required navigation). Note version retention policy configurable (max versions per note, default 20 — enforced at write time in `services/note_versions.py`).
|
||
|
||
**Content deduplication + history sidebar:**
|
||
- `6d593a0` Move history to sidebar, simplify task assist, add content deduplication: `HistoryPanel` moved to a collapsible right sidebar in `NoteEditorView` (previously a modal overlay). Writing assist panel simplified — removed multi-step UX, direct instruction input. `build_context()` in `services/llm.py` deduplicates injected content (RAG-found notes, sidebar includes, context notes) by ID so the same note cannot appear in multiple context blocks.
|
||
|
||
**ShareDialog CSS fix:**
|
||
- `a63f067` Fix ShareDialog transparent background — replaced undefined CSS custom property references with explicit values.
|
||
|
||
---
|
||
|
||
**Previous session (2026-03-11 — Multi-user & backup):** Multi-user sharing & collaboration, in-app notifications, groups management, backup rewrite.
|
||
|
||
**Multi-user sharing & collaboration:**
|
||
- `alembic/versions/0025_add_sharing_and_notifications.py` (new): creates `groups`, `group_memberships`, `project_shares`, `note_shares`, `notifications` tables. Partial unique indexes via raw SQL. CHECK constraint enforces exclusive user/group target on share rows.
|
||
- `src/fabledassistant/models/group.py` (new): `Group` + `GroupMembership` SQLAlchemy models.
|
||
- `src/fabledassistant/models/share.py` (new): `ProjectShare` + `NoteShare` models with `shared_with_user_id`, `shared_with_group_id`, `permission`, `invited_by` columns.
|
||
- `src/fabledassistant/models/notification.py` (new): `Notification` model with `type`, `payload` (JSONB), `read_at`.
|
||
- `src/fabledassistant/models/__init__.py`: exports all three new model groups.
|
||
- `src/fabledassistant/services/access.py` (new): `PERMISSION_RANK` dict (`viewer=1 editor=2 admin=3 owner=4`). `get_project_permission(uid, project_id)` and `get_note_permission(uid, note_id)` — check ownership, direct share, group-based share, and note→project inheritance; return highest permission string or `None`. Helper predicates: `can_read_*`, `can_write_*`, `can_admin_*`.
|
||
- `src/fabledassistant/services/groups.py` (new): `create_group`, `list_groups`, `update_group`, `delete_group`, `add_member`, `update_member_role`, `remove_member`.
|
||
- `src/fabledassistant/routes/groups.py` (new): CRUD at `/api/groups` and `/api/groups/:id`; member management at `/api/groups/:id/members/:uid`.
|
||
- `src/fabledassistant/services/sharing.py` (new): `share_project/note`, `update_project/note_share`, `remove_project/note_share`, `list_project/note_shares`, `list_shared_with_me`.
|
||
- `src/fabledassistant/routes/shares.py` (new): project shares at `/api/projects/:id/shares`, note shares at `/api/notes/:id/shares`, `GET /api/shared-with-me`.
|
||
- `src/fabledassistant/services/notifications.py`: extended with `create_in_app_notification`, `notify_project_shared`, `notify_note_shared`, `notify_group_added`, `list_in_app_notifications`, `unread_notification_count`, `mark_notification_read`, `mark_all_notifications_read`.
|
||
- `src/fabledassistant/routes/in_app_notifications.py` (new): `GET /api/notifications`, `GET /api/notifications/count`, `POST /api/notifications/:id/read`, `POST /api/notifications/read-all`.
|
||
- `src/fabledassistant/routes/users.py` (new): `GET /api/users/search?q=` — username/email prefix search, min 2 chars, excludes self.
|
||
- `src/fabledassistant/services/projects.py`: added `get_project_for_user(accessing_uid, project_id)` → `(Project, perm) | None` and `list_projects_for_user(uid)` (owned + shared).
|
||
- `src/fabledassistant/services/notes.py`: added `get_note_for_user(accessing_uid, note_id)` → `(Note, perm) | None`.
|
||
- `src/fabledassistant/routes/projects.py`: `list_projects_route` uses `list_projects_for_user`; `get_project_route` uses `get_project_for_user` and adds `permission` field; `get_project_notes_route` access-checks via `get_project_for_user`.
|
||
- `src/fabledassistant/routes/notes.py`, `routes/tasks.py`: `get_note_route`/`get_task_route` use `get_note_for_user` and add `permission` field.
|
||
- `src/fabledassistant/app.py`: registers `groups_bp`, `shares_bp`, `notifications_bp`, `users_bp`.
|
||
|
||
**Frontend — sharing & notifications:**
|
||
- `frontend/src/api/client.ts`: added `ShareEntry`, `GroupEntry`, `GroupMember`, `NotificationEntry`, `UserSearchResult` TypeScript interfaces and API helper functions for all new endpoints.
|
||
- `frontend/src/stores/notifications.ts` (new): Pinia store — `count`, `items`, `fetchCount`, `fetchAll`, `markRead`, `markAll`.
|
||
- `frontend/src/components/NotificationBell.vue` (new): bell SVG icon with unread count badge, document-click-outside close, 60s polling interval, toggles `NotificationsPanel`.
|
||
- `frontend/src/components/NotificationsPanel.vue` (new): absolute-positioned dropdown listing unread notifications by type icon, bold inviter name, relative timestamp. "Mark all read" button. Click navigates to `payload.url`.
|
||
- `frontend/src/components/ShareDialog.vue` (new): `<Teleport to="body">` modal. Props: `resourceType: 'project' | 'note'`, `resourceId`, `resourceTitle`. User tab: debounced user search dropdown + permission select + Add button. Group tab: group picker + permission select. Current shares list with inline permission change and remove.
|
||
- `frontend/src/views/SharedWithMeView.vue` (new): `/shared` route. Grid of shared projects (color bar, title, owner, permission badge). List of shared notes/tasks (icon, title, owner, permission badge).
|
||
- `frontend/src/components/AppHeader.vue`: `NotificationBell` added to `nav-right` before the `?` button; "Shared" nav link added to desktop center nav and mobile menu.
|
||
- `frontend/src/views/ProjectView.vue`: "Share" button + `showShare` ref + `<ShareDialog>` at template bottom.
|
||
- `frontend/src/views/NoteViewerView.vue`: "Share" button in toolbar + `<ShareDialog>` after layout root.
|
||
- `frontend/src/views/TaskViewerView.vue`: "Share" button in toolbar + `<ShareDialog>` after layout root.
|
||
- `frontend/src/views/SettingsView.vue`: "groups" added to `VALID_TABS`; Groups admin tab added to sidebar. Groups panel: create group form, groups list with member count, per-group "Manage" panel with user search + role select + add, member list with per-member remove.
|
||
- `frontend/src/router/index.ts`: `/shared` → `SharedWithMeView` route added.
|
||
|
||
**Backup rewrite:**
|
||
- `src/fabledassistant/services/backup.py`: full rewrite to version 2. `export_full_backup()` and `export_user_backup()` now include all tables: projects, milestones, task logs, note drafts (AI draft model), note versions, push subscriptions. `restore_full_backup()` dispatches to `_restore_v1()` or `_restore_v2()` by version key. `_restore_v2()` builds ID maps (`user_id_map`, `project_id_map`, `milestone_id_map`, `note_id_map`); two-pass note restore patches `parent_id` after all notes are inserted.
|
||
|
||
---
|
||
|
||
**Previous session (2026-03-10):** Feature batch: workspace view, graph view, settings tabs, message queue persistence, ToolCallCard direct-API confirm, duplicate detection scoping, push notification fixes.
|
||
|
||
**UI polish pass — design language:**
|
||
- `frontend/src/assets/theme.css`: added Fraunces Google Font import; `h1/h2/h3` use `font-family: 'Fraunces', Georgia, serif`; `--radius-md` 8→12px, `--radius-lg` 12→18px; added thin indigo-tinted scrollbars (4px); added bubble-specific CSS variables (`--color-bubble-user-*`, `--color-bubble-asst-shadow`); dark palette shifted from generic navy (#1a1a2e family) to slate-indigo (#111113 family).
|
||
- `frontend/src/components/AppLogo.vue`: logo book fill changed from `var(--color-text)` (black in light mode) to `var(--color-primary)` (indigo). Stroke updated to `color-mix(in srgb, var(--color-primary) 70%, transparent)`.
|
||
- `frontend/src/components/AppHeader.vue`: removed `border-bottom` from `.app-header`; nav brand uses Fraunces font; active nav link uses `inset 0 -2px 0 var(--color-primary)` underline instead of background fill.
|
||
- `frontend/src/components/ChatMessage.vue`: user bubble ghosted (transparent bg, thin border, muted text); assistant bubble elevated with left `2px solid var(--color-primary)` accent + shadow; assistant role label in Fraunces italic indigo; thinking block uses left-accent instead of full border.
|
||
- `frontend/src/views/ChatView.vue`: removed sidebar/header/context-sidebar borders; streaming bubble matches assistant style; active conversation item uses 15% indigo tint; send button and queued bubbles use indigo gradient + glow.
|
||
- `frontend/src/components/NoteCard.vue`, `TaskCard.vue`: removed `border: 1px solid`; replaced with whisper shadow (`0 1px 4px + 0 0 0 1px indigo tint`); elevated shadow on hover.
|
||
- `frontend/src/views/HomeView.vue`: `dashboard-response` uses left indigo accent + elevation shadow (no border); `dashboard-response-actions` border-top removed; quick-action-chip hover adds indigo bg tint; project-mini-card uses whisper shadow; ms-fill progress bars use `var(--color-primary)`; `.btn-cta` and `.btn-open-chat.prominent` use indigo gradient + glow; `.empty-state::before` adds decorative `✦` marker.
|
||
- `frontend/src/views/NotesListView.vue`: `.btn-new` and `.btn-cta` use indigo gradient + glow on hover.
|
||
|
||
**Design intent:** "Illuminated Transcript" — LLM responses are primary artifacts (elevated, card-like, indigo accent left-border), user prompts are subordinate margin notes (ghosted, recessed). Buttons with the gradient carry intentional weight. Borders replaced by shadow depth throughout.
|
||
|
||
---
|
||
|
||
**Previous session (2026-03-10):** Feature batch: workspace view, graph view, settings tabs, message queue persistence, ToolCallCard direct-API confirm, duplicate detection scoping, push notification fixes.
|
||
|
||
**Project Workspace (`/workspace/:projectId`):**
|
||
- `frontend/src/views/WorkspaceView.vue` (new): 3-panel layout (tasks / chat / notes) with CSS grid collapse. Panel toggles in ws-header. Conversation persisted to `localStorage` as `workspace_conv_{projectId}`; deleted on unmount only if brand-new and empty. `sendMessage()` passes `projectId` as both `ragProjectId` and `workspaceProjectId`; `think: true` always enabled. SSE watcher auto-loads note on `create_note`/`update_note`, refreshes task panel on `create_task`/`update_task`.
|
||
- `frontend/src/components/WorkspaceTaskPanel.vue` (new): tasks grouped by milestone (No Milestone first), collapsible groups, task detail slide-over with status cycle + milestone `<select>` + read-only markdown body + TaskLogSection + inline-confirm delete.
|
||
- `frontend/src/components/WorkspaceNoteEditor.vue` (new): list view (search, inline tags, inline delete) ↔ editor view (TipTap + TagInput + WordCount + Suggest button + autosave via `useAutoSave`).
|
||
- Entry point: "Open Workspace" button on `ProjectView.vue` page header.
|
||
- Height fix: `workspace-root` uses `height: 100%`; `app-content:has(.workspace-root)` switches to `overflow: hidden`.
|
||
- Backend: `workspace_project_id` accepted in POST body (`routes/chat.py`), threaded to `run_generation` and `build_context()`; injects system prompt with project title so agent passes `project="Title"` (not ID) to tools.
|
||
|
||
**Graph View (`/graph`):**
|
||
- `frontend/src/views/GraphView.vue` (new): D3 force-directed graph of all notes/tasks. Tag nodes as first-class nodes (string IDs `"tag:name"`); invisible project hub nodes attract project members. Physics panel with sliders: repulsion (110), link distance (80), link strength (0.50), hub pull (0.05), gravity (0.03). `forceX`/`forceY` for gravity (not `forceCenter`). Clicking tag node → `/notes?tags=name`. Note/task node → 340px slide-in peek panel (type badge, tags, rendered body, linked nodes; Escape/✕ closes). `peek-slide` CSS transition.
|
||
- Router: `/graph` route added to `frontend/src/router/index.ts`.
|
||
- Keyboard shortcut: bare `g` navigates to `/graph` (added to `App.vue`).
|
||
|
||
**Settings page tabs:**
|
||
- `frontend/src/views/SettingsView.vue`: fully rewritten with 6 tabs — General, Account, Notifications, Integrations, Data, Admin. Tab state persisted to `localStorage` key `settings_tab`. Admin tab only shown when `authStore.isAdmin`. Session invalidation button added in Admin tab (`POST /api/auth/invalidate-sessions`).
|
||
|
||
**Push notification fixes:**
|
||
- `frontend/public/sw.js`: suppresses notification if the relevant chat tab is already focused (`clients.matchAll()` visibility check before `showNotification`). Works over HTTPS only — Firefox shows "not supported" over plain HTTP.
|
||
- `src/fabledassistant/services/push.py`: errors in `_send_sync` promoted to `logger.error` with `exc_info=True`; successful sends logged at `logger.info`.
|
||
- `src/fabledassistant/services/generation_task.py`: tool-only responses (empty `content_so_far`) now synthesise push notification body from tool names (`"Completed: create_note, create_task"`) instead of sending an empty notification.
|
||
|
||
**Message queue improvements:**
|
||
- `frontend/src/components/DashboardChatInput.vue`: removed `|| store.streaming` from disabled checks — queue works on the dashboard widget.
|
||
- `frontend/src/stores/chat.ts`: queue persisted to `localStorage` key `fa_conv_queue_{convId}`; saved on enqueue/dequeue, restored in `fetchConversation`, removed on conversation delete. `queuedMessages` computed returns full `QueuedMessage[]` for current conv.
|
||
- `frontend/src/views/ChatView.vue` + `WorkspaceView.vue`: queued messages rendered as user-style bubbles (`linear-gradient(135deg, #6366f1, #4f46e5)`, `border-bottom-right-radius: 4px`, 18px radius, opacity 0.45, right-aligned via `.chat-message.role-user { justify-content: flex-end }`). "QUEUED" label in `rgba(255,255,255,0.75)`. Cancel button clears entire queue.
|
||
|
||
**ToolCallCard confirm/deny — direct API:**
|
||
- `frontend/src/components/ToolCallCard.vue`: confirm/deny buttons moved **inline in the header row** (no separate block). "Create anyway" posts directly to `POST /api/notes` or `POST /api/tasks` (inferred from `toolCall.function`); shows "✓ Created" on success, "Skipped" on deny — no LLM round-trip. Removed `useChatStore` dependency for these actions. `confirmState: 'idle' | 'creating' | 'created' | 'denied'` local ref.
|
||
- `src/fabledassistant/routes/notes.py` + `routes/tasks.py`: POST handlers now accept `project` (name string) and resolve to `project_id` via `get_project_by_title` when `project_id` not supplied directly.
|
||
|
||
**Duplicate detection fixes:**
|
||
- `src/fabledassistant/services/tools.py`: `create_note` and `create_task` now scope all three duplicate checks (exact title, fuzzy title, semantic similarity) to the same type only — `is_task=True` for `create_task`, `is_task=False` for `create_note`. A note and a task can share the same title without conflict.
|
||
- `src/fabledassistant/services/embeddings.py`: `semantic_search_notes()` gains `is_task: bool | None = None` parameter; filters SQL join to `Note.status.isnot(None)` / `Note.status.is_(None)` when set.
|
||
- Semantic similarity threshold raised 0.87 → 0.90; minimum body length raised 80 → 200 chars. Catches near-identical content (accidentally duplicated notes) while allowing topically-related notes (e.g. enemy design templates) to coexist.
|
||
|
||
**Abort button:**
|
||
- ■ Stop button in `ChatView.vue` header and `WorkspaceView.vue` input bar; calls `store.cancelGeneration()`.
|
||
|
||
**CI fix (ruff E741):**
|
||
- `src/fabledassistant/routes/task_logs.py`: renamed ambiguous variable `l` → `log` in list comprehension.
|
||
|
||
---
|
||
|
||
**Previous session (2026-03-10):** UI polish pass: "Illuminated Transcript" design language, Fraunces typography, indigo gradient buttons, shadow-based card depth, bubble hierarchy flip.
|
||
|
||
---
|
||
|
||
**Previous session (2026-03-10):** CI/CD optimization: custom runner base image, explicit label naming, pip caching, Node 22.
|
||
|
||
**CI/CD infrastructure overhaul:**
|
||
- `infra/Dockerfile.runner-base` (new): Ubuntu 24.04 base image with Python 3.12 (native, no PPA) and Node 22 LTS pre-installed. Tagged `py3.12-node22`. Eliminates the ~3-4 min deadsnakes PPA install that ran on every test job. Build/push command in file header.
|
||
- `infra/act-runner-config.yml`: added `runner.labels` section mapping `py3.12-node22` → `runner-base:py3.12-node22`. This is the authoritative label config — `GITEA_RUNNER_LABELS` env var is only honoured on first registration and was being ignored after `.runner` exists.
|
||
- `infra/runner-compose.yml`: removed redundant `GITEA_RUNNER_LABELS` env var (labels now owned solely by config.yml).
|
||
- `.forgejo/workflows/ci.yml`: all jobs changed from `runs-on: ubuntu-latest` → `runs-on: py3.12-node22`; removed deadsnakes Python install steps from test job; added `actions/cache@v3` for pip keyed on `hashFiles('pyproject.toml')`; bumped `node-version` 20 → 22.
|
||
- `Dockerfile`: bumped frontend build stage `node:20-alpine` → `node:22-alpine`.
|
||
- `.gitignore`: added `.claude/`, `settings.local.json`, `.vscodium/`.
|
||
|
||
**Runner label design:** Label name (`py3.12-node22`) matches the image tag, making the dependency contract explicit in workflow files. `ubuntu-latest` alias removed — it was opaque and implied a moving target.
|
||
|
||
**To activate on server (one-time):** copy `infra/act-runner-config.yml` → `/nfs/data/fabledsword/act_runner/config.yml`, delete `/data/.runner` in the runner container, restart the stack. Runner will re-register with the `py3.12-node22` label.
|
||
|
||
---
|
||
|
||
**Previous session (2026-03-06):** Session invalidation on credential change (password reset + password change).
|
||
|
||
**Session invalidation on credential change:**
|
||
- `models/user.py`: added `session_version: Mapped[int]` column (default 1). `Integer` import added.
|
||
- `alembic/versions/0024_add_session_version.py`: migration adds `session_version INTEGER NOT NULL DEFAULT 1` to `users`.
|
||
- `auth.py` (`_check_auth`): after loading user, checks `session["session_version"] == user.session_version`; mismatch → `session.clear()` + 401 "Session expired. Please log in again."
|
||
- `services/auth.py`:
|
||
- `change_password` return type changed from `bool` to `int | None` (returns new `session_version` on success, `None` on failure). Increments `user.session_version` before commit.
|
||
- `reset_password_with_token`: increments `user.session_version` before commit (invalidates all live sessions on password reset).
|
||
- `routes/auth.py`:
|
||
- `login`, `register`, `register_with_invite`, `oauth_callback`: now also set `session["session_version"] = user.session_version` alongside `session["user_id"]`.
|
||
- `update_password`: receives `new_version` from `change_password`; updates `session["session_version"] = new_version` so the current user's own session stays valid while all other sessions are invalidated.
|
||
- **Effect:** All existing sessions will require re-login once after the migration runs (existing cookies lack `session_version`, so they'll mismatch `1`). Subsequent credential changes immediately evict all other active sessions.
|
||
|
||
---
|
||
|
||
**DRY refactoring pass (backend):**
|
||
- `src/fabledassistant/models/base.py` (new): `TimestampMixin` (`created_at` + `updated_at`) and `CreatedAtMixin` (`created_at` only) — SQLAlchemy 2.0 `Mapped[]` mixins. Applied to all 10+ models (`Note`, `Project`, `Milestone`, `Conversation`, `Message`, `User`, `PushSubscription`, `TaskLog`, `NoteDraft`, `NoteVersion`), removing ~60 lines of duplicated column definitions.
|
||
- `src/fabledassistant/routes/utils.py` (new): `not_found(resource)` → `(Response, 404)` and `parse_iso_date(value, field)` → `date | None | (Response, 400)`. Used across `notes.py`, `tasks.py`, `projects.py`, `milestones.py`, `chat.py`, replacing ~18 inline 404 blocks and ~4 duplicate date-parsing try/except blocks.
|
||
- `routes/milestones.py`: `_milestone_dict(m)` local async helper replaces 5 repetitions of `entry = m.to_dict(); entry.update(await get_milestone_progress(m.id))`.
|
||
|
||
**DRY refactoring pass (frontend):**
|
||
- `frontend/src/composables/useAutoSave.ts` (new): `useAutoSave(dirty, saving, saveFn, intervalMs?)` — interval-based autosave with `onMounted`/`onUnmounted` lifecycle, guards on dirty+saving state.
|
||
- `frontend/src/composables/useEditorGuards.ts` (new): `useEditorGuards(dirty, saveFn)` — registers Ctrl+S handler, `beforeunload` warning, and `onBeforeRouteLeave` confirm guard.
|
||
- `frontend/src/composables/useTagSuggestions.ts` (new): `useTagSuggestions(title, body, tags, markDirty)` — encapsulates `/api/notes/suggest-tags` call and suggestion state.
|
||
- `frontend/src/composables/useFloatingAssist.ts` (new): `useFloatingAssist(onRequest)` — floating selection-based assist button positioning.
|
||
- `frontend/src/composables/useListKeyboardNavigation.ts` (new): `useListKeyboardNavigation<T>(items, navigateTo, rowSelector?, enabled?)` — j/k/Enter navigation with focus-in-input guard and optional `enabled` ref.
|
||
- `frontend/src/components/ConfirmDialog.vue` (new): reusable confirm modal. Props: `title`, `message`, `confirmLabel` (default "Delete"), `danger` (default true). Emits `confirm`/`cancel`. Uses `<teleport to="body">` internally.
|
||
- `frontend/src/assets/editor-shared.css`: added shared sidebar CSS (`.sidebar-toggle`, `.sidebar-content`, `.sb-field`, `.sb-label`, `.sb-select`, `.sb-input`, `.sb-divider` + mobile collapse rules) used by both editor views.
|
||
- `frontend/src/assets/viewer-shared.css` (new): shared context-breadcrumb CSS (`.context-bar`, `.ctx-crumb*`) imported by `NoteViewerView` and `TaskViewerView`.
|
||
- `NoteEditorView.vue`, `TaskEditorView.vue`: replaced ~120 lines each of duplicated floating-assist, tag-suggestion, autosave, and route-guard logic with composable calls; replaced inline `<teleport>` delete modal with `<ConfirmDialog>`; removed ~80 lines of duplicated scoped sidebar CSS.
|
||
- `NotesListView.vue`, `TasksListView.vue`: replaced inline `activeIndex`/`onKeydown`/`scrollActiveIntoView` keyboard-nav (~25 lines each) with `useListKeyboardNavigation`. TasksListView passes `isFlat` computed ref as `enabled` guard.
|
||
- `NoteViewerView.vue`, `TaskViewerView.vue`: removed ~40 lines of duplicate `.context-bar`/`.ctx-crumb*` scoped CSS; added `<style src="@/assets/viewer-shared.css" />`.
|
||
- No behaviour changes. Net: −634 lines, +237 lines across 31 files.
|
||
|
||
---
|
||
|
||
## Previous Session
|
||
2026-03-06 — Project-aware writing assist, link suggestions, project-scoped RAG, semantic note search tool, SSE done-event race fix, RAG snippet increase, sidebar include full body, Enter-to-submit assist.
|
||
|
||
**SSE done-event race fix:** `routes/notes.py` and `routes/chat.py` — The SSE stream generator had a race condition where `yield buf.format_sse(event)` hands control back to the event loop, allowing the generation task to set `buf.state = COMPLETED` and append the `done` event between the last yield and the state check. The loop would then break without delivering the `done` event (containing `full_text`). Fixed by adding a final drain loop after the `while` exits in both stream generators. Added INFO-level logging to `run_assist_generation` showing `input_chars`, `output_chars`, event count, and done-event index.
|
||
|
||
**RAG snippet + sidebar include:** `services/llm.py` — `RAG_AUTO_SNIPPET` raised from 800 to 4000 chars. Sidebar-included notes (`include_note_ids`) now deliver full body (`n.body or ""`) instead of the previous 2000-char truncation, matching the paperclip/context_note behaviour.
|
||
|
||
**Assist `MAX_BODY_CHARS`:** `services/assist.py` — raised from 8000 to 24000 chars, safely within the 16384-token Ollama context (input + output headroom considered).
|
||
|
||
**DiffView equal-line collapsing:** `DiffView.vue` — unchanged lines are now collapsed into `⋯ N unchanged lines` markers when a run of 6+ equal lines exists, showing only 3 lines of context around each change (git-style). Makes reviewing large-document diffs practical.
|
||
|
||
**Enter-to-submit assist textarea:** Both `NoteEditorView.vue` and `TaskEditorView.vue` — writing assistant instruction textareas now submit on plain Enter (Shift+Enter inserts newline). Uses `@keydown.enter.exact.prevent` with `canSubmit` guard.
|
||
|
||
**Project-aware writing assist:** `services/assist.py` — `build_assist_messages()` accepts `context_notes: list[dict] | None`; when provided, injects a `--- Project Context ---` block into the user message (before the document) listing related note titles, tags, and body previews. Instructs the model to use `[[wikilinks]]` for referenced concepts. `routes/notes.py` `assist_route` — accepts `project_id` and `note_id`; fetches up to 5 project notes as context: `definition`-tagged notes first (up to 3, always injected for canonical term definitions), then recently-updated notes fill remaining slots. `composables/useAssist.ts` — accepts `projectId?: Ref<number | null>` third param; includes `note_id` and `project_id` in the POST body. Both `NoteEditorView.vue` and `TaskEditorView.vue` pass their project ref to `useAssist`.
|
||
|
||
**Link suggestions:** `routes/notes.py` — new `POST /api/notes/link-suggestions` endpoint. Accepts `{body, project_id, exclude_note_id}`. Fetches all project note titles (up to 200), runs regex to find titles appearing as plain text outside `[[...]]` spans, returns `[{note_id, title, count}]` sorted by occurrence count. `NoteEditorView.vue` — new "Link Suggestions" sidebar section: fetches suggestions on mount and debounced 2s after each body edit (when project is set). Per-term "Link" button applies `[[Title]]` wrapping to all unlinked occurrences; "Link all" applies all at once. Text replacement splits on `[[...]]` spans to avoid double-linking.
|
||
|
||
**Project-scoped RAG:** `services/embeddings.py` `semantic_search_notes()` — new `project_id` param filters the SQL join to `Note.project_id == project_id`. `services/notes.py` `search_notes_for_context()` — same `project_id` filter. `services/llm.py` `build_context()` — new `rag_project_id` param threaded to both search functions. `services/generation_task.py` `run_generation()` + `routes/chat.py` `send_message_route` — `rag_project_id` accepted from POST body and passed through. `stores/chat.ts` `sendMessage()` — new `ragProjectId` param included in POST. `ChatView.vue` — `ProjectSelector` added to chat sidebar under "Scope notes to project" label; when set, all RAG (semantic + keyword fallback) restricts to that project's notes.
|
||
|
||
**Semantic note search tool:** `services/tools.py` `search_notes` — upgraded from pure keyword to hybrid semantic+keyword. Runs `semantic_search_notes()` first (threshold 0.40, broader than auto-inject 0.60 since this is an intentional query); merges keyword results for any not already found. Results include a `relevance` field (percentage for semantic, `"keyword"` for text matches). Added `project` parameter (resolves by name, same pattern as `list_notes`). Preview extended to 300 chars. Tool description updated to explain semantic capability. `services/llm.py` tool guidance updated to direct the model to use `search_notes` for conceptual/thematic queries. `generation_task.py` status label updated to "Searching notes (semantic)".
|
||
|
||
**Previous session (2026-03-06):** Code review fixes: SSRF guard, config validation, race condition handling, tag autocomplete SQL, note versions now store tags, unmount cleanup, stale log string, PATCH due_date validation.
|
||
|
||
**SSRF protection:** `services/llm.py` — new `_is_private_url(url)` helper uses `socket.getaddrinfo` + `ipaddress` to block requests to loopback, private, link-local, reserved, and multicast addresses before fetching. `follow_redirects` set to `False` (redirects to internal IPs would bypass the check). All web research and search_web tool calls go through `fetch_url_content`, so this covers the full pipeline.
|
||
|
||
**Config validation:** `config.py` — new `Config.validate()` classmethod checks `OLLAMA_NUM_CTX`, `LOG_RETENTION_DAYS`, `IMAGE_MAX_BYTES`, `SMTP_PORT` bounds, and `BASE_URL` format when OIDC is enabled. `app.py` — `Config.validate()` called at the top of `create_app()` so misconfigurations surface immediately with clear messages instead of cryptic runtime errors.
|
||
|
||
**create_buffer race:** `routes/chat.py` — wrapped `create_buffer(conv_id, assistant_msg.id)` in try/except RuntimeError → returns 409 instead of 500 if two concurrent requests race past the buffer-running check (which is possible because there are await points between the GET check and the create call).
|
||
|
||
**Stale log message:** `services/generation_task.py` — "90s" → "180s" in the model-load timeout warning.
|
||
|
||
**Tag autocomplete SQL:** `services/notes.py` — `get_all_tags()` now pushes the `q` filter into the SQL query (`ILIKE`) and adds `LIMIT 100` on both filtered and unfiltered paths, replacing the previous Python-side filter over a full table scan.
|
||
|
||
**Note versions now store tags:** Migration `0023_add_tags_to_note_versions.py` adds `tags TEXT[] NOT NULL DEFAULT '{}'` to `note_versions`. `models/note_version.py` — added `tags` field; `to_dict()` includes it. `services/note_versions.py` — `create_version()` accepts optional `tags` param. `services/notes.py` — snapshots `old_tags` before update, passes them to `create_version`. Frontend: `NoteVersion` interface (in `HistoryPanel.vue` and `types/task.ts`) updated with `tags: string[]`. `HistoryPanel.vue` — `restore` emit updated to include tags as second argument. `NoteEditorView.vue` — restore handler now restores both body and tags.
|
||
|
||
**useAssist unmount cleanup:** `NoteEditorView.vue` — added `onUnmounted(() => assist.clearSelection())` which closes any in-flight SSE stream handle, preventing orphaned server connections when navigating away mid-generate.
|
||
|
||
**PATCH due_date validation:** `routes/notes.py` — `date.fromisoformat()` in the PATCH handler now wrapped in try/except `(ValueError, TypeError)`, returning 400 with a clear message instead of a 500.
|
||
|
||
**Previous session (2026-03-06 earlier):** SSE reconnection for chat and writing assist.
|
||
|
||
**SSE reconnection — chat:** `stores/chat.ts` — new `reconnectIfGenerating(convId)` function exported from the store. Checks `isStreamingConv` first (skips if stream already active). Finds the last assistant message with `status: 'generating'`, removes it from the messages array (the `done` event re-adds the final version), initialises stream state with `status: "Reconnecting..."`, then calls `_streamGeneration` which replays all buffered events from `last_event_id=-1`. If the buffer is >60s stale (already cleaned up), `_streamGeneration` exhausts its retries and falls back to `fetchConversation` to show the DB-saved final content. `ChatView.vue` — `reconnectIfGenerating` called (fire-and-forget, no await) in both `onMounted` and `watch(convId)` after the fetch step, covering both the page-refresh and navigate-away-and-back scenarios.
|
||
|
||
**SSE reconnection — writing assistant:** `composables/useAssist.ts` — extracted `_buildProposedFullBody()` helper. `submit()` now wraps the SSE connection in a retry loop (up to 3 retries, exponential back-off 1 s / 2 s / 4 s, capped at 5 s). Tracks `lastEventId`; reconnects use `?last_event_id=N` so only new chunks are received (no duplication). Loop breaks early on `done`, `error`, or if state left `'streaming'` (user cancelled). Falls back to accumulated text as draft on exhausted retries.
|
||
|
||
**Model load timeout:** `generation_task.py` — `wait_for_model_loaded` timeout raised from 90 s to 180 s.
|
||
|
||
**Previous session (2026-03-05):** Note editor sidebar layout, full-document writing assist, persistent drafts, version history, context window bump.
|
||
|
||
**Note editor sidebar layout:** `NoteEditorView.vue` fully refactored into two-column layout matching `TaskEditorView`. Right sidebar (280px) contains Project, Milestone, Tags + tag suggestions, and the Writing Assistant panel (always visible, no toggle). Mobile collapses to accordion. Removed `assistOpen` ref and `✨ Assist` toggle button. `InlineAssistPanel` removed from note editor.
|
||
|
||
**Full-document writing assist:** `services/assist.py` — new `whole_doc: bool` param with a separate system prompt that instructs the model to output the complete revised document. `routes/notes.py` — `whole_doc` accepted from POST body; validation updated (section mode requires `target_section`, both modes require `instruction`). `composables/useAssist.ts` — added `scopeMode` ref (`'document' | 'section'`), `proposedFullBody` ref (full body after section replacement or whole-doc output), updated `diff` to always compare full document snapshots (`bodySnapshot → proposedFullBody`). Scope dropdown in sidebar drives `scopeMode` and `selectedSection`. `canSubmit` no longer requires a target in document mode. `selectSection()` and `selectTextRange()` now set `scopeMode = 'section'` automatically.
|
||
|
||
**DiffView.vue:** New standalone component (`frontend/src/components/DiffView.vue`). Full-width, flex-fills available height. Sticky summary bar (insertions / deletions count). Scrollable monospace diff body. Replaces the editor main area during review state.
|
||
|
||
**Main area state switching (NoteEditorView):** streaming → stream preview (rendered markdown); review → `DiffView` full-width; idle → normal Write/Preview/TiptapEditor.
|
||
|
||
**Persistent drafts — backend:** Migration `0022_add_note_versions_and_drafts.py` — `note_drafts` table (UNIQUE per `note_id + user_id`; fields: `proposed_body`, `original_body`, `instruction`, `scope`) and `note_versions` table (max 20 per note; fields: `body`, `title`, `created_at`). Models `models/note_draft.py`, `models/note_version.py`. Added imports to `models/__init__.py`. Services `services/note_drafts.py` (`upsert_draft` via INSERT … ON CONFLICT, `get_draft`, `delete_draft`) and `services/note_versions.py` (`create_version` with auto-prune to 20, `list_versions`, `get_version`). `services/notes.py` `update_note()` — snapshots old body/title before applying changes; calls `create_version` when body actually changes. Routes in `routes/notes.py`: `GET/PUT/DELETE /api/notes/<id>/draft`, `GET /api/notes/<id>/versions`, `GET /api/notes/<id>/versions/<vid>`.
|
||
|
||
**Persistent drafts — frontend:** `useAssist.ts` — accepts optional `noteId: Ref<number | null>` second param; saves draft via `PUT /api/notes/<id>/draft` after `done` event; `loadDraft(draft)` restores `bodySnapshot`, `proposedFullBody`, `instruction`, `scopeMode`, and sets state to `'review'`; `accept()` and `reject()` call `DELETE /api/notes/<id>/draft`. `NoteEditorView.vue` — on mount, after note loads, fetches draft and calls `assist.loadDraft()` if one exists. `NoteDraft` interface exported from `useAssist.ts`; `NoteDraft` + `NoteVersion` interfaces added to `frontend/src/types/task.ts`.
|
||
|
||
**Version history browser:** `HistoryPanel.vue` — wide modal (900px, 80vh), version list on left (lazy body loading), `DiffView` on right (selected version vs current body), Restore button emits body to parent. `NoteEditorView.vue` — "History" toolbar button, renders `<HistoryPanel>` with restore handler (`body = $event; markDirty()`).
|
||
|
||
**Context window + output token limits:** `OLLAMA_NUM_CTX` default raised from 16384 to 65536 in `config.py` (overridable via env var; comment updated to remove stale VRAM reference). `run_assist_generation` in `generation_task.py` — `num_predict` changed from hardcoded 4096 to `Config.OLLAMA_NUM_CTX`, so assist output budget always matches the configured context window.
|
||
|
||
**Previous session (2026-03-05 earlier):** Fix writing assist: disable thinking mode, drop stuck-buffer 409.
|
||
|
||
**Task Work Log (backend):** New `task_logs` table (migration `0021_add_task_logs.py`) with FK to `notes(id)` CASCADE and `users(id)` CASCADE, indexes on `task_id` and `user_id`. SQLAlchemy model `models/task_log.py`. Service `services/task_logs.py` with `create_log`, `list_logs`, `update_log` (uses `_UNSET` sentinel so `None` can explicitly clear `duration_minutes`), `delete_log` — all ownership-checked. Blueprint `routes/task_logs.py` registered in `app.py` at `/api/tasks/<task_id>/logs` (GET, POST, PATCH `/<log_id>`, DELETE `/<log_id>`). LLM tool `log_work` added to `_CORE_TOOLS` in `services/tools.py`: resolves task by title, calls `create_log`, returns `{success, log, task}`.
|
||
|
||
**Task Work Log (frontend):** `TaskLog` interface added to `frontend/src/types/task.ts`. `TaskLogSection.vue` component (props: `taskId`) — renders logs ASC with date+time timestamps (not just date, so multiple same-day entries are distinguishable), duration badge, inline edit (textarea + duration field + Save/Cancel), markdown rendering via `renderMarkdown`. New-entry textarea has `autofocus`. Integrated below TiptapEditor in `TaskEditorView.vue`.
|
||
|
||
**Writing assistant — reliability (Pass 1):** `services/generation_task.py` `run_assist_generation` now retries up to 3 times on HTTP 500, with `3s × attempt` delay and `buf.content_so_far` reset between attempts. `composables/useAssist.ts`: removed `chatStore.chatReady` gate from `canSubmit` (chat store no longer needed; Ollama errors surface via backend response); replaced with `useToastStore` for error toasts on SSE error events, catch blocks, and accept-conflict detection.
|
||
|
||
**Writing assistant — inline UX (Pass 2):** New `InlineAssistPanel.vue` component renders streaming preview (animated pulse + live markdown) and diff review (monospace red/green diff or full-text toggle + Accept/Reject) directly in the editor column. The right-hand assist side panel now only shows the instruction input (idle state); streaming and review output moved inline. `.assist-active-hint` style added to `editor-shared.css`. Both `NoteEditorView.vue` and `TaskEditorView.vue` updated: `assistLabel` computed from the target section title, `InlineAssistPanel` rendered between MarkdownToolbar and TiptapEditor, aside restricted to idle/error states.
|
||
|
||
**Task editor UI overhaul:** `TaskEditorView.vue` restructured into a two-column layout: left `.task-main` (Write/Preview tabs + MarkdownToolbar + InlineAssistPanel + TiptapEditor + TaskLogSection) and right `.task-sidebar` (280px, all metadata: status, priority, due date, project, milestone, parent task, sub-tasks, tags + suggest). Title remains full-width above both columns. Sidebar collapses to an accordion on `max-width: 720px` (toggle button hidden on desktop). `sidebarOpen` ref defaults to `true`. Body tab defaults to Preview (`showPreview = ref(true)`).
|
||
|
||
**Previous session (2026-03-04):** Per-conversation streaming state + auto-new-chat on open. Keyboard navigation overhaul.
|
||
|
||
## Project Overview
|
||
Fabled Assistant is a self-hosted note-taking and task-tracking application with
|
||
integrated LLM capabilities. It is designed to run on container infrastructure
|
||
(Docker Swarm) and connect to Ollama or any self-hostable LLM-compatible system
|
||
for AI-assisted features.
|
||
|
||
## Core Architecture
|
||
|
||
### Stack
|
||
| Layer | Technology | Notes |
|
||
|-------------|-----------|-------|
|
||
| Frontend | Vue 3 + TypeScript + Vite + Pinia + Vue Router | SPA served from the same container as the API |
|
||
| Backend/API | Quart (Python 3.12) | Async framework; serves both API and built frontend static files |
|
||
| LLM | Ollama | Or any OpenAI-compatible self-hosted LLM API |
|
||
| Database | PostgreSQL 16 | asyncpg driver, SQLAlchemy 2.0 async ORM, Alembic migrations |
|
||
| Deployment | Docker Compose | Single-container app + separate DB + LLM service |
|
||
|
||
### Key Design Decisions
|
||
- **Single container for frontend + API:** Quart serves the Vue.js production
|
||
build as static files and exposes the REST API under `/api/`.
|
||
- **Quart chosen for familiarity:** The maintainer (bvandeusen) knows Quart well.
|
||
- **SPA routing via 404 handler:** `app.py` uses `@app.errorhandler(404)` (not a
|
||
catch-all route) to serve static files or fall back to `index.html`. API routes
|
||
(`/api/*`) get JSON 404 responses. This avoids a catch-all `/<path:path>` route
|
||
intercepting API GETs.
|
||
- **LLM integration is a separate service:** The app communicates with Ollama (or
|
||
compatible) over HTTP.
|
||
- **First-class tag field:** Tags live in the `tags ARRAY[text]` column and are
|
||
explicitly set by the client — they are NOT auto-extracted from the body text.
|
||
`extract_tags()` in `utils/tags.py` is preserved but no longer called on save.
|
||
`TagDecoration.ts` keeps visual `#tag` highlighting in existing notes that have
|
||
inline tags for cosmetic backward compatibility.
|
||
- **Hierarchical tags:** `#project/webapp` stored as `"project/webapp"`. Filtering
|
||
by `project` matches both `project` and `project/*` children via SQL `unnest` +
|
||
`LIKE` prefix.
|
||
- **Dark-first theming:** CSS custom properties on `:root` (light) and
|
||
`[data-theme="dark"]`, with `prefers-color-scheme` detection defaulting to dark.
|
||
- **Design tokens:** Standardized CSS custom properties for border-radius
|
||
(`--radius-sm: 6px`, `--radius-md: 8px`, `--radius-lg: 12px`), semantic colors
|
||
(`--color-success`, `--color-warning`, `--color-overlay`), and focus ring
|
||
(`--focus-ring`). All components reference tokens instead of hardcoded values.
|
||
- **Unified note/task model:** A task is just a note with task attributes enabled.
|
||
A note has `status IS NOT NULL` ⟹ it's a task. "Convert to task" sets
|
||
`status='todo'`; "convert to note" clears `status`, `priority`, `due_date`.
|
||
No companion notes, no cascade deletes, no bidirectional sync needed.
|
||
- **Wikilinks:** Obsidian-style `[[Title]]` and `[[Title|Display Text]]` in markdown
|
||
bodies. Clicking a wikilink uses `POST /api/notes/resolve-title` to auto-create
|
||
missing notes.
|
||
- **Background generation architecture:** LLM streaming runs in a detached
|
||
`asyncio.Task` that writes into an in-memory `GenerationBuffer`. SSE clients
|
||
tail the buffer and can reconnect mid-stream without data loss. Buffer has
|
||
`cancel_event` for user-initiated stop. Completed buffers are cleaned up after
|
||
60s grace period. Periodic DB flushes every 5s preserve partial content.
|
||
Both chat and AI Assist use this architecture — assist buffers are keyed by
|
||
`"assist:{user_id}"` (string keys) instead of conversation ID (int keys).
|
||
Assist generation has no DB persistence, no title generation, no cancellation.
|
||
- **SSE over WebSockets for LLM streaming:** SSE clients connect via
|
||
`GET /api/chat/conversations/:id/generation/stream` with `Last-Event-ID`
|
||
reconnection support. Frontend uses `fetch()` + `ReadableStream`. Simpler than
|
||
WebSockets; Quart supports async generators natively for SSE.
|
||
- **Context building server-side:** Backend fetches URL content and searches notes —
|
||
frontend sends the message text + optional context note ID + optional `include_note_ids`.
|
||
Keyword extraction uses simple word splitting with stopword filtering (no embeddings).
|
||
`build_context()` returns `(messages, context_meta)` tuple; metadata includes
|
||
auto-found note IDs/titles sent to frontend via SSE `context` event before streaming.
|
||
Multi-word search splits terms into per-word ILIKE with AND logic (not adjacent match).
|
||
Auto-found notes populate the sidebar but are **not** injected into the system prompt
|
||
automatically — users must click `+` in the sidebar to include them (stable system
|
||
prompt prefix enables Ollama KV cache reuse). Explicitly included notes appear as
|
||
`--- Included Notes ---` in the system prompt.
|
||
- **Reverse proxy required for production:** The app does not terminate TLS. A
|
||
reverse proxy (Nginx/Traefik/Caddy) must sit in front of port 5000. Do not
|
||
expose the app directly to the internet.
|
||
- **Registration auto-closes:** After the first user registers (admin), registration
|
||
is closed by default. The admin can toggle it from `/admin/users`. The setting is
|
||
stored as the admin user's `registration_open` setting key.
|
||
- **No blocking long-running operations:** Any potentially slow operation (model
|
||
pulls, LLM calls, URL fetching, etc.) must never block app startup or freeze the
|
||
UI. Backend uses SSE streaming for incremental responses (chat messages and model
|
||
pull progress). Frontend keeps the UI responsive during async operations (loading
|
||
states, streaming indicators, progress percentages). This applies to all future
|
||
features as well.
|
||
- **Auto-pull model on startup:** Non-blocking background task, logs warning on
|
||
failure so the app still starts even if Ollama isn't ready.
|
||
- **Backlinks:** `GET /api/notes/:id/backlinks` searches all note bodies for
|
||
`[[Title]]` patterns referencing the given note. Results include `type: "note"` or
|
||
`type: "task"` based on whether the linking note has `status IS NOT NULL`.
|
||
- **Idempotent raw SQL migrations:** All Alembic migrations use raw SQL with
|
||
`CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and `DO $$ BEGIN
|
||
CREATE TYPE ... EXCEPTION WHEN duplicate_object` to allow safe re-runs and
|
||
fresh database creation.
|
||
- **Session cookie security:** `HttpOnly` and `SameSite=Lax` always set. `Secure`
|
||
flag controlled by `SECURE_COOKIES` env var (enable when behind TLS).
|
||
- **Default SECRET_KEY warning:** App logs a WARNING on startup if the default
|
||
`dev-secret-change-me` key is in use.
|
||
- **Security headers:** Applied in `app.py` `after_request` using `setdefault` so
|
||
SSE/streaming responses that set their own headers aren't clobbered: `X-Content-Type-Options`,
|
||
`X-Frame-Options: DENY`, `Referrer-Policy`, and a restrictive `Content-Security-Policy`.
|
||
- **Rate limiting:** In-memory sliding-window rate limiter (`rate_limit.py`) applied to
|
||
auth endpoints: login (10/60s), register (5/300s), forgot-password (5/300s, silent drop
|
||
to avoid timing info), reset-password (10/60s). Keys are per-IP.
|
||
- **Proxy-aware client IP:** `TRUST_PROXY_HEADERS` env var enables reading real client IP
|
||
from `X-Forwarded-For` / `X-Real-IP` when behind a trusted reverse proxy. Off by default.
|
||
- **Auto-save:** Both note and task editors auto-save every 5 minutes when editing an
|
||
existing dirty record. Silent on error; shows "Auto-saved" toast on success.
|
||
|
||
### High-Level Component Diagram
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ Docker Compose │
|
||
│ │
|
||
│ ┌──────────────────────┐ ┌────────────┐ │
|
||
│ │ fabledassistant │ │ ollama │ │
|
||
│ │ ┌────────────────┐ │ │ │ │
|
||
│ │ │ Quart Server │ │ │ LLM API │ │
|
||
│ │ │ ┌──────────┐ │ │ │ │ │
|
||
│ │ │ │ Vue SPA │ │ │ └────────────┘ │
|
||
│ │ │ │ (static) │ │ │ ▲ │
|
||
│ │ │ └──────────┘ │ │ │ │
|
||
│ │ │ ┌──────────┐ │ │ HTTP/REST │
|
||
│ │ │ │ /api/* │──┼──┼─────────┘ │
|
||
│ │ │ └──────────┘ │ │ │
|
||
│ │ │ │ │ │ ┌────────────┐ │
|
||
│ │ │ ▼ │ │ │ PostgreSQL │ │
|
||
│ │ │ ┌──────────┐ │ │ │ 16 │ │
|
||
│ │ │ │ asyncpg │──┼──┼──▶ │ │
|
||
│ │ │ └──────────┘ │ │ └────────────┘ │
|
||
│ │ └────────────────┘ │ │
|
||
│ └──────────────────────┘ │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Data Model
|
||
|
||
### Users
|
||
- `id` (int PK), `username` (text UNIQUE NOT NULL), `email` (text nullable),
|
||
`password_hash` (text **nullable** — NULL for OAuth-only accounts),
|
||
`oauth_sub` (text UNIQUE nullable — OIDC subject identifier),
|
||
`role` (text NOT NULL DEFAULT 'user'), `created_at` (timestamptz)
|
||
- First registered user auto-assigned `role='admin'`; claims orphaned data
|
||
- Passwords hashed with bcrypt; OAuth-only users have `password_hash = NULL`
|
||
- `to_dict()` excludes `password_hash`; includes `has_password: bool`
|
||
|
||
### Notes (unified — includes tasks)
|
||
- `id` (int PK), `title` (str), `body` (markdown str), `tags` (ARRAY[str]),
|
||
`parent_id` (nullable FK to self), `user_id` (nullable FK to users, CASCADE),
|
||
`status` (nullable str — `todo`/`in_progress`/`done`),
|
||
`priority` (nullable str — `none`/`low`/`medium`/`high`), `due_date` (nullable date),
|
||
`created_at`, `updated_at`
|
||
- **A note is a task when `status IS NOT NULL`** — the `is_task` property checks this
|
||
- Tags are explicitly provided by the client — NOT extracted from body text
|
||
- Supports hierarchical organization via `parent_id`
|
||
- Lookup by exact title via `get_note_by_title()` for wikilink resolution
|
||
- Auto-create via `get_or_create_note_by_title()` for wikilink clicks
|
||
- `to_dict()` returns: `id`, `title`, `body`, `tags`, `parent_id`, `status`,
|
||
`priority`, `due_date`, `is_task`, `created_at`, `updated_at`
|
||
- Indexes: GIN on tags, B-tree on status, B-tree on title
|
||
|
||
### Task ≡ Note with task attributes
|
||
- No separate tasks table. `routes/tasks.py` imports directly from
|
||
`services/notes.py` with `is_task=True` for listing and
|
||
defaults `status='todo'`, `priority='none'` for creation.
|
||
- "Convert to task" = `update_note(id, status='todo', priority='none')`
|
||
- "Convert to note" = `update_note(id, status=None, priority=None, due_date=None)`
|
||
- Task body field is `body` (not `description`) — standardized with notes
|
||
|
||
### Settings
|
||
- Composite PK: `(user_id, key)` — `user_id` FK to users (CASCADE), `key` (text)
|
||
- `value` (text)
|
||
- Per-user key-value store for settings (assistant name, default model, etc.)
|
||
- CRUD via `services/settings.py`: all functions take `user_id` as first parameter
|
||
|
||
### Conversations
|
||
- `id` (int PK), `title` (str), `model` (str), `user_id` (nullable FK to users, CASCADE), `created_at`, `updated_at`
|
||
- Has many messages (cascade delete)
|
||
- Title auto-generated by LLM on first exchange and re-generated every 10th message
|
||
- Index on `updated_at` for list ordering
|
||
- `to_dict()` returns: `id`, `title`, `model`, `message_count`, `created_at`, `updated_at`
|
||
- `list_conversations()` uses a subquery for `message_count` instead of eager-loading all messages
|
||
|
||
### App Logs
|
||
- `id` (int PK), `category` (text NOT NULL — `audit`/`usage`/`error`),
|
||
`user_id` (int FK users ON DELETE SET NULL), `username` (text — denormalized),
|
||
`action` (text), `endpoint` (text), `method` (text), `status_code` (int),
|
||
`duration_ms` (real), `ip_address` (text), `details` (text — JSON-serialized),
|
||
`created_at` (timestamptz DEFAULT now())
|
||
- Single table with `category` field for all log types
|
||
- Denormalized `username` preserves attribution after user deletion
|
||
- `details` stores flexible JSON data (error tracebacks, audit metadata, etc.)
|
||
- Indexes: `category`, `user_id`, `created_at`, composite `(category, created_at DESC)`
|
||
- Automatic retention cleanup via hourly asyncio task (configurable `LOG_RETENTION_DAYS`, default 90)
|
||
|
||
### Invitation Tokens
|
||
- `id` (int PK), `email` (text NOT NULL), `token_hash` (text NOT NULL UNIQUE),
|
||
`invited_by` (int FK users CASCADE), `expires_at` (timestamptz NOT NULL),
|
||
`used` (boolean NOT NULL DEFAULT FALSE), `created_at` (timestamptz)
|
||
- Admin creates invitation → raw token emailed → recipient registers via `/register-invite?token=...`
|
||
- Token stored as SHA256 hash (same pattern as password reset)
|
||
- 7-day expiration, one-time use, previous unused invitations for same email auto-revoked
|
||
- Indexes: `token_hash`, `email`
|
||
|
||
### Messages
|
||
- `id` (int PK), `conversation_id` (FK to conversations, CASCADE), `role` (str: system/user/assistant),
|
||
`content` (str), `status` (str, default `'complete'` — `complete`/`generating`/`error`),
|
||
`context_note_id` (nullable FK to notes, SET NULL), `tool_calls` (nullable JSONB), `created_at`
|
||
- Index on `conversation_id`
|
||
- `context_note_id` tracks which note was attached as context when message was sent
|
||
- `tool_calls` stores an array of tool call records `[{function, arguments, result, status}]` for assistant messages that used tools
|
||
- `to_dict()` returns: `id`, `conversation_id`, `role`, `content`, `status`, `context_note_id`, `tool_calls`, `created_at`
|
||
- `context_note_title` is NOT a DB column — it is synthesised at query time in `get_conversation_route` via a batch `get_notes_by_ids()` lookup and injected into the message dict so the frontend can display the note title without a separate fetch
|
||
|
||
## Project Structure (Current)
|
||
```
|
||
fabledassistant/
|
||
├── summary.md # This file — canonical project context
|
||
├── pyproject.toml # Python project config (deps include caldav, icalendar, httpx)
|
||
├── Dockerfile # Multi-stage build (Node → Python)
|
||
├── .dockerignore # Prevents secrets/node_modules/__pycache__/.env.* leaking into build
|
||
├── docker-compose.yml # Dev compose (app, PostgreSQL, Ollama) — app service has healthcheck
|
||
├── docker-compose.prod.yml # Production stack (Docker Swarm, secrets, network isolation)
|
||
├── alembic.ini # Alembic config (prepend_sys_path = src)
|
||
├── docs/
|
||
│ └── oauth-setup.md # Step-by-step Authentik OIDC setup guide with example docker-compose config
|
||
├── alembic/
|
||
│ ├── env.py # Async migration runner
|
||
│ └── versions/
|
||
│ ├── 0001_create_notes_table.py # Notes table (raw SQL, idempotent)
|
||
│ ├── 0002_create_tasks_table.py # Tasks table + enums (raw SQL, idempotent)
|
||
│ ├── 0003_task_note_companion.py # Data migration: create companion notes for existing tasks
|
||
│ ├── 0004_merge_tasks_into_notes.py # Add task columns to notes, migrate data, drop tasks table
|
||
│ ├── 0005_add_chat_tables.py # Conversations + messages tables with FKs and indexes
|
||
│ ├── 0006_add_settings_table.py # Settings key-value table
|
||
│ ├── 0007_add_title_and_updated_at_indexes.py # B-tree indexes on notes.title and conversations.updated_at
|
||
│ ├── 0008_add_users_and_user_id.py # Users table, user_id FKs on notes/conversations/settings, composite PK for settings
|
||
│ ├── 0009_add_message_status.py # Add status column to messages table (default 'complete')
|
||
│ ├── 0010_add_app_logs_table.py # App logs table for audit, usage, and error logging
|
||
│ ├── 0011_add_password_reset_tokens.py # Password reset tokens table
|
||
│ ├── 0012_add_invitation_tokens.py # Invitation tokens table
|
||
│ ├── 0013_add_tool_calls_to_messages.py # Add tool_calls JSONB column to messages
|
||
│ ├── 0014_add_note_embeddings.py # note_embeddings table for semantic search (note_id PK, user_id, embedding JSONB, updated_at)
|
||
│ └── 0015_add_oauth_fields.py # Add oauth_sub UNIQUE column; DROP NOT NULL on password_hash
|
||
├── src/
|
||
│ └── fabledassistant/
|
||
│ ├── __init__.py
|
||
│ ├── app.py # Quart app factory: SPA via 404 handler, JSON 404/500 for API, request logging, security headers (after_request)
|
||
│ ├── auth.py # Auth decorators: login_required, admin_required, get_current_user_id — shared _check_auth() helper
|
||
│ ├── config.py # Config from env vars + Docker secrets file support (_read_secret) + SECURE_COOKIES + TRUST_PROXY_HEADERS + OLLAMA_NUM_CTX (KV cache window, default 8192) + OIDC_ISSUER/CLIENT_ID/CLIENT_SECRET/SCOPES + LOCAL_AUTH_ENABLED + oidc_enabled() classmethod + SEARXNG_URL + searxng_enabled() classmethod
|
||
│ ├── rate_limit.py # In-memory sliding-window rate limiter (asyncio.Lock + defaultdict); is_rate_limited(key, max, window)
|
||
│ ├── models/
|
||
│ │ ├── __init__.py # async_session factory, Base, imports all models
|
||
│ │ ├── user.py # User model (id, username, email, password_hash nullable, oauth_sub unique nullable, role, created_at); to_dict() includes has_password bool
|
||
│ │ ├── note.py # Note model (unified: id, title, body, tags[], parent_id, user_id, status, priority, due_date, timestamps)
|
||
│ │ ├── conversation.py # Conversation + Message models with user_id
|
||
│ │ ├── setting.py # Setting model (composite PK: user_id + key, value TEXT)
|
||
│ │ ├── app_log.py # AppLog model (id, category, user_id, username, action, endpoint, method, status_code, duration_ms, ip_address, details, created_at)
|
||
│ │ └── invitation.py # InvitationToken model (id, email, token_hash, invited_by, expires_at, used, created_at)
|
||
│ ├── routes/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── api.py # /api blueprint with /health endpoint (public)
|
||
│ │ ├── auth.py # /api/auth blueprint: register, login, logout, me, password, email change, status, password reset, invitation registration, OAuth login+callback — rate limiting, LOCAL_AUTH_ENABLED guards, _client_ip() helper
|
||
│ │ ├── admin.py # /api/admin blueprint: backup, restore, user management, registration toggle, invitations, base URL, SMTP (admin only)
|
||
│ │ ├── chat.py # /api/chat blueprint: conversations CRUD, SSE message streaming (all @login_required)
|
||
│ │ ├── images.py # /api/images/<id> GET — serve locally-cached images (no auth required; IDs are opaque)
|
||
│ │ ├── notes.py # /api/notes CRUD + wikilinks + backlinks + tag suggestions + link suggestions + assist; POST accepts `project` name string (resolves to project_id)
|
||
│ │ ├── quick_capture.py # /api/quick-capture POST — mobile/external single-shot item creation
|
||
│ │ ├── tasks.py # /api/tasks CRUD + PATCH status; POST accepts `project` name string
|
||
│ │ ├── task_logs.py # /api/tasks/<id>/logs — GET/POST/PATCH/<log_id>/DELETE/<log_id>
|
||
│ │ ├── projects.py # /api/projects CRUD
|
||
│ │ ├── milestones.py # /api/projects/<pid>/milestones CRUD
|
||
│ │ ├── push.py # /api/push — VAPID public key, subscribe/unsubscribe
|
||
│ │ ├── export.py # /api/export?format=markdown|json — ZIP or JSON export
|
||
│ │ └── settings.py # /api/settings GET/PUT, GET /models
|
||
│ ├── services/
|
||
│ │ ├── auth.py # Auth business logic: hash_password, verify_password, create_user (password optional, oauth_sub kwarg), authenticate (returns None for OAuth-only users), get_user_by_id/username/email/oauth_sub, update_user_email, link_oauth_sub, is_registration_open, list_users, delete_user, password reset tokens, invitation tokens
|
||
│ │ ├── oauth.py # OIDC/OAuth2 service: get_oidc_config (discovery, cached), build_auth_url (PKCE), exchange_code, get_userinfo, find_or_create_oauth_user (sub lookup → email auto-link → create)
|
||
│ │ ├── backup.py # Backup/restore: export_full_backup, export_user_backup, restore_full_backup
|
||
│ │ ├── notes.py # CRUD with user_id isolation, is_task filter, convert, backlinks, search_notes_for_context
|
||
│ │ ├── llm.py # Ollama interaction: build_context with user_id, streaming (stream_chat + stream_chat_with_tools), ChatChunk dataclass, URL fetching; generate_completion accepts num_ctx kwarg; uses Config.OLLAMA_NUM_CTX for KV cache window
|
||
│ │ ├── chat.py # Conversation CRUD with user_id isolation, add_message, save/summarize as note (LLM-titled, chat-tagged)
|
||
│ │ ├── generation_buffer.py # In-memory SSE event buffer with cancel_event, reconnect support, auto-cleanup; supports chat (int keys) and assist (string keys)
|
||
│ │ ├── generation_task.py # Background asyncio tasks: run_generation + run_assist_generation. Tool-only responses synthesise push notification body from tool names. workspace_project_id threaded through to build_context().
|
||
│ │ ├── intent.py # Intent routing: classify_intent() makes fast non-streaming LLM call (num_ctx=4096); IntentResult has ack field; classify_capture_intent() uses dedicated _CAPTURE_SYSTEM_PROMPT (always routes to a tool, never null)
|
||
│ │ ├── images.py # Image cache service: fetch_and_store_image (SHA-256 dedup, content-type validation, 5MB cap), get_image_record, get_image_path
|
||
│ │ ├── tools.py # LLM tool definitions + execute_tool dispatcher. Duplicate detection in create_note/create_task: exact title, fuzzy (SequenceMatcher ≥0.82), semantic (cosine ≥0.90, body ≥200 chars) — all scoped to same type (is_task). POST /api/notes|tasks accept `project` name string.
|
||
│ │ ├── research.py # SearXNG research pipeline: parallel query/fetch, streaming synthesis; run_research_pipeline(buf=None) → Note (buf optional — no status events when omitted); _search_searxng_images() for image category search; constants SEARXNG_QUERIES=5, PAGES_PER_QUERY=3, MAX_SYNTHESIS_SOURCES=12, CHARS_PER_SOURCE=2000
|
||
│ │ ├── tag_suggestions.py # LLM-powered tag suggestions: suggest_tags() builds prompt with existing tags, calls generate_completion, parses JSON response
|
||
│ │ ├── caldav.py # CalDAV integration: full event lifecycle (create/list/search/update/delete), list_calendars, timezone (ZoneInfo), reminders (VALARM), attendees, multi-calendar search. Todo functions exist in code but are NOT exposed as LLM tools.
|
||
│ │ ├── settings.py # Settings CRUD with user_id isolation: get_setting, set_setting, set_settings_batch, get_all_settings
|
||
│ │ ├── logging.py # App logging: log_audit, log_usage, log_error, get_logs, get_log_stats, delete_old_logs, start_log_retention_loop
|
||
│ │ ├── email.py # SMTP email service: get_smtp_config, is_smtp_configured, send_email, send_test_email
|
||
│ │ ├── notifications.py # Notification service: notify_security_event, check_due_tasks, start_notification_loop
|
||
│ │ ├── push.py # VAPID key generation/loading, send_push_notification (fire-and-forget); pywebpush 2.x API (webpush() function). sw.js suppresses notification when relevant chat tab is focused.
|
||
│ │ ├── projects.py # Project CRUD + get_project_by_title + get_project_summary (includes milestone_summary)
|
||
│ │ ├── milestones.py # Milestone CRUD + get_milestone_progress
|
||
│ │ ├── task_logs.py # create_log, list_logs, update_log (_UNSET sentinel for optional duration_minutes), delete_log — all ownership-checked
|
||
│ │ └── assist.py # Writing assistant: build_assist_messages (section/whole-doc modes, project context injection)
|
||
│ ├── utils/
|
||
│ │ ├── __init__.py
|
||
│ │ └── tags.py # extract_tags() — regex #tag extraction, skips code fences
|
||
│ └── static/ # Vue production build (generated by Dockerfile)
|
||
└── frontend/
|
||
├── package.json # deps: vue, pinia, vue-router, marked, dompurify
|
||
├── vite.config.ts
|
||
├── tsconfig.json
|
||
├── src/
|
||
│ ├── App.vue # Shell: .app-shell (100dvh flex column) with AppHeader + .app-content (flex:1, scrollable) wrapping router-view; starts status polling + loads settings on mount
|
||
│ ├── main.ts # App init, imports theme.css
|
||
│ ├── assets/
|
||
│ │ ├── theme.css # CSS custom properties: light/dark themes, body reset, design tokens, responsive breakpoints (480/768/1024), utility classes (.hide-mobile/.hide-desktop), mobile touch targets; light mode uses indigo brand color (#6366f1) + indigo-tinted off-white backgrounds (#f5f5fb/#ededf5)
|
||
│ │ └── editor-shared.css # Shared editor styles for NoteEditorView + TaskEditorView: layout, toolbar, tag suggestions, assist panel, diff view, modal, responsive, .inline-assist-btn (global — required for teleported elements)
|
||
│ ├── api/
|
||
│ │ └── client.ts # ApiError class, apiGet/apiPost/apiPut/apiPatch/apiDelete + apiSSEStream (fetch+ReadableStream), apiStreamPost (legacy), auto 401→login redirect
|
||
│ ├── composables/
|
||
│ │ ├── useTheme.ts # Theme toggle, localStorage, prefers-color-scheme
|
||
│ │ ├── useShortcuts.ts # Shared showShortcuts ref + open/close/toggle helpers (used by App.vue + AppHeader.vue)
|
||
│ │ ├── useAutocomplete.ts # Legacy textarea autocomplete (replaced by Tiptap suggestion extensions)
|
||
│ │ └── useAssist.ts # AI Assist composable: section parsing, target selection, two-step POST+SSE streaming (apiPost → apiSSEStream), accept/reject (accept() resets to idle on doc-change error), proofread (full-document), LCS line diff (DiffLine/computeDiff), isProofreading ref; watches body ref for auto-sync
|
||
│ ├── stores/
|
||
│ │ ├── auth.ts # Auth state: user, isAuthenticated, isAdmin, oauthEnabled, localAuthEnabled, login/register/logout/checkAuth/checkHasUsers
|
||
│ │ ├── notes.ts # CRUD + tag filter, resolveTitle, convertToTask, convertToNote, fetchBacklinks, fetchAllTags (with toast errors)
|
||
│ │ ├── tasks.ts # CRUD + status/priority filter, patchStatus (with toast errors)
|
||
│ │ ├── chat.ts # Conversation CRUD, sendMessage (SSE streaming, includeNoteIds param), status polling (memory-leak-safe _pollUntilLoaded), running models, model warming, updateConversationModel (with toast errors)
|
||
│ │ ├── settings.ts # App settings: assistantName, defaultModel, installedModels, defaultChatModel, defaultIntentModel, pullModel, deleteModel (with toast errors)
|
||
│ │ └── toast.ts # Toast notification state (success/error/warning), 4s auto-dismiss, dismiss(id)
|
||
│ ├── types/
|
||
│ │ ├── auth.ts # User interface (incl. has_password bool), AuthStatus interface (incl. oauth_enabled, local_auth_enabled)
|
||
│ │ ├── note.ts # Note interface (with status, priority, due_date, is_task) + TaskStatus, TaskPriority types + NoteListResponse
|
||
│ │ ├── chat.ts # ToolCallRecord, Message, Conversation, ConversationDetail, ContextMeta, OllamaModel, RunningModel, OllamaStatus interfaces
|
||
│ │ ├── settings.ts # AppSettings interface, ModelInfo interface (name, description, size, bestFor, category)
|
||
│ │ └── task.ts # Task = re-export of Note; TaskListResponse
|
||
│ ├── extensions/
|
||
│ │ ├── TagDecoration.ts # ProseMirror decoration plugin: highlights #tags with .inline-tag class
|
||
│ │ ├── WikilinkDecoration.ts # ProseMirror decoration plugin: highlights [[wikilinks]] with .wikilink class
|
||
│ │ ├── TagSuggestion.ts # @tiptap/suggestion extension for #tag autocomplete (suppressed at line start for headings)
|
||
│ │ ├── WikilinkSuggestion.ts # @tiptap/suggestion extension for [[wikilink]] autocomplete
|
||
│ │ └── suggestionRenderer.ts # Shared Vue renderer for suggestion dropdowns (creates/positions SuggestionDropdown)
|
||
│ ├── utils/
|
||
│ │ ├── tags.ts # extractTags(), linkifyTags() (with (?<!&) to skip HTML entities), linkifyWikilinks()
|
||
│ │ ├── markdown.ts # renderMarkdown() (full) + renderPreview() (strips links/images) — decodes HTML entities before marked, replaces ' after sanitization; explicit DOMPurify config with FORCE_BODY
|
||
│ │ ├── markdownSerializer.ts # Tiptap JSON → markdown serializer: handles all StarterKit nodes + marks
|
||
│ │ └── sectionParser.ts # parseMarkdownSections() (heading-based) + parseFallbackSections() (paragraph/Q&A-style — single-line ≤120 char paragraphs become pseudo-headings; top-level bullet/numbered list items become individual sections)
|
||
│ ├── views/
|
||
│ │ ├── LoginView.vue # Login form; "Login with Authentik" SSO button when oauth_enabled; hides password form when local_auth_disabled; handles ?error=oauth query param
|
||
│ │ ├── RegisterView.vue # Register form with password confirmation; shows "closed" message when registration disabled
|
||
│ │ ├── RegisterInviteView.vue # Invitation-based registration: validates token, creates account with pre-set email
|
||
│ │ ├── UserManagementView.vue # Admin user management: registration toggle, invitations (send/revoke), user list with delete
|
||
│ │ ├── ChatView.vue # Dedicated /chat page: responsive sidebar, bubble messages, note picker, context sidebar (auto-included + suggested), model selector, abort button, bulk-select conversations, per-conv message queue with localStorage persistence; queued bubbles indigo gradient right-aligned
|
||
│ │ ├── WorkspaceView.vue # /workspace/:projectId — 3-panel (tasks/chat/notes), CSS grid collapse, SSE tool-call watcher auto-loads notes + refreshes tasks, conv persisted to localStorage
|
||
│ │ ├── GraphView.vue # /graph — D3 force-directed graph: note/task/tag/project-hub nodes, physics panel, peek panel slide-in on click, tag-click nav to /notes?tags=
|
||
│ │ ├── HomeView.vue # Chat-first dashboard: quick actions + chat widget (top, full-width), inline response panel, two-column grid (3fr tasks / 2fr notes); task sections: Overdue, Due Today, Due This Week, High Priority, In Progress, Other (capped 10, due-dated first); 8 recent notes; model warming on mount
|
||
│ │ ├── SettingsView.vue # Tabbed settings (6 tabs: General, Account, Notifications, Integrations, Data, Admin); tab state in localStorage key `settings_tab`; Admin tab: session invalidation button, SMTP, base URL, data export/restore, user management links
|
||
│ │ ├── NotesListView.vue # Note list: search, sort, tag filter pills, pagination
|
||
│ │ ├── NoteEditorView.vue # Create/edit: Tiptap editor, sticky toolbar, TagInput chip field (between title and body), ProjectSelector + MilestoneSelector (milestone resets when project changes), AI Assist panel (right-side 320px, collapsible), line-level diff view, Proofread action, floating inline ✨ pill on text selection, LLM tag suggestions (adds chips), Ctrl+S, auto-save (5min), unsaved guard; styles from editor-shared.css
|
||
│ │ ├── NoteViewerView.vue # Markdown render, wikilink auto-create, convert-to-task, backlinks, table of contents sidebar
|
||
│ │ ├── TasksListView.vue # Task list: search, status/priority filters, sort, pagination
|
||
│ │ ├── TaskEditorView.vue # Create/edit task: Tiptap editor, sticky toolbar, TagInput chip field (between metadata fields and body), AI Assist panel (right-side 320px, collapsible), line-level diff view, Proofread action, floating inline ✨ pill on text selection, LLM tag suggestions (adds chips), Ctrl+S, auto-save (5min), dirty guard; styles from editor-shared.css + task-specific scoped styles
|
||
│ │ └── TaskViewerView.vue # Task detail: rendered markdown, badges (isOverdue uses ISO string comparison), convert-to-note, backlinks, table of contents sidebar
|
||
│ ├── components/
|
||
│ │ ├── LogsView.vue # Admin log viewer: stats summary, category/search/date filters, paginated table with IP column + expandable detail rows (expands on ip_address or details)
|
||
│ │ ├── AppHeader.vue # Nav bar: three-zone layout — brand (left), Notes/Projects/Tasks/Chat centered (absolute positioning), right rail: status + ? + theme + gear dropdown (Settings/Users/Logs) + username/signout; hamburger + mobile dropdown on ≤768px
|
||
│ │ ├── ChatPanel.vue # Slide-out chat panel (right side overlay, receives contextNoteId prop), bubble-style messages, floating dark input, note picker, context pills with promote (+) only (no exclude)
|
||
│ │ ├── ModelSelector.vue # Model dropdown (v-model pattern): fetches installed + running models, hot/cold indicators
|
||
│ │ ├── DashboardChatInput.vue # Inline chat bar: ModelSelector + note picker + textarea + send button; emits submit event
|
||
│ │ ├── WorkspaceTaskPanel.vue # Tasks grouped by milestone, collapsible, detail slide-over (status cycle + milestone select + body + TaskLogSection + delete)
|
||
│ │ ├── WorkspaceNoteEditor.vue # List view (search, inline tags, delete) ↔ TipTap editor (TagInput + WordCount + autosave)
|
||
│ │ ├── ToolCallCard.vue # Compact card for tool call results + suggested tag pills. Duplicate `requires_confirmation` state: inline confirm/deny buttons in header row; "Create anyway" → direct POST /api/notes or /api/tasks (no LLM round-trip); `confirmState: idle|creating|created|denied`
|
||
│ │ ├── ChatMessage.vue # Message bubble: markdown rendering, tool call cards, configurable assistant name label, "Save as Note" action on assistant messages
|
||
│ │ ├── NoteCard.vue # Card with rendered markdown preview (v-html), TagPill, tag-click emit, hover edit button
|
||
│ │ ├── TaskCard.vue # Card with rendered preview (body not description), StatusBadge (clickable), PriorityBadge, due date, tags, hover edit button
|
||
│ │ ├── StatusBadge.vue # Color-coded status badge, optional clickable cycling
|
||
│ │ ├── PriorityBadge.vue # Color-coded priority indicator (hidden for "none")
|
||
│ │ ├── MarkdownToolbar.vue # Tiptap command-based toolbar: bold/italic/link/list/heading with active state highlighting
|
||
│ │ ├── TagInput.vue # Chip-based tag input: Enter/comma/click to confirm, Backspace removes last, × removes chip, autocomplete from /api/notes/tags, space→hyphen sanitization
|
||
│ │ ├── TiptapEditor.vue # Tiptap wrapper: markdown↔HTML round-trip, paste handling, selection change emit (closest-match offset strategy), expose editor; no fetchTags prop (TagSuggestion removed, TagDecoration kept)
|
||
│ │ ├── SuggestionDropdown.vue # Shared autocomplete dropdown for tag/wikilink suggestions
|
||
│ │ ├── SearchBar.vue # Debounced search input
|
||
│ │ ├── TagPill.vue # Clickable/dismissible tag pill
|
||
│ │ ├── PaginationBar.vue # Prev/next + page numbers
|
||
│ │ ├── TableOfContents.vue # Sticky sidebar TOC: parses markdown headings, smooth-scroll on click, hidden ≤1200px
|
||
│ │ └── ToastNotification.vue # Fixed-position toast container with close button, warning support
|
||
│ └── router/
|
||
│ └── index.ts # Routes: /, /login, /register, /register-invite, /notes/*, /tasks/*, /chat, /chat/:id, /workspace/:projectId, /graph, /projects, /projects/:id, /settings, /admin/users, /admin/logs; beforeEach auth guard
|
||
└── public/
|
||
```
|
||
|
||
## API Endpoints (Current)
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| GET | `/api/health` | Health check (public) |
|
||
| GET | `/api/auth/status` | Returns `{has_users, registration_open, oauth_enabled, local_auth_enabled}` (public) |
|
||
| POST | `/api/auth/register` | Register new user (first user becomes admin; 403 if registration closed or local auth disabled) |
|
||
| POST | `/api/auth/login` | Login with username/password (403 if local auth disabled; returns None for OAuth-only users) |
|
||
| POST | `/api/auth/logout` | Logout (clear session) |
|
||
| GET | `/api/auth/me` | Get current user info (includes `has_password` bool) |
|
||
| PUT | `/api/auth/password` | Change password (body: `{current_password, new_password}`) |
|
||
| PUT | `/api/auth/email` | Change email (body: `{email, password?}`; password required only if user has local password) |
|
||
| GET | `/api/auth/oauth/login` | Initiate OIDC flow — generates PKCE verifier + state, stores in session, redirects to provider |
|
||
| GET | `/api/auth/oauth/callback` | OIDC callback — exchanges code, fetches userinfo, finds/creates user, sets session, redirects to `/` |
|
||
| GET | `/api/admin/backup` | Export backup (`?scope=user` for own data, full requires admin) |
|
||
| POST | `/api/admin/restore` | Restore from JSON backup (admin only) |
|
||
| GET | `/api/admin/users` | List all users (admin only) |
|
||
| DELETE | `/api/admin/users/:id` | Delete a user (admin only, cannot delete self) |
|
||
| GET | `/api/admin/registration` | Get registration open/closed status (admin only) |
|
||
| PUT | `/api/admin/registration` | Toggle registration open/closed (admin only, body: `{open: bool}`) |
|
||
| GET | `/api/admin/logs` | List log entries (admin only, params: `category`, `user_id`, `search`, `date_from`, `date_to`, `limit`, `offset`) |
|
||
| GET | `/api/admin/logs/stats` | Get log category counts (admin only) |
|
||
| GET | `/api/notes` | List notes (params: `q`, `tag`, `sort`, `order`, `limit`, `offset`, `project_id`, `milestone_id`, `parent_id`, `type`; `type=note` default — plain notes only; `type=task` for tasks, `type=all` for everything) |
|
||
| POST | `/api/notes` | Create note (body: `{title, body, tags?: string[], status?, priority?, due_date?}` — tags explicit array) |
|
||
| GET | `/api/notes/tags` | List all tags from notes table (param: `q` for filter) |
|
||
| POST | `/api/notes/suggest-tags` | LLM-suggest tags (body: `{title, body, current_tags?: string[]}`, returns `{suggested_tags: [...]}`) |
|
||
| POST | `/api/notes/:id/append-tag` | Add tag to note's tags array with deduplication (body: `{tag}`, returns updated note) |
|
||
| GET | `/api/notes/by-title?title=...` | Resolve note by exact title (case-insensitive) |
|
||
| POST | `/api/notes/resolve-title` | Get-or-create note by title (for wikilink clicks) |
|
||
| GET | `/api/notes/:id` | Get single note (response includes `is_task`, `status`, `priority`, `due_date`) |
|
||
| PUT | `/api/notes/:id` | Update note (body: `{title?, body?, tags?: string[], status?, priority?, due_date?, project_id?, milestone_id?, parent_id?}`) |
|
||
| PATCH | `/api/notes/:id` | Partial update note — same accepted fields as PUT; used for sub-task status toggle |
|
||
| DELETE | `/api/notes/:id` | Delete note (simple delete, no cascade) |
|
||
| POST | `/api/notes/:id/convert-to-task` | Set `status='todo'`, `priority='none'` on note (returns 200) |
|
||
| POST | `/api/notes/:id/convert-to-note` | Clear `status`, `priority`, `due_date` from note (returns 200) |
|
||
| GET | `/api/notes/:id/backlinks` | List notes/tasks that reference this note via wikilinks |
|
||
| POST | `/api/notes/assist` | Launch background assist generation, return 202 (body: `{body, target_section, instruction}`; 409 if already running) |
|
||
| GET | `/api/notes/assist/stream` | SSE endpoint tailing assist generation buffer; supports `Last-Event-ID` reconnection; emits `chunk`, `done`, `error` events with 15s keepalives |
|
||
| GET | `/api/auth/invitation/:token` | Validate invitation token, returns `{valid, email?}` (public) |
|
||
| POST | `/api/auth/register-with-invite` | Register with invitation token (body: `{token, username, password}`) (public) |
|
||
| GET | `/api/admin/base-url` | Get application base URL setting (admin only) |
|
||
| PUT | `/api/admin/base-url` | Set application base URL (admin only, body: `{base_url}`) |
|
||
| POST | `/api/admin/invitations` | Create invitation (admin only, body: `{email}`) — sends email with registration link |
|
||
| GET | `/api/admin/invitations` | List pending invitations (admin only) |
|
||
| DELETE | `/api/admin/invitations/:id` | Revoke invitation (admin only) |
|
||
| GET | `/api/tasks` | List tasks (params: `q`, `tag`, `status`, `priority`, `due_before`, `due_after`, `sort`, `order`, `limit`, `offset`) — queries notes where `status IS NOT NULL` |
|
||
| POST | `/api/tasks` | Create task (body: `{title, body, tags?: string[], status?, priority?, due_date?}` — accepts `description` as fallback for `body`) |
|
||
| GET | `/api/tasks/:id` | Get single task |
|
||
| PUT | `/api/tasks/:id` | Update task (body: `{title?, body?, tags?: string[], status?, priority?, due_date?}` — accepts `description` as fallback for `body`) |
|
||
| PATCH | `/api/tasks/:id/status` | Quick status toggle (body: `{status}`) |
|
||
| DELETE | `/api/tasks/:id` | Delete task (simple delete) |
|
||
| GET | `/api/chat/conversations` | List conversations (params: `limit`, `offset`) |
|
||
| POST | `/api/chat/conversations` | Create conversation (body: `{title?, model?}`) |
|
||
| GET | `/api/chat/conversations/:id` | Get conversation with all messages |
|
||
| DELETE | `/api/chat/conversations/:id` | Delete conversation (cascades to messages) |
|
||
| PATCH | `/api/chat/conversations/:id` | Update conversation title or model (body: `{title?, model?}`) |
|
||
| POST | `/api/chat/conversations/:id/messages` | Start generation: save user message, launch background task, return 202 (body: `{content, context_note_id?, include_note_ids?}`) |
|
||
| GET | `/api/chat/conversations/:id/generation/stream` | SSE endpoint tailing generation buffer; supports `Last-Event-ID` reconnection; emits `context`, `chunk`, `done`, `error` events |
|
||
| POST | `/api/chat/conversations/:id/generation/cancel` | Cancel active generation (sets cancel_event, saves partial content) |
|
||
| POST | `/api/chat/messages/:id/save-as-note` | Save assistant message as a new note (LLM-generated title, tagged `chat`) |
|
||
| POST | `/api/chat/conversations/:id/summarize` | Summarize conversation via LLM, save as note |
|
||
| GET | `/api/chat/ps` | List currently loaded (hot) Ollama models (`{models: [{name, size, size_vram, expires_at}]}`) |
|
||
| POST | `/api/chat/warm` | Pre-load a model into Ollama memory (body: `{model}`, returns 202) |
|
||
| GET | `/api/chat/status` | Check Ollama availability and model readiness (`{ollama, model, default_model}`) |
|
||
| GET | `/api/chat/models` | List available Ollama models |
|
||
| POST | `/api/chat/models/pull` | Pull/download a model from Ollama via SSE streaming progress (body: `{model}`, response: SSE with `{status, completed, total}` events) |
|
||
| POST | `/api/chat/models/delete` | Delete a model from Ollama (body: `{model}`) |
|
||
| GET | `/api/admin/smtp` | Get SMTP config (password masked) (admin only) |
|
||
| PUT | `/api/admin/smtp` | Save SMTP config to admin settings (admin only, body: `{smtp_host, smtp_port, ...}`) |
|
||
| POST | `/api/admin/smtp/test` | Send test email (admin only, body: `{recipient}`) |
|
||
| GET | `/api/settings` | Get all app settings as `{key: value}` dict |
|
||
| PUT | `/api/settings` | Update settings (body: `{key: value, ...}`) |
|
||
| GET | `/api/settings/models` | Get installed Ollama models + configured defaults (`{models, default_chat_model, default_intent_model}`) |
|
||
| GET | `/api/projects` | List projects |
|
||
| POST | `/api/projects` | Create project |
|
||
| GET | `/api/projects/:id` | Get project with milestone summary |
|
||
| PATCH | `/api/projects/:id` | Update project |
|
||
| DELETE | `/api/projects/:id` | Delete project |
|
||
| GET | `/api/projects/:id/milestones` | List milestones for project |
|
||
| POST | `/api/projects/:id/milestones` | Create milestone |
|
||
| PATCH | `/api/projects/:id/milestones/:mid` | Update milestone |
|
||
| DELETE | `/api/projects/:id/milestones/:mid` | Delete milestone |
|
||
| GET | `/api/tasks/:id/logs` | List work logs for task |
|
||
| POST | `/api/tasks/:id/logs` | Create work log (body: `{content, duration_minutes?}`) |
|
||
| PATCH | `/api/tasks/:id/logs/:log_id` | Update work log |
|
||
| DELETE | `/api/tasks/:id/logs/:log_id` | Delete work log |
|
||
| GET | `/api/push/vapid-public-key` | Get VAPID public key for push subscription |
|
||
| POST | `/api/push/subscribe` | Register push subscription |
|
||
| DELETE | `/api/push/subscribe` | Unregister push subscription |
|
||
| GET | `/api/export` | Export notes/tasks (`?format=markdown` → ZIP, `?format=json` → JSON array) |
|
||
| POST | `/api/auth/invalidate-sessions` | Bump `session_version` — invalidates all other sessions, keeps current alive |
|
||
| POST | `/api/chat/conversations/:id/messages` | Start generation (body: `{content, context_note_id?, include_note_ids?, rag_project_id?, workspace_project_id?}`) — workspace_project_id injects project system prompt |
|
||
| POST | `/api/chat/conversations/bulk-delete` | Delete multiple conversations (body: `{ids: number[]}`) |
|
||
|
||
## Alembic Migrations
|
||
|
||
### Overview
|
||
Migrations use raw SQL for full idempotency — safe to run on a fresh database
|
||
or re-run on an existing one. The Dockerfile runs migrations automatically on
|
||
container startup.
|
||
|
||
### Migration Chain
|
||
```
|
||
0001 → 0002 → 0003 → 0004 → 0005 → 0006 → 0007 → 0008 → 0009 → 0010 → 0011 → 0012 → 0013 → 0014 → 0015
|
||
```
|
||
|
||
### How Migrations Run
|
||
The Dockerfile CMD runs:
|
||
```sh
|
||
(alembic stamp --purge base 2>/dev/null || true) && alembic upgrade head && hypercorn ...
|
||
```
|
||
- `alembic stamp --purge base` clears any stale revision stamps (safe no-op if none)
|
||
- `alembic upgrade head` runs all pending migrations in order
|
||
- Migrations are idempotent so re-running is safe
|
||
|
||
### Creating a New Migration
|
||
When adding a new migration, follow these conventions:
|
||
|
||
1. **Create the migration file:**
|
||
```
|
||
alembic/versions/0005_description.py
|
||
```
|
||
|
||
2. **Use raw SQL for idempotency:**
|
||
```python
|
||
from alembic import op
|
||
|
||
revision = "0005"
|
||
down_revision = "0004"
|
||
|
||
def upgrade() -> None:
|
||
# For new enums:
|
||
op.execute("""
|
||
DO $$ BEGIN
|
||
CREATE TYPE my_enum AS ENUM ('a', 'b');
|
||
EXCEPTION WHEN duplicate_object THEN null;
|
||
END $$
|
||
""")
|
||
# For new tables:
|
||
op.execute("""
|
||
CREATE TABLE IF NOT EXISTS my_table (...)
|
||
""")
|
||
# For new indexes:
|
||
op.execute("CREATE INDEX IF NOT EXISTS ix_name ON table (col)")
|
||
# For adding columns:
|
||
op.execute("""
|
||
DO $$ BEGIN
|
||
ALTER TABLE my_table ADD COLUMN new_col TEXT DEFAULT '';
|
||
EXCEPTION WHEN duplicate_column THEN null;
|
||
END $$
|
||
""")
|
||
|
||
def downgrade() -> None:
|
||
op.execute("DROP INDEX IF EXISTS ix_name")
|
||
op.execute("DROP TABLE IF EXISTS my_table")
|
||
op.execute("DROP TYPE IF EXISTS my_enum")
|
||
```
|
||
|
||
3. **Rebuild and test:**
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
To test from a completely fresh database:
|
||
```bash
|
||
docker compose down -v && docker compose up --build
|
||
```
|
||
|
||
### Important Notes
|
||
- Do NOT use `op.create_table()` or `sa.Enum()` — SQLAlchemy's event system
|
||
can fire `CREATE TYPE` even with `create_type=False`, causing failures on re-run
|
||
- Always write raw SQL with PostgreSQL idempotency guards
|
||
- Set `down_revision` to chain from the previous migration's `revision`
|
||
- Data migrations (like 0003) should use `op.get_bind()` + `sa.text()` for queries
|
||
|
||
## Implemented Features
|
||
|
||
### Notes & Tasks
|
||
- Full CRUD with markdown bodies, first-class tag array (chip input in editors), hierarchical tag filtering
|
||
- Unified data model: a task is a note with `status IS NOT NULL` — convert freely between note ↔ task
|
||
- Task attributes: status (todo/in_progress/done), priority (none/low/medium/high), due_date
|
||
- Obsidian-style `[[wikilinks]]` with auto-create on click, backlinks ("what links here")
|
||
- Tiptap WYSIWYG editor with markdown round-trip, tag/wikilink autocomplete and decorations, sticky toolbar
|
||
- AI Assist panel (right-side 320px, toggle persisted to localStorage): section targeting, floating ✨ pill on text selection, full-document Proofread action, line-level diff view in review state (LCS algorithm), "Show full text" toggle, accept/reject; panel collapses to bottom 45% on mobile (≤768px)
|
||
- Table of contents sidebar on note/task viewers (auto-generated from headings, hidden ≤1200px)
|
||
- Inline edit buttons on NoteCard/TaskCard (hover on desktop, always visible on touch)
|
||
- Search (ILIKE), sort, tag filter pills, pagination on list views
|
||
|
||
### Dashboard
|
||
- **Chat-first layout:** Quick action chips + chat input at top (full width); no page title.
|
||
Inline streaming response (full width) appears between widget and content grid when active.
|
||
- **Two-column grid:** Tasks left (3fr) / Recent Notes right (2fr); collapses to single column on mobile. Max-width 1400px.
|
||
- **Left column — 6 task sections** in urgency order, all cascading-deduplicated:
|
||
Overdue (red border), Due Today, Due This Week, High Priority (amber border), In Progress, Other (capped at 10).
|
||
"Other" = broad fetch of all non-done tasks deduped against shown sections; due-dated items first (asc), then undated by priority desc.
|
||
- **Right column** — 8 most recently edited notes.
|
||
- Priority-aware sorting (priority desc → due date asc) within each section.
|
||
- All sections hidden when empty; marking a task done removes it from all lists.
|
||
- **Inline chat:** Streams response inline — no navigation to `/chat`. Tool calls shown live.
|
||
Conversational (no tool calls) response promotes "Continue this conversation →" button.
|
||
- **Quick action chips:** Pre-defined prompts above the chat input.
|
||
- **Auto-focus:** Dashboard chat input gains focus on page mount.
|
||
- **Keyboard shortcut — Escape in ChatView:** Cascade close: note picker → mobile sidebar → clear textarea → navigate to `/` home.
|
||
- **Keyboard shortcuts overlay:** Press `?` or click `?` in nav bar. State shared via `useShortcuts` composable.
|
||
- **Global keyboard shortcuts (`App.vue`):**
|
||
- `g`+`h/n/t/p/c` — navigate to home / notes / tasks / projects / chat
|
||
- `n` — new note; `t` — new task
|
||
- `e` — jump to edit (on `note-view` or `task-view` route)
|
||
- `/` — focus search bar (dispatches `shortcut:focus-search`; list views listen + call `SearchBar.focus()`)
|
||
- `c` — focus chat input on home (dispatches `shortcut:focus-chat`); navigate to `/chat` elsewhere
|
||
- `j` / `k` — move selection down / up in flat note/task lists; `Enter` opens selected item
|
||
- `Escape` — progressive: close shortcuts panel → blur active input → navigate home
|
||
- All shortcuts suppressed when focus is in an input, textarea, or contenteditable
|
||
- `a:focus-visible` added to `theme.css` focus-ring ruleset so router-link cards show visible focus outlines
|
||
- `SearchBar.vue` exposes `focus()` via `defineExpose` for external focus dispatch
|
||
|
||
### LLM Chat
|
||
- Ollama integration via async HTTP (httpx), default model `qwen3:latest` (`config.py` fallback); docker-compose default is `llama3.1` (override via `OLLAMA_MODEL` env var or user `default_model` setting); auto-pull on startup
|
||
- Background generation with `GenerationBuffer` (in-memory SSE fan-out, `Last-Event-ID` reconnect, 60s cleanup)
|
||
- Stop generation with partial content preservation
|
||
- Note-aware context building: current note + keyword search for related notes + URL fetching
|
||
- **Context sidebar (Phase 21):** Right panel in ChatView shows two sections: **Suggested** (auto-found
|
||
by semantic/keyword search — click `+` to include) and **In Context** (explicitly included by user —
|
||
click `×` to remove). Removing an included note moves it back to Suggested. Hidden on mobile (≤768px).
|
||
Auto-found notes are shown as sidebar candidates only — they are NOT injected into the system prompt
|
||
automatically, keeping the system prompt prefix stable for Ollama KV cache reuse.
|
||
- Note picker (paperclip) in chat input adds notes directly to **persistent** `includedNotes` (not a
|
||
one-shot attachment) — picked notes appear in "In Context" and remain for the entire conversation.
|
||
`context_note_title` synthesised server-side at conversation load via batch `get_notes_by_ids()`;
|
||
message badge shows note title instead of "Note #N".
|
||
- LLM-generated conversation titles (re-generated every 10th message)
|
||
- Save assistant messages as notes (LLM-titled, chat-tagged); summarize conversations
|
||
- Dedicated `/chat` page with responsive sidebar + slide-out chat panel from header
|
||
- Model catalog with installed/available tabs, download progress, select, remove
|
||
- Per-conversation model selection via ModelSelector dropdown in chat header (persisted via PATCH); user's `default_model` setting is always the source of truth for generation and summarization — `conv.model` (stored at creation time) no longer short-circuits the setting lookup
|
||
- Dashboard inline chat input: model selector + note picker + textarea; creates conversation and navigates
|
||
- **Startup warm-up (fixed):** No longer warms `Config.OLLAMA_MODEL`. At startup, queries all distinct `default_model` values from user settings, cross-references with Ollama's installed models, and warms only the intersection. Models selected by users but not yet installed are skipped with an info log.
|
||
- Model warming: default model pre-loaded into Ollama on dashboard mount via fire-and-forget POST
|
||
- **Model load state indicator:** `GET /api/chat/status` now queries `/api/tags` and `/api/ps` in
|
||
parallel. Model status has three values: `"not_found"` (not installed), `"cold"` (installed but
|
||
not in VRAM — first response will be slow), `"loaded"` (hot in VRAM, fast response).
|
||
`chatReady` is true for both `"cold"` and `"loaded"` since cold models still work.
|
||
AppHeader shows five distinct visual states: gray pulse (checking), red (Ollama down), orange
|
||
(model not installed), yellow pulse (cold), green (loaded). Each state has a short inline text
|
||
label ("Cold", "Ready", "Offline", etc.) visible without hovering, plus a tooltip with detail.
|
||
After `warmModel()` is called, a fast 5s polling loop runs for up to 60s until the indicator
|
||
transitions to green (instead of waiting for the 30s poll cycle).
|
||
- Hot/cold model indicators: `/api/chat/ps` proxies Ollama `/api/ps`; ModelSelector shows green/red emoji circles
|
||
- Ollama configured with `OLLAMA_MAX_LOADED_MODELS=2` and `OLLAMA_KEEP_ALIVE=30m`
|
||
- Timeout tuning: connect timeout 30s (cold model loading), warm timeout 300s, pull timeout 1800s
|
||
- SSE reconnection failure shows error toast instead of silently recovering
|
||
- **LLM tool calling:** Models with tool support can create tasks, create/update notes, search and list
|
||
notes/tasks, and manage CalDAV events/todos on behalf of the user during chat. Multi-round tool loop
|
||
(max 5 rounds) allows the LLM to execute tools and then produce a natural language response
|
||
incorporating results. Tool call results are persisted in message `tool_calls` JSONB column and
|
||
rendered as compact ToolCallCard components. SSE emits `tool_call` events for real-time rendering.
|
||
System prompt includes today's date for relative date resolution. Graceful degradation: models without
|
||
tool support respond normally.
|
||
Full tool suite:
|
||
- `create_task` / `create_note` — create new items; protected by a three-layer duplicate guard:
|
||
1. **Exact title** (case-insensitive via `get_note_by_title`) → hard block, redirect to `update_note`
|
||
2. **Fuzzy title** (`SequenceMatcher` ≥82%; strips punctuation before word search for candidates) → hard block
|
||
3. **Semantic content** (`semantic_search_notes` threshold 0.87, graceful no-op if embedding model down) → soft block with `requires_confirmation:true`; model must ask user then retry with `confirmed:true`
|
||
Both tools have an optional `confirmed` parameter (not required by default — only needed when a content-similarity warning fires).
|
||
- `create_project` — always requires `confirmed:true` before creation (structural, must be intentional);
|
||
additionally guarded by exact + fuzzy title checks (≥82%) against existing projects
|
||
- `create_milestone` — always requires `confirmed:true`; additionally guarded by exact + fuzzy title
|
||
checks against existing milestones within the same project
|
||
- `update_note` — edit note content (replace/append) AND update task fields: `status`, `priority`,
|
||
`due_date`, `tags` (with `tag_mode`: replace/add/remove); finds by exact title first, falls back to fuzzy search
|
||
- `delete_note` / `delete_task` — permanently delete (require user confirmation via confirm UI;
|
||
validates type so delete_note won't delete a task and vice versa; clears note context cache)
|
||
- `get_note` — retrieve full note body by title/keyword (search_notes only returns 200-char preview)
|
||
- `list_notes` — browse notes by recency/keyword/tags with configurable limit; notes only (use list_tasks for tasks)
|
||
- `list_tasks` — filter tasks by `status`, `priority`, `due_before`, `due_after`, `limit`;
|
||
backed by `list_notes(is_task=True)`; enables "overdue tasks", "high priority", "in progress" queries
|
||
- `search_notes` — keyword search across notes and tasks; optional `type: "note"|"task"` filter
|
||
- Full CalDAV suite: `create_event`, `list_events`, `search_events`, `update_event`, `delete_event`,
|
||
`list_calendars`, `create_todo`, `list_todos`, `search_todos`, `update_todo`, `complete_todo`, `delete_todo`
|
||
(`search_todos` keyword-filters the todo list — companion to `list_todos`)
|
||
- **Duplicate guard helpers** in `services/tools.py`: `_fuzzy_title_match(title, candidates, threshold=0.82)` uses `SequenceMatcher`; semantic check uses `semantic_search_notes` at threshold 0.87 (vs. 0.45 for RAG suggestions). `_PUNCT_RE` strips punctuation from title before word-search to avoid false-negative candidates (e.g. "Shackled - Game Premise" → "Shackled Game Premise" query).
|
||
- **Streaming status transparency:** The backend emits `status` SSE events at each pipeline stage
|
||
so the user always sees what's happening instead of a blank progress dot. Stages:
|
||
(1) intent ack text streamed as a `chunk` event (tool responses — TTFT ~400ms) or
|
||
`"Generating response..."` status event (chat-only responses);
|
||
(2) human-readable tool label (e.g. `"Creating calendar event..."`) before each tool executes;
|
||
(3) `"Composing response..."` before tool follow-up rounds.
|
||
Frontend: `chat.ts` stores `streamingStatus` ref, cleared on first content chunk or on done/error.
|
||
`ChatView.vue` shows a pulsing dot + italic label above the content while status is active, then
|
||
falls back to the blinking cursor when content streams in. `HomeView.vue` dashboard panel shows
|
||
the status label in place of `...` before any content arrives.
|
||
- **Intent routing (intent-first pipeline, Phase 21):** On the first round, `build_context()` and
|
||
`classify_intent()` run concurrently. Once intent returns (~400ms), the pipeline immediately acts:
|
||
if a tool is detected, the intent's one-sentence `ack` field is streamed as the first chunk
|
||
(becoming TTFT), the tool executes, then the main model generates a follow-up response with the
|
||
tool result. For chat-only responses, the model streams directly with no ack prefix.
|
||
No optimistic streaming queue or race — eliminates wasted GPU prefill when intent won the race.
|
||
`IntentResult.ack` (one-sentence acknowledgment) is embedded in the intent JSON output, so no
|
||
additional LLM call is needed for acknowledgment. Intent model `max_tokens` 350 (was 200).
|
||
Dedicated intent model configurable via `OLLAMA_INTENT_MODEL` env var (default `qwen2.5:7b`)
|
||
or per-user `intent_model` setting — smaller/faster model for routing. Main model default
|
||
is `qwen3:latest` (configurable via `OLLAMA_MODEL` env var or per-user `default_model` setting
|
||
— both settable as dropdowns in the Settings UI populated from installed models).
|
||
`OLLAMA_NUM_CTX` env var (default 8192) controls the KV cache context window for all generation
|
||
calls; reducing from 32768 cuts VRAM usage ~4x without affecting most conversations.
|
||
Supports confidence levels ("high"/"medium"/"low") — low-confidence intents fall through to streaming.
|
||
Passes last 6 user/assistant turns as history for anaphora resolution ("move it", "cancel that").
|
||
Intent router rules cover: update/delete events, CalDAV todos, time-period → list_events (not
|
||
search_events), update_note vs create_note disambiguation, reminder_minutes conversion,
|
||
delete_note vs delete_task disambiguation, get_note for "read/show me this note", list_notes for
|
||
"browse/list notes", tag management via update_note (tag_mode add/remove), search_todos.
|
||
`generate_completion` (used by intent classifier) retries on HTTP 500 (3 attempts, 3s/6s delays)
|
||
to handle cold model loading without failing intent classification.
|
||
- **Intent performance optimizations:**
|
||
- **Intent skip heuristic:** `_should_skip_intent(msg)` in `generation_task.py` skips the intent
|
||
model call entirely for short messages (≤10 words) that contain none of the `_INTENT_TRIGGER_WORDS`
|
||
frozenset (~50 action/object/date words). Saves 400–800ms for conversational replies like "thanks",
|
||
"can you explain that?", "okay" without risking missed tool calls on longer or action-verb messages.
|
||
- **Intent `num_ctx=4096`:** Intent classification calls use a 4k context window (override) instead
|
||
of the default, reducing VRAM pressure and prefill time on every request.
|
||
- **Prior-work fast-path:** `_PRIOR_WORK_REFS` regex in `intent.py` detects phrases like "research
|
||
you did", "note you made", "using your research", "based on the research" etc. and returns no-tool
|
||
immediately — skips the LLM call entirely so the main model answers using `search_notes`/context
|
||
instead of firing a web search. Prevents `search_web` being triggered when the user references
|
||
existing notes.
|
||
- **`search_web` scoping rules:** Intent prompt explicitly prohibits `search_web` for creative/
|
||
brainstorming requests, game design, writing help, or when the user references existing notes.
|
||
Creative/ideation requests ("think of", "come up with", "brainstorm") always route to null (chat).
|
||
`search_web` is only for genuinely new real-time facts not in the user's notes.
|
||
- **Image search with local cache (Phase 23):** `search_images` tool (SearXNG `categories=images`) fetches
|
||
images server-side, stores them on disk, and serves them from `/api/images/<id>` — the user's browser
|
||
never contacts the original image host. Original URLs preserved for citation.
|
||
- New migration `0016_add_image_cache.py`: `image_cache` table (`id`, `url_hash`, `original_url`,
|
||
`source_domain`, `title`, `content_type`, `file_size`, `file_ext`, `fetched_at`)
|
||
- `services/images.py`: `fetch_and_store_image()` — SHA-256 dedup, content-type validation (`image/*`
|
||
only), 5 MB cap, same-origin `Referer` header to bypass hotlink protection, `IntegrityError` race
|
||
handling. `get_image_record()`, `get_image_path()`.
|
||
- `routes/images.py`: `GET /api/images/<id>` — no auth (IDs are opaque SHA-256-derived); `Cache-Control:
|
||
max-age=86400`; 404 if file missing from disk.
|
||
- `research.py`: `_search_searxng_images(query)` — SearXNG with `categories=images`, returns
|
||
`[{img_src, page_url, title, source_domain}]` with same 429-retry logic as text search.
|
||
- `tools.py`: `_IMAGE_TOOLS` list + `search_images` branch in `execute_tool` — fetches top 2 images,
|
||
returns `{type: "image_search", data: {images: [{local_url, page_url, source_domain, title}]}}`.
|
||
- `intent.py`: routing rule — only triggers on explicit visual language ("show me", "what does X look
|
||
like", "picture of", "photo of"). Factual/description questions stay as null (chat).
|
||
- Config: `IMAGE_CACHE_DIR` (default `/data/images`), `IMAGE_MAX_BYTES` (default 5 MB).
|
||
- Docker: named volume `app_data` mounted at `/data` (covers all future persistent storage, not just
|
||
images). Bind-mount alternative `./data:/data` documented in compose comments.
|
||
- No CSP changes needed — `/api/images/` is same-origin, already covered by `img-src 'self'`.
|
||
- **Suggested notes improvements:** `semantic_search_notes` now returns `list[tuple[float, Note]]`
|
||
(was `list[Note]`); scores threaded through `context_meta["auto_notes"]` to frontend. Sidebar shows
|
||
`%` badge per note: green ≥75%, amber 60–74%, muted 45–59%. Threshold raised 0.30 → 0.45 (only
|
||
genuinely relevant notes shown). Limit raised 3 → 8 (no added compute — threshold is the real gate).
|
||
Keyword fallback notes carry `score: null` (no badge shown).
|
||
- **Quick-capture endpoint:** `POST /api/quick-capture` in `routes/quick_capture.py` (session auth via
|
||
cookie). Takes `{"text": "natural language string"}`, runs `classify_intent` filtered to creation-only
|
||
tools (`create_note`, `create_task`, `create_event`, `create_todo`), calls `execute_tool`, and returns
|
||
a single synchronous JSON response — no SSE, no conversation ID. Falls back to `create_note` if intent
|
||
is unclear or low-confidence. Response: `{"success", "type", "message", "data", "fallback?"}`.
|
||
Designed for Android/mobile quick-capture use case. Auth: session cookie from `POST /api/auth/login`.
|
||
- **Bug fixes (this session):**
|
||
- `create_note`/`create_task` list-title crash: `execute_tool` now validates `title` is a string and
|
||
returns a structured error so the model self-corrects with individual calls (vs. crashing asyncpg).
|
||
- AI Assist panel 400 errors: `routes/notes.py` assist route was missing `or Config.OLLAMA_MODEL`
|
||
safety net — empty `default_model` DB value was passed to Ollama as-is, causing 400.
|
||
- Note picker → persistent context: paperclip attachment now calls `includeNote()` directly
|
||
(persistent `includedNotes`) instead of the one-shot `attachedNote` pattern.
|
||
- **Default model setting fix:** `delete_setting()` added to `services/settings.py` — saving an empty
|
||
model value in Settings now deletes the DB row rather than storing `""`, so `get_setting()` falls
|
||
back to the `Config` default. Safety net `or Config.OLLAMA_MODEL` guards added in `routes/chat.py`
|
||
status, message, and summarize routes to prevent empty-string model from breaking readiness indicator.
|
||
- **Web research pipeline (Phase 22):** `research.py` implements a full autonomous research pipeline
|
||
triggered by "research X and make a note" (intent routes to `research_topic` tool) or via the 🔍
|
||
Research button in ChatView (sends "Research: {topic}" message).
|
||
Pipeline stages:
|
||
1. Intent model generates 5 focused sub-queries as a JSON array (falls back to `[topic]` on parse failure)
|
||
2. All 5 SearXNG queries execute in parallel with 200ms stagger (avoids hammering rate limiter)
|
||
3. All unique URLs (up to 15) fetched in parallel via `asyncio.gather`; duplicates deduplicated by URL
|
||
4. Failed fetches filtered; up to 12 sources passed to synthesis LLM
|
||
5. Synthesis uses `stream_chat` with `num_ctx=16384`, `num_predict=8192` — tokens stream into
|
||
the chat buffer in real time (user sees the note being written); minimum 2500 words, 6+ topic-appropriate
|
||
sections (topic determines section structure, not hardcoded), detailed prose, `## Sources` section
|
||
6. Note created with `tags=["research"]`; "Research complete!" separator appended to chat
|
||
Also includes `search_web` tool for lightweight single-query searches (no note created; results
|
||
returned to LLM for conversational answer). Both tools only added to tool list when `SEARXNG_URL` is set.
|
||
SearXNG `429` handling: 3-attempt retry with exponential backoff per query.
|
||
Sub-query JSON parsed with `json.JSONDecoder().raw_decode()` to handle trailing model text.
|
||
Frontend: `ToolCallCard.vue` handles `web_search` (external links), `research_pending`, `research_note` types.
|
||
Settings: `GET /api/settings/search?q=` proxy + Search Test section in SettingsView.
|
||
Settings UI: 2-column grid layout (paired simple cards, `full-width` for complex sections).
|
||
Docker: `OLLAMA_NUM_PARALLEL=2` to prevent research and live chat queuing each other.
|
||
SearXNG setup: add app server IP to `botdetection.ip_lists.pass_ip` in SearXNG `settings.yml`
|
||
to bypass rate limiter for trusted backend requests while keeping it active for public users.
|
||
- **CalDAV calendar integration:** Per-user CalDAV settings (URL, username, password, calendar name, timezone).
|
||
LLM tools: `create_event` (all_day, recurrence, timezone, reminder_minutes, attendees, calendar_name),
|
||
`list_events`, `search_events`, `update_event`, `delete_event`, `list_calendars`,
|
||
`create_todo`, `list_todos`, `search_todos`, `update_todo`, `complete_todo`, `delete_todo`.
|
||
All-day events use iCalendar DATE values; recurrence uses RRULE (e.g. `FREQ=YEARLY`).
|
||
VALARM components added for reminders. Attendees via mailto: vCalAddress.
|
||
Multi-calendar search: when no specific calendar configured, all calendars are scanned.
|
||
Runs synchronous caldav library calls in asyncio executor. Settings UI for CalDAV config including timezone.
|
||
- **Dedicated tag chip input (Phase 20):** Tags are now a first-class UI field. `TagInput.vue` is a
|
||
chip-based input placed between the title and body in both editor views. Chips confirmed with
|
||
Enter/comma/autocomplete click; Backspace removes last chip; × removes individual chips. Autocomplete
|
||
fetches from `/api/notes/tags?q=`. Tags saved as explicit `tags: string[]` in create/update payloads.
|
||
`TagSuggestion` Tiptap extension removed; `TagDecoration` kept for legacy inline `#tag` display.
|
||
- **LLM-suggested tags:** Backend service (`tag_suggestions.py`) prompts LLM with existing user tags
|
||
and note content, returns 3-5 relevant tag suggestions filtered against `current_tags` (not body text).
|
||
Exposed via `POST /api/notes/suggest-tags` (accepts `current_tags` list) and `POST /api/notes/:id/append-tag`.
|
||
Integrated in:
|
||
(1) Editor views — "Suggest tags" button shows clickable pills that add chips to TagInput (not body);
|
||
(2) Chat tool calls — `create_note`/`create_task` results include `suggested_tags`, rendered as
|
||
pills in ToolCallCard with one-click apply via append-tag API.
|
||
LLM instructed to use the `tags` parameter, not embed `#tag` text in note body.
|
||
|
||
### Projects & Milestones (Phases A + G)
|
||
- **Project model** (`models/project.py`): id, user_id (FK CASCADE), title, description, goal, status ("active"/"completed"/"archived"), color, timestamps.
|
||
- **Milestone model** (`models/milestone.py`): id, user_id, project_id (FK CASCADE), title, description, status, order_index, timestamps. Hierarchy: **Project → Milestone → Task**.
|
||
- **`notes` table**: `project_id` FK (SET NULL) + `milestone_id` FK (SET NULL) columns. `parent_id` column now has a FK constraint to `notes.id` (SET NULL) to enable sub-tasks.
|
||
- **Migrations**: `0017_add_projects.py`, `0020_add_milestones.py` (milestone_id on notes).
|
||
- **Services**: `services/projects.py` (CRUD + `get_or_create_project` + `get_project_summary`); `services/milestones.py` (CRUD + `get_milestone_progress` + `get_project_milestone_summary`).
|
||
- **Routes**: `routes/projects.py` under `/api/projects`; `routes/milestones.py` under `/api/projects/<pid>/milestones`.
|
||
- **LLM tools**: `create_project`, `list_projects`, `get_project`, `update_project`; `create_milestone`, `list_milestones`; `create_note`/`create_task`/`update_note` accept optional `project` + `milestone` + `parent_task` params.
|
||
- **Frontend**: `ProjectListView.vue` (card grid, stacked milestone progress bars per card), `ProjectView.vue` (milestone-grouped kanban + inline milestone management + `+` button in Todo column header → `/tasks/new?projectId=X&milestoneId=Y`), `ProjectSelector.vue` (dropdown used in NoteEditorView + TaskEditorView), `MilestoneSelector.vue` (used in NoteEditorView + TaskEditorView).
|
||
- **Sub-tasks in TaskEditorView**: Sub-tasks section fetches child tasks (`parent_id=<id>`), shows toggle + inline create form. URL query params `?projectId=X&milestoneId=Y&parentId=Z` pre-fill editor fields on new task.
|
||
- **Types**: `frontend/src/types/note.ts` Note interface now includes `project_id: number | null` and `milestone_id: number | null`.
|
||
- `app.py` registers `projects_bp` and `milestones_bp`; router adds `/projects` and `/projects/:id`.
|
||
- **`services/notes.py`**: `list_notes()` accepts `parent_id` filter and new `milestone_ids: list[int]` param — when provided with `project_id`, uses `OR (project_id=X OR milestone_id IN (...))` so tasks assigned to a milestone-but-not-project are still returned. `create_note()` auto-sets `project_id` from the milestone's project when `milestone_id` is provided and `project_id` is omitted.
|
||
- **`services/milestones.py`**: `find_milestone_by_title()` for cross-project milestone lookup.
|
||
- **`GET /api/notes`** now accepts additional query params: `project_id`, `milestone_id`, `parent_id`, `type` (`note`/`task`/`all`).
|
||
- **`routes/projects.py` `GET /api/projects/:id/notes`**: fetches project's milestone IDs and passes them via `milestone_ids` to `list_notes`, so tasks assigned via milestone (but lacking `project_id`) are included.
|
||
- **`routes/tasks.py` bug fix**: `POST /api/tasks` and `PUT /api/tasks/:id` were silently dropping `project_id`, `milestone_id`, and `parent_id` from the request body. Both routes now read and pass all three fields. `GET /api/tasks/:id` now includes `parent_title` in the response (secondary lookup when `parent_id` is set).
|
||
- **`routes/notes.py`**: Added `PATCH /api/notes/:id` for partial updates (same accepted fields as PUT). Used by sub-task status toggle in the frontend.
|
||
- **`services/tools.py`**: `list_notes` tool supports project filter + `updated_at`; `list_tasks` tool supports milestone without requiring project; `tag_mode` defaults to `add`; fail-fast project resolution raises tool error immediately.
|
||
|
||
### RAG Auto-injection (Phase B)
|
||
- Notes scoring ≥0.60 cosine similarity are injected automatically into every chat system prompt (max 3, up to 800 chars each) under `--- Relevant Notes ---` heading.
|
||
- `semantic_search_notes()` accepts `threshold` param (default 0.45 for sidebar suggestions; 0.60 for auto-inject).
|
||
- `build_context()` constants: `RAG_AUTO_THRESHOLD=0.60`, `RAG_AUTO_LIMIT=3`, `RAG_AUTO_SNIPPET=800`.
|
||
- `context_meta` adds `auto_injected_notes` list + `auto_injected: bool` flag on each `auto_notes` item.
|
||
- `excluded_note_ids` param in `build_context()` + POST body lets users remove a note from auto-injection.
|
||
- ChatView sidebar: "Auto-included" section (green border) above "Suggested" and "In Context".
|
||
|
||
### Summarization Improvements (Phase C)
|
||
- `_HISTORY_SUMMARY_THRESHOLD` raised 20 → 30; `_HISTORY_KEEP_RECENT` raised 6 → 8; summary `max_tokens` raised 200 → 400.
|
||
- Improved summary prompt captures: note/task/project names, decisions, open questions, topic arc.
|
||
- Two-pass summarization for histories >50 messages (first half → summary_a, combined → final).
|
||
|
||
### Browser Push Notifications (Phase E)
|
||
- **`models/push_subscription.py`**: PushSubscription — endpoint, p256dh, auth, user_agent; UNIQUE(user_id, endpoint).
|
||
- **Migration**: `0018_add_push_subscriptions.py` (down_revision="0017").
|
||
- **`services/push.py`**: `vapid_enabled()`, `save_subscription()`, `delete_subscription()`, `send_push_notification()` (lazy-imports pywebpush, fire-and-forget, removes 410 Gone subs). `ensure_vapid_keys()` auto-generates an EC P-256 key pair on first boot, saves to `/data/vapid_keys.json` (inside `app_data` volume) so it survives container restarts.
|
||
- **`routes/push.py`**: `GET /api/push/vapid-public-key`, `POST/DELETE /api/push/subscribe`.
|
||
- Config: `VAPID_PRIVATE_KEY`, `VAPID_PUBLIC_KEY`, `VAPID_CLAIMS_SUB` env vars — all **optional** (keys are auto-generated at startup if absent). Env vars still take precedence for deployments that manage keys externally.
|
||
- `generation_task.py`: fires push after `buf.state = COMPLETED` (guarded by `vapid_enabled()`).
|
||
- `pywebpush>=2.0` added to `pyproject.toml`.
|
||
- **Frontend**: `frontend/public/sw.js` (push + notificationclick handlers); `frontend/src/stores/push.ts` (isSupported, permission, isSubscribed, subscribe/unsubscribe); SettingsView "Push Notifications" toggle.
|
||
|
||
### PWA Manifest (Phase F)
|
||
- `frontend/public/manifest.json`: name, short_name, start_url, display: standalone, icons.
|
||
- `index.html`: `<link rel="manifest">`, `<meta name="theme-color">`, Apple mobile meta tags.
|
||
- `main.ts`: service worker registration.
|
||
- Installable on iOS (Share → Add to Home Screen) and Android. Push works on Android (iOS 16.4+ partial).
|
||
|
||
### Authentication & User Management
|
||
- Session cookie auth with bcrypt, first-user-is-admin, orphaned data claiming
|
||
- Per-user data isolation across all resources
|
||
- Registration auto-closes after first user; admin toggle; invitation-based registration
|
||
- Email invitation system: admin sends invite → branded email → `/register-invite` token flow
|
||
- Password reset: email-based, SHA256-hashed tokens, 1-hour expiry
|
||
- Session cookie hardening: HttpOnly, SameSite=Lax, optional Secure flag
|
||
- Admin user management: list, delete, invite, revoke
|
||
- **OAuth/OIDC SSO (Phase 18):** Authorization Code + PKCE flow via any OIDC provider (Authentik, Keycloak, etc.)
|
||
- `GET /api/auth/oauth/login` → generates state + PKCE verifier, stores in session, redirects to provider
|
||
- `GET /api/auth/oauth/callback` → exchanges code, fetches userinfo, sets session, redirects to `/`
|
||
- Account linking: sub lookup → email auto-link → auto-provision with collision-safe username
|
||
- `LOCAL_AUTH_ENABLED=false` hides password form and blocks `POST /api/auth/login|register`
|
||
- OAuth-only users have `password_hash = NULL`; `authenticate()` returns None for them
|
||
- OIDC discovery response cached in-process after first fetch; no new Python dependencies (`httpx` already present)
|
||
- Config: `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` (or `_FILE`), `OIDC_SCOPES`
|
||
- **Email change:** `PUT /api/auth/email` — requires current password for local-auth users; OAuth-only users can change freely; checks email uniqueness; updates `authStore.user` in-place
|
||
|
||
### Notifications & Email
|
||
- SMTP email service (aiosmtplib): STARTTLS (587) and implicit TLS (465)
|
||
- Security alerts: login, failed login, logout, password change (fire-and-forget)
|
||
- Task due date reminders: hourly background check, grouped per user, dedup via logs
|
||
- Invitation and password reset emails with branded HTML templates
|
||
- Per-user notification preferences (task reminders, security alerts)
|
||
- Admin SMTP configuration via Settings UI with test email
|
||
- **Shared email template** (`_email_html` in `email.py`): gray outer background, white card, indigo header with inline SVG logo (`_EMAIL_LOGO_SVG`) + "Fabled Assistant" wordmark, content area, footer; used by all six email types (security alert, password reset, reset success, invitation, task reminder, test email)
|
||
|
||
### Logging & Observability
|
||
- Single `app_logs` table: audit (security events), usage (API requests), error (unhandled exceptions)
|
||
- Request logging middleware with timing (skips log endpoints to avoid recursion)
|
||
- Admin log viewer: stats summary, category/search/date filters, paginated table, expandable JSON details
|
||
- Configurable retention via `LOG_RETENTION_DAYS` (default 90), hourly cleanup
|
||
|
||
### Settings & Admin
|
||
- Per-user key-value settings store (assistant name, default model, notification prefs)
|
||
- Admin: backup/restore (full or per-user JSON), SMTP config, base URL, registration toggle, user management, log viewer
|
||
- Configurable base URL for email links (admin setting, env var fallback)
|
||
|
||
### UI & Theming
|
||
- Dark/light theme with CSS custom properties, design tokens, `prefers-color-scheme` detection; light mode uses indigo brand color (`--color-primary: #6366f1`) and indigo-tinted off-white backgrounds (`--color-bg: #f5f5fb`, `--color-bg-secondary: #ededf5`) with white cards to pop content
|
||
- Responsive design: breakpoints (480/768/1024), hamburger menu, mobile touch targets (44px), sidebar overlays
|
||
- App shell: navbar always visible, 100dvh flex layout, all views fit within viewport
|
||
- Toast notifications (success/error/warning, 4s auto-dismiss)
|
||
- DOMPurify sanitization on all rendered markdown
|
||
- **Site-wide max-width:** List/chat/settings views 1200px; editor pages 1400px; note/task viewer layout 1400px (content area 1100px)
|
||
- **Favicon:** `frontend/public/favicon.svg` — light mode uses indigo brand color (`#6366f1` fill, `#4f46e5` stroke, `#a5b4fc` lines); dark mode uses light gray; gold sparkle always visible; `@media (prefers-color-scheme: dark)` in SVG `<style>`
|
||
|
||
### Infrastructure
|
||
- Multi-stage Dockerfile: Node build → Python runtime, auto-migration on startup
|
||
- Docker Compose (dev) with app service healthcheck (`/api/health`, 10s interval, 30s start period) + Docker Swarm production stack with secrets, overlay networks, health checks
|
||
- `.dockerignore` prevents secrets, `node_modules`, `__pycache__`, `.env.*` from leaking into build context
|
||
- Production compose (`docker-compose.prod.yml`): `TRUST_PROXY_HEADERS=true` + `SECURE_COOKIES=true` set for Traefik deployments; port 5000 not published directly (Traefik routes internally)
|
||
- Quart serves Vue SPA from static + REST API under `/api/`; 404 handler for SPA routing
|
||
- Security headers applied in `after_request`: `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy`, `Content-Security-Policy`
|
||
- In-memory sliding-window rate limiter on all auth endpoints (login, register, forgot/reset password); proxy-aware client IP with `TRUST_PROXY_HEADERS`
|
||
- SQLAlchemy async engine configured with `pool_pre_ping=True` (tests connections before use, discards stale ones after Postgres restart) and `pool_recycle=1800` (recycles idle connections every 30 min to prevent TCP/firewall staleness)
|
||
- Alembic migrations: 20 migrations (0001–0020), all raw SQL with idempotency guards (IF NOT EXISTS, DO $$ BEGIN...EXCEPTION)
|
||
- Config from env vars + Docker secrets file support (`_read_secret`)
|
||
|
||
## Development Workflow
|
||
- All development and testing done via Docker: `docker compose up --build`
|
||
- No local dependency installation — everything containerized
|
||
- Frontend dev: Vite dev server with proxy to Quart (via Docker)
|
||
- Production build: Dockerfile multi-stage — Vite builds Vue into static files,
|
||
Quart serves them
|
||
- To reset database: `docker compose down -v && docker compose up --build`
|
||
|
||
## Android Companion App
|
||
|
||
A native Flutter app at `/home/bvandeusen/Nextcloud/Projects/fabled_app` (separate repository).
|
||
|
||
### Stack
|
||
- Flutter + Dart, Riverpod (state), GoRouter (navigation), Dio (HTTP), PersistCookieJar (session)
|
||
- SSE streaming for chat using `fetch` + `ReadableStream` bridge
|
||
- Self-update support via Forgejo release API (`update_provider.dart`)
|
||
|
||
### Architecture
|
||
- **Data layer**: `lib/data/models/`, `lib/data/api/`, `lib/data/repositories/`
|
||
- **State**: Riverpod `AsyncNotifierProvider` per resource in `lib/providers/`
|
||
- **Navigation**: GoRouter with `ShellRoute` for tabbed main shell; `_RouterNotifier` refreshes on auth change
|
||
|
||
### Models & API Coverage
|
||
|
||
| Resource | Model fields | API endpoints |
|
||
|----------|-------------|---------------|
|
||
| Note | id, title, body, tags, project_id, milestone_id, created_at, updated_at | GET/POST /api/notes, GET/PUT/DELETE /api/notes/:id |
|
||
| Task | id, title, body, status, priority, due_date, project_id, milestone_id, parent_id, created_at, updated_at | GET/POST /api/tasks, GET/PUT/DELETE /api/tasks/:id |
|
||
| Project | id, title, description, goal, status, color, created_at, updated_at | GET/POST /api/projects, GET/PATCH/DELETE /api/projects/:id |
|
||
| Conversation | standard chat fields | GET/POST conversations, SSE stream |
|
||
| QuickCapture | text → type+title+message | POST /api/quick-capture |
|
||
|
||
### Navigation Shell (4 tabs)
|
||
Notes · Tasks · Projects · Chat — bottom `NavigationBar` on phone; `NavigationRail` on tablet/landscape.
|
||
Quick Capture bar at the top of the shell (persists across all tabs); Settings accessible from top-right icon.
|
||
|
||
### Feature Status
|
||
|
||
| Feature | Status | Notes |
|
||
|---------|--------|-------|
|
||
| Notes CRUD | ✅ | tags chip input; project selector in editor |
|
||
| Tasks CRUD | ✅ | project selector in editor |
|
||
| Projects list | ✅ | active/archived sections; long-press status change; create dialog |
|
||
| Chat + SSE | ✅ | full streaming |
|
||
| Quick Capture | ✅ | offline queue with retry |
|
||
| Tags | ✅ (model + API) | Chip input in NoteEditScreen; typed as `List<String>` |
|
||
| Project assignment | ✅ | `ProjectSelector` dropdown in Note + Task editors |
|
||
| Milestones | ❌ deferred | Too granular for mobile; web UI handles it |
|
||
| Push notifications | ❌ incompatible | Backend uses browser VAPID; Flutter needs FCM/APNs — separate implementation required |
|
||
| CalDAV settings | ❌ intentional | Server-side config only; not exposed in mobile app |
|
||
|
||
### Key Files
|
||
```
|
||
lib/
|
||
app.dart # GoRouter + _Shell + _QuickCaptureBar
|
||
core/constants.dart # Routes.*
|
||
data/
|
||
models/note.dart # Note (tags, project_id, milestone_id)
|
||
models/task.dart # Task (project_id, milestone_id, parent_id)
|
||
models/project.dart # Project
|
||
api/notes_api.dart # create/update accept tags, project_id
|
||
api/tasks_api.dart # create accepts project_id
|
||
api/projects_api.dart # full CRUD
|
||
repositories/notes_repository.dart
|
||
repositories/tasks_repository.dart
|
||
repositories/projects_repository.dart
|
||
providers/
|
||
api_client_provider.dart # all API + repository providers
|
||
notes_provider.dart # NotesNotifier
|
||
tasks_provider.dart # TasksNotifier
|
||
projects_provider.dart # ProjectsNotifier
|
||
screens/
|
||
notes/note_edit_screen.dart # chip tag input + ProjectSelector
|
||
tasks/task_edit_screen.dart # ProjectSelector
|
||
projects/project_list_screen.dart
|
||
widgets/
|
||
project_selector.dart # reusable DropdownButtonFormField
|
||
```
|
||
|
||
### API Compatibility Notes
|
||
- `GET /api/projects/:id` returns a flat JSON object (not `{project: ...}` wrapper); includes `summary` field.
|
||
- `POST /api/projects` returns project dict directly (201).
|
||
- `PATCH /api/projects/:id` returns updated project dict.
|
||
- Task body field name is `body` (not `description`) — Flutter maps `description` → `body` on serialize.
|
||
|
||
## Backlog
|
||
- Calendar/timeline view for tasks
|
||
- Import/export (Markdown files, JSON)
|
||
- Email integration (read/send emails from chat via IMAP/SMTP tools)
|
||
- Session invalidation on user deletion
|
||
- **Note relation map (Obsidian-style graph):** Interactive force-directed graph visualizing connections between
|
||
notes via wikilinks (`[[Title]]`) and shared tags. Nodes = notes/tasks; edges = wikilink references or
|
||
tag co-occurrence. Clicking a node navigates to that note. Filter by tag or depth. Useful for discovering
|
||
clusters of related notes and orphaned notes with no connections.
|
||
- **Flutter push notifications:** Requires FCM/APNs integration (separate from web VAPID). Would need
|
||
a FCM server key in Config and a new notification pathway in `generation_task.py`.
|
||
- **Flutter milestone support:** Milestone grouping in project view deferred; could add as a filtered
|
||
task list view once the feature is well-established on web.
|