chore: ignore docs/superpowers, docs/plans, docs/specs — keep only root docs
This commit is contained in:
@@ -1,538 +0,0 @@
|
||||
# Backup Service Rewrite Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Rewrite `services/backup.py` so that full and user backup/restore correctly includes every model added since the original implementation (projects, milestones, task logs, drafts, versions), with correct FK re-mapping on restore.
|
||||
|
||||
**Architecture:** Bump backup JSON format to version 2. Export is additive — all new tables exported. Restore builds an ID map for each table and patches FK references in the correct dependency order. V1 backups continue to restore via the existing code path.
|
||||
|
||||
**Tech Stack:** Python/SQLAlchemy 2.0 async, no new dependencies.
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-03-11-backup-rewrite-design.md`
|
||||
|
||||
**Dependency note:** This plan can be split into Part A (pre-sharing models) and Part B (sharing models). Part A is independent and should be done first.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Extend export — full backup
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/fabledassistant/services/backup.py`
|
||||
|
||||
- [ ] **Step 1: Read the current `export_full_backup()` function**
|
||||
|
||||
Understand what is currently exported: users, notes (partial fields), conversations+messages, settings.
|
||||
|
||||
- [ ] **Step 2: Rewrite `export_full_backup()` to version 2**
|
||||
|
||||
Add all missing models to the import list at the top of `backup.py`:
|
||||
```python
|
||||
from fabledassistant.models.project import Project
|
||||
from fabledassistant.models.milestone import Milestone
|
||||
from fabledassistant.models.task_log import TaskLog
|
||||
from fabledassistant.models.note_draft import NoteDraft
|
||||
from fabledassistant.models.note_version import NoteVersion
|
||||
from fabledassistant.models.push_subscription import PushSubscription
|
||||
```
|
||||
|
||||
Rewrite `export_full_backup()`:
|
||||
```python
|
||||
async def export_full_backup() -> dict:
|
||||
async with async_session() as session:
|
||||
users = (await session.execute(select(User))).scalars().all()
|
||||
projects = (await session.execute(select(Project))).scalars().all()
|
||||
milestones = (await session.execute(select(Milestone))).scalars().all()
|
||||
notes = (await session.execute(select(Note))).scalars().all()
|
||||
task_logs = (await session.execute(select(TaskLog))).scalars().all()
|
||||
note_drafts = (await session.execute(select(NoteDraft))).scalars().all()
|
||||
note_versions = (await session.execute(select(NoteVersion).order_by(NoteVersion.note_id, NoteVersion.version_number))).scalars().all()
|
||||
conversations = (await session.execute(
|
||||
select(Conversation).options(selectinload(Conversation.messages))
|
||||
)).scalars().all()
|
||||
settings = (await session.execute(select(Setting))).scalars().all()
|
||||
push_subs = (await session.execute(select(PushSubscription))).scalars().all()
|
||||
|
||||
return {
|
||||
"version": 2,
|
||||
"scope": "full",
|
||||
"exported_at": datetime.now(timezone.utc).isoformat(),
|
||||
"_security_notice": (
|
||||
"This backup contains hashed passwords and push subscription keys. "
|
||||
"Store it securely and restrict access."
|
||||
),
|
||||
"users": [
|
||||
{
|
||||
"id": u.id,
|
||||
"username": u.username,
|
||||
"email": u.email,
|
||||
"password_hash": u.password_hash,
|
||||
"oauth_sub": u.oauth_sub,
|
||||
"role": u.role,
|
||||
"session_version": u.session_version,
|
||||
"created_at": u.created_at.isoformat(),
|
||||
}
|
||||
for u in users
|
||||
],
|
||||
"projects": [
|
||||
{
|
||||
"id": p.id,
|
||||
"user_id": p.user_id,
|
||||
"title": p.title,
|
||||
"description": p.description,
|
||||
"goal": p.goal,
|
||||
"status": p.status,
|
||||
"color": p.color,
|
||||
"created_at": p.created_at.isoformat(),
|
||||
"updated_at": p.updated_at.isoformat(),
|
||||
}
|
||||
for p in projects
|
||||
],
|
||||
"milestones": [
|
||||
{
|
||||
"id": m.id,
|
||||
"user_id": m.user_id,
|
||||
"project_id": m.project_id,
|
||||
"title": m.title,
|
||||
"description": m.description,
|
||||
"status": m.status,
|
||||
"order_index": m.order_index,
|
||||
"created_at": m.created_at.isoformat(),
|
||||
"updated_at": m.updated_at.isoformat(),
|
||||
}
|
||||
for m in milestones
|
||||
],
|
||||
"notes": [
|
||||
{
|
||||
"id": n.id,
|
||||
"user_id": n.user_id,
|
||||
"title": n.title,
|
||||
"body": n.body,
|
||||
"tags": n.tags or [],
|
||||
"parent_id": n.parent_id,
|
||||
"project_id": n.project_id,
|
||||
"milestone_id": n.milestone_id,
|
||||
"is_task": n.is_task,
|
||||
"status": n.status,
|
||||
"priority": n.priority,
|
||||
"due_date": n.due_date.isoformat() if n.due_date else None,
|
||||
"is_starred": getattr(n, "is_starred", False),
|
||||
"is_pinned": getattr(n, "is_pinned", False),
|
||||
"created_at": n.created_at.isoformat(),
|
||||
"updated_at": n.updated_at.isoformat(),
|
||||
}
|
||||
for n in notes
|
||||
],
|
||||
"task_logs": [
|
||||
{
|
||||
"id": tl.id,
|
||||
"user_id": tl.user_id,
|
||||
"note_id": tl.note_id,
|
||||
"description": tl.description,
|
||||
"duration_minutes": tl.duration_minutes,
|
||||
"logged_at": tl.logged_at.isoformat() if tl.logged_at else None,
|
||||
"created_at": tl.created_at.isoformat(),
|
||||
}
|
||||
for tl in task_logs
|
||||
],
|
||||
"note_drafts": [
|
||||
{
|
||||
"id": nd.id,
|
||||
"user_id": nd.user_id,
|
||||
"note_id": nd.note_id,
|
||||
"title": nd.title,
|
||||
"body": nd.body,
|
||||
"saved_at": nd.saved_at.isoformat() if nd.saved_at else None,
|
||||
}
|
||||
for nd in note_drafts
|
||||
],
|
||||
"note_versions": [
|
||||
{
|
||||
"id": nv.id,
|
||||
"user_id": nv.user_id,
|
||||
"note_id": nv.note_id,
|
||||
"title": nv.title,
|
||||
"body": nv.body,
|
||||
"version_number": nv.version_number,
|
||||
"created_at": nv.created_at.isoformat(),
|
||||
}
|
||||
for nv in note_versions
|
||||
],
|
||||
"conversations": [
|
||||
{
|
||||
"id": c.id,
|
||||
"user_id": c.user_id,
|
||||
"title": c.title,
|
||||
"created_at": c.created_at.isoformat(),
|
||||
"updated_at": c.updated_at.isoformat(),
|
||||
"messages": [
|
||||
{
|
||||
"id": m.id,
|
||||
"role": m.role,
|
||||
"content": m.content,
|
||||
"context_note_id": m.context_note_id,
|
||||
"created_at": m.created_at.isoformat(),
|
||||
}
|
||||
for m in c.messages
|
||||
],
|
||||
}
|
||||
for c in conversations
|
||||
],
|
||||
"settings": [
|
||||
{"user_id": s.user_id, "key": s.key, "value": s.value}
|
||||
for s in settings
|
||||
],
|
||||
"push_subscriptions": [
|
||||
{
|
||||
"user_id": ps.user_id,
|
||||
"endpoint": ps.endpoint,
|
||||
"p256dh": ps.p256dh,
|
||||
"auth": ps.auth,
|
||||
"created_at": ps.created_at.isoformat(),
|
||||
}
|
||||
for ps in push_subs
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
Check what exact field names exist on each model before assuming. Use `getattr(obj, "field", default)` for fields that may not exist on older DB versions.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add src/fabledassistant/services/backup.py
|
||||
git commit -m "feat(backup): v2 full export with projects, milestones, task_logs, drafts, versions"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Extend export — user backup
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/fabledassistant/services/backup.py`
|
||||
|
||||
- [ ] **Step 1: Rewrite `export_user_backup(user_id)`**
|
||||
|
||||
Same structure as full backup but filtered to `WHERE user_id = uid`. Apply same field additions. Omit sensitive fields (password_hash, oauth_sub) from user self-export.
|
||||
|
||||
```python
|
||||
async def export_user_backup(user_id: int) -> dict:
|
||||
async with async_session() as session:
|
||||
user = await session.get(User, user_id)
|
||||
projects = (await session.execute(select(Project).where(Project.user_id == user_id))).scalars().all()
|
||||
milestones = (await session.execute(select(Milestone).where(Milestone.user_id == user_id))).scalars().all()
|
||||
notes = (await session.execute(select(Note).where(Note.user_id == user_id))).scalars().all()
|
||||
task_logs = (await session.execute(select(TaskLog).where(TaskLog.user_id == user_id))).scalars().all()
|
||||
note_drafts = (await session.execute(select(NoteDraft).where(NoteDraft.user_id == user_id))).scalars().all()
|
||||
note_versions = (await session.execute(
|
||||
select(NoteVersion).where(NoteVersion.user_id == user_id)
|
||||
.order_by(NoteVersion.note_id, NoteVersion.version_number)
|
||||
)).scalars().all()
|
||||
conversations = (await session.execute(
|
||||
select(Conversation).options(selectinload(Conversation.messages))
|
||||
.where(Conversation.user_id == user_id)
|
||||
)).scalars().all()
|
||||
settings = (await session.execute(select(Setting).where(Setting.user_id == user_id))).scalars().all()
|
||||
|
||||
return {
|
||||
"version": 2,
|
||||
"scope": "user",
|
||||
"exported_at": datetime.now(timezone.utc).isoformat(),
|
||||
"user": {
|
||||
"id": user.id,
|
||||
"username": user.username,
|
||||
"email": user.email,
|
||||
"role": user.role,
|
||||
"created_at": user.created_at.isoformat(),
|
||||
} if user else None,
|
||||
"projects": [...], # same as full but user-filtered
|
||||
"milestones": [...],
|
||||
"notes": [...],
|
||||
"task_logs": [...],
|
||||
"note_drafts": [...],
|
||||
"note_versions": [...],
|
||||
"conversations": [...],
|
||||
"settings": [...],
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add src/fabledassistant/services/backup.py
|
||||
git commit -m "feat(backup): v2 user backup with all models"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Rewrite restore for v2
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/fabledassistant/services/backup.py`
|
||||
|
||||
- [ ] **Step 1: Add version dispatch to `restore_full_backup`**
|
||||
|
||||
```python
|
||||
async def restore_full_backup(data: dict) -> dict:
|
||||
version = data.get("version", 1)
|
||||
if version == 1:
|
||||
return await _restore_v1(data)
|
||||
return await _restore_v2(data)
|
||||
```
|
||||
|
||||
Move existing restore code into `_restore_v1(data)` with no changes.
|
||||
|
||||
- [ ] **Step 2: Implement `_restore_v2(data)` with full FK re-mapping**
|
||||
|
||||
Restore order (respects FK dependencies):
|
||||
1. Users → build `user_id_map`
|
||||
2. Projects (fk: user_id) → build `project_id_map`
|
||||
3. Milestones (fk: user_id, project_id) → build `milestone_id_map`
|
||||
4. Notes — first pass: insert without `parent_id` (fk: user_id, project_id, milestone_id) → build `note_id_map`
|
||||
5. Notes — second pass: patch `parent_id` using `note_id_map`
|
||||
6. TaskLogs (fk: user_id, note_id via note_id_map)
|
||||
7. NoteDrafts (fk: user_id, note_id via note_id_map)
|
||||
8. NoteVersions (fk: user_id, note_id via note_id_map) — export only, no restore by default (skip unless flag set)
|
||||
9. Conversations (fk: user_id) → Messages (fk: conversation_id, context_note_id via note_id_map)
|
||||
10. Settings (fk: user_id)
|
||||
|
||||
```python
|
||||
async def _restore_v2(data: dict) -> dict:
|
||||
from datetime import date, datetime, timezone
|
||||
|
||||
stats = {
|
||||
"users": 0, "projects": 0, "milestones": 0, "notes": 0,
|
||||
"task_logs": 0, "note_drafts": 0, "conversations": 0,
|
||||
"messages": 0, "settings": 0
|
||||
}
|
||||
|
||||
async with async_session() as session:
|
||||
user_id_map: dict[int, int] = {}
|
||||
project_id_map: dict[int, int] = {}
|
||||
milestone_id_map: dict[int, int] = {}
|
||||
note_id_map: dict[int, int] = {}
|
||||
|
||||
# 1. Users
|
||||
for u_data in data.get("users", []):
|
||||
old_id = u_data["id"]
|
||||
user = User(
|
||||
username=u_data["username"],
|
||||
email=u_data.get("email"),
|
||||
password_hash=u_data.get("password_hash"),
|
||||
oauth_sub=u_data.get("oauth_sub"),
|
||||
role=u_data.get("role", "user"),
|
||||
session_version=u_data.get("session_version", 1),
|
||||
created_at=datetime.fromisoformat(u_data["created_at"]) if u_data.get("created_at") else datetime.now(timezone.utc),
|
||||
)
|
||||
session.add(user)
|
||||
await session.flush()
|
||||
user_id_map[old_id] = user.id
|
||||
stats["users"] += 1
|
||||
|
||||
# 2. Projects
|
||||
for p_data in data.get("projects", []):
|
||||
mapped_uid = user_id_map.get(p_data.get("user_id", 0))
|
||||
if mapped_uid is None:
|
||||
continue
|
||||
proj = Project(
|
||||
user_id=mapped_uid,
|
||||
title=p_data.get("title", ""),
|
||||
description=p_data.get("description"),
|
||||
goal=p_data.get("goal"),
|
||||
status=p_data.get("status", "active"),
|
||||
color=p_data.get("color"),
|
||||
created_at=datetime.fromisoformat(p_data["created_at"]) if p_data.get("created_at") else datetime.now(timezone.utc),
|
||||
updated_at=datetime.fromisoformat(p_data["updated_at"]) if p_data.get("updated_at") else datetime.now(timezone.utc),
|
||||
)
|
||||
session.add(proj)
|
||||
await session.flush()
|
||||
project_id_map[p_data["id"]] = proj.id
|
||||
stats["projects"] += 1
|
||||
|
||||
# 3. Milestones
|
||||
for m_data in data.get("milestones", []):
|
||||
mapped_uid = user_id_map.get(m_data.get("user_id", 0))
|
||||
mapped_pid = project_id_map.get(m_data.get("project_id", 0))
|
||||
if mapped_uid is None:
|
||||
continue
|
||||
ms = Milestone(
|
||||
user_id=mapped_uid,
|
||||
project_id=mapped_pid,
|
||||
title=m_data.get("title", ""),
|
||||
description=m_data.get("description"),
|
||||
status=m_data.get("status", "open"),
|
||||
order_index=m_data.get("order_index", 0),
|
||||
created_at=datetime.fromisoformat(m_data["created_at"]) if m_data.get("created_at") else datetime.now(timezone.utc),
|
||||
updated_at=datetime.fromisoformat(m_data["updated_at"]) if m_data.get("updated_at") else datetime.now(timezone.utc),
|
||||
)
|
||||
session.add(ms)
|
||||
await session.flush()
|
||||
milestone_id_map[m_data["id"]] = ms.id
|
||||
stats["milestones"] += 1
|
||||
|
||||
# 4. Notes — first pass (no parent_id)
|
||||
note_objects: list[tuple[int, int]] = [] # (old_parent_id, new_note_id)
|
||||
for n_data in data.get("notes", []):
|
||||
mapped_uid = user_id_map.get(n_data.get("user_id", 0))
|
||||
if mapped_uid is None:
|
||||
continue
|
||||
due = None
|
||||
if n_data.get("due_date"):
|
||||
due = date.fromisoformat(n_data["due_date"])
|
||||
note = Note(
|
||||
user_id=mapped_uid,
|
||||
title=n_data.get("title", ""),
|
||||
body=n_data.get("body", ""),
|
||||
tags=n_data.get("tags", []),
|
||||
parent_id=None, # patched in second pass
|
||||
project_id=project_id_map.get(n_data.get("project_id")) if n_data.get("project_id") else None,
|
||||
milestone_id=milestone_id_map.get(n_data.get("milestone_id")) if n_data.get("milestone_id") else None,
|
||||
is_task=n_data.get("is_task", False),
|
||||
status=n_data.get("status"),
|
||||
priority=n_data.get("priority"),
|
||||
due_date=due,
|
||||
created_at=datetime.fromisoformat(n_data["created_at"]) if n_data.get("created_at") else datetime.now(timezone.utc),
|
||||
updated_at=datetime.fromisoformat(n_data["updated_at"]) if n_data.get("updated_at") else datetime.now(timezone.utc),
|
||||
)
|
||||
session.add(note)
|
||||
await session.flush()
|
||||
note_id_map[n_data["id"]] = note.id
|
||||
if n_data.get("parent_id"):
|
||||
note_objects.append((n_data["parent_id"], note.id))
|
||||
stats["notes"] += 1
|
||||
|
||||
# 5. Notes — second pass: patch parent_id
|
||||
for old_parent_id, new_note_id in note_objects:
|
||||
new_parent_id = note_id_map.get(old_parent_id)
|
||||
if new_parent_id:
|
||||
note_row = await session.get(Note, new_note_id)
|
||||
if note_row:
|
||||
note_row.parent_id = new_parent_id
|
||||
|
||||
# 6. TaskLogs
|
||||
for tl_data in data.get("task_logs", []):
|
||||
mapped_uid = user_id_map.get(tl_data.get("user_id", 0))
|
||||
mapped_nid = note_id_map.get(tl_data.get("note_id", 0))
|
||||
if mapped_uid is None or mapped_nid is None:
|
||||
continue
|
||||
from fabledassistant.models.task_log import TaskLog
|
||||
tl = TaskLog(
|
||||
user_id=mapped_uid,
|
||||
note_id=mapped_nid,
|
||||
description=tl_data.get("description", ""),
|
||||
duration_minutes=tl_data.get("duration_minutes"),
|
||||
logged_at=datetime.fromisoformat(tl_data["logged_at"]) if tl_data.get("logged_at") else None,
|
||||
created_at=datetime.fromisoformat(tl_data["created_at"]) if tl_data.get("created_at") else datetime.now(timezone.utc),
|
||||
)
|
||||
session.add(tl)
|
||||
stats["task_logs"] += 1
|
||||
|
||||
# 7. NoteDrafts
|
||||
for nd_data in data.get("note_drafts", []):
|
||||
mapped_uid = user_id_map.get(nd_data.get("user_id", 0))
|
||||
mapped_nid = note_id_map.get(nd_data.get("note_id", 0))
|
||||
if mapped_uid is None or mapped_nid is None:
|
||||
continue
|
||||
from fabledassistant.models.note_draft import NoteDraft
|
||||
nd = NoteDraft(
|
||||
user_id=mapped_uid,
|
||||
note_id=mapped_nid,
|
||||
title=nd_data.get("title", ""),
|
||||
body=nd_data.get("body", ""),
|
||||
saved_at=datetime.fromisoformat(nd_data["saved_at"]) if nd_data.get("saved_at") else None,
|
||||
)
|
||||
session.add(nd)
|
||||
stats["note_drafts"] += 1
|
||||
|
||||
# 8. Conversations + Messages
|
||||
for c_data in data.get("conversations", []):
|
||||
mapped_uid = user_id_map.get(c_data.get("user_id", 0))
|
||||
if mapped_uid is None:
|
||||
continue
|
||||
conv = Conversation(
|
||||
user_id=mapped_uid,
|
||||
title=c_data.get("title", ""),
|
||||
created_at=datetime.fromisoformat(c_data["created_at"]) if c_data.get("created_at") else datetime.now(timezone.utc),
|
||||
updated_at=datetime.fromisoformat(c_data["updated_at"]) if c_data.get("updated_at") else datetime.now(timezone.utc),
|
||||
)
|
||||
session.add(conv)
|
||||
await session.flush()
|
||||
stats["conversations"] += 1
|
||||
for m_data in c_data.get("messages", []):
|
||||
msg = Message(
|
||||
conversation_id=conv.id,
|
||||
role=m_data["role"],
|
||||
content=m_data.get("content", ""),
|
||||
context_note_id=note_id_map.get(m_data["context_note_id"]) if m_data.get("context_note_id") else None,
|
||||
created_at=datetime.fromisoformat(m_data["created_at"]) if m_data.get("created_at") else datetime.now(timezone.utc),
|
||||
)
|
||||
session.add(msg)
|
||||
stats["messages"] += 1
|
||||
|
||||
# 9. Settings
|
||||
for s_data in data.get("settings", []):
|
||||
mapped_uid = user_id_map.get(s_data.get("user_id", 0))
|
||||
if mapped_uid is None:
|
||||
continue
|
||||
setting = Setting(user_id=mapped_uid, key=s_data["key"], value=s_data.get("value", ""))
|
||||
session.add(setting)
|
||||
stats["settings"] += 1
|
||||
|
||||
await session.commit()
|
||||
|
||||
logger.info("Restored v2 backup: %s", stats)
|
||||
return stats
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Add missing imports at top of file**
|
||||
|
||||
```python
|
||||
from datetime import datetime, timezone
|
||||
from fabledassistant.models.project import Project
|
||||
from fabledassistant.models.milestone import Milestone
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Test restore round-trip**
|
||||
|
||||
```bash
|
||||
# Export
|
||||
curl -s -b cookies.txt "http://localhost:5000/api/admin/backup?scope=full" -o /tmp/backup_v2.json
|
||||
# Inspect structure
|
||||
python3 -c "import json; d=json.load(open('/tmp/backup_v2.json')); print(list(d.keys()))"
|
||||
# Expected keys: version, scope, exported_at, users, projects, milestones, notes, task_logs, ...
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Typecheck**
|
||||
|
||||
```bash
|
||||
docker compose exec app python -m py_compile src/fabledassistant/services/backup.py
|
||||
```
|
||||
Expected: No errors.
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/fabledassistant/services/backup.py
|
||||
git commit -m "feat(backup): v2 restore with full FK re-mapping; v1 restore preserved"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Verification
|
||||
|
||||
- [ ] **Step 1: Full round-trip test**
|
||||
|
||||
1. Export full backup as admin
|
||||
2. Verify JSON has `"version": 2` and all expected top-level keys
|
||||
3. Verify notes have `project_id`, `milestone_id`, `is_task` fields
|
||||
4. Verify `task_logs` array has entries (create a task log entry first if needed)
|
||||
5. Restore backup to a clean test instance (or verify restore code path runs without error in dry-run)
|
||||
|
||||
- [ ] **Step 2: V1 backward compat test**
|
||||
|
||||
Take an old v1 backup JSON (or construct one without the `version` key) and run restore. Verify it takes the v1 path and doesn't error.
|
||||
|
||||
- [ ] **Step 3: Commit final verification note**
|
||||
|
||||
```bash
|
||||
git commit --allow-empty -m "chore(backup): v2 backup rewrite verified"
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,285 +0,0 @@
|
||||
# Briefing Service Improvements — Design Spec
|
||||
|
||||
**Date:** 2026-03-25
|
||||
**Status:** Approved
|
||||
**Scope:** Web-first (no Android changes in this cycle)
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The daily briefing has several usability issues:
|
||||
|
||||
1. **Task repetition** — tasks are restated identically every day regardless of whether anything changed, making the briefing feel stale and hard to scan.
|
||||
2. **RSS repetition** — the same news stories resurface across days with no mechanism to learn what the user cares about.
|
||||
3. **No path to sources** — news items are summarised in prose with no link to the original article.
|
||||
4. **Stale weather** — if the weather cache is outdated, the briefing silently uses old data rather than failing gracefully. The current prose weather format is also hard to scan.
|
||||
5. **No feedback loop** — there is no way to teach the briefing what topics are interesting or uninteresting.
|
||||
|
||||
---
|
||||
|
||||
## Approach
|
||||
|
||||
**Pre-processing pipeline with explicit state tracking.** Rather than relying on the synthesis LLM to handle deduplication and filtering, we add deterministic pre-processing steps before synthesis runs. Each concern is isolated: task change detection, RSS topic classification and filtering, weather staleness gating. The synthesis LLM receives pre-filtered, structured input and focuses on tone and flow.
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### Migration: `0028_add_briefing_improvements`
|
||||
|
||||
**`rss_items` table — two new columns**
|
||||
|
||||
```sql
|
||||
ALTER TABLE rss_items ADD COLUMN IF NOT EXISTS topics TEXT[] DEFAULT '{}';
|
||||
ALTER TABLE rss_items ADD COLUMN IF NOT EXISTS classified_at TIMESTAMPTZ;
|
||||
```
|
||||
|
||||
`topics` stores LLM-assigned topic tags (e.g. `["technology", "ai"]`). `classified_at` is NULL until classification runs, allowing backfill queries. The `RssFeed` / `RssItem` SQLAlchemy model (`models/rss_feed.py`) must also be updated to add these two mapped columns and expose them in `to_dict()`.
|
||||
|
||||
**`messages` table — new metadata column**
|
||||
|
||||
```sql
|
||||
ALTER TABLE messages ADD COLUMN IF NOT EXISTS metadata JSONB;
|
||||
```
|
||||
|
||||
The briefing pipeline populates this when it creates the compiled message. The frontend reads it when loading the conversation to render the `WeatherCard` and attach reaction buttons. No SSE events are needed — structured data travels with the message record.
|
||||
|
||||
Schema stored in `metadata`:
|
||||
```json
|
||||
{
|
||||
"weather": {
|
||||
"location": "Berlin",
|
||||
"fetched_at": "2026-03-25T06:00:00Z",
|
||||
"current_temp": 12,
|
||||
"condition": "Partly Cloudy",
|
||||
"today_high": 16,
|
||||
"today_low": 8,
|
||||
"yesterday_high": 14,
|
||||
"yesterday_low": 9,
|
||||
"forecast": [
|
||||
{"day": "Wed", "condition": "Sunny", "high": 18, "low": 10},
|
||||
{"day": "Thu", "condition": "Cloudy", "high": 14, "low": 9}
|
||||
]
|
||||
},
|
||||
"rss_item_ids": [42, 17, 89, 103, 55]
|
||||
}
|
||||
```
|
||||
|
||||
If weather is unavailable, `metadata.weather` is `null` and the card renders a failure placeholder. The `Message` SQLAlchemy model (`models/conversation.py`) must be updated to add the `metadata` mapped column.
|
||||
|
||||
**New table: `rss_item_reactions`**
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS rss_item_reactions (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
rss_item_id INTEGER NOT NULL REFERENCES rss_items(id) ON DELETE CASCADE,
|
||||
reaction TEXT NOT NULL CHECK (reaction IN ('up', 'down')),
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
UNIQUE (user_id, rss_item_id)
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS ix_rss_item_reactions_user_id ON rss_item_reactions(user_id);
|
||||
```
|
||||
|
||||
One reaction per user per item. A second click on the same button removes the reaction; clicking the opposite button flips it.
|
||||
|
||||
**New table: `briefing_task_snapshot`**
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS briefing_task_snapshot (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
task_id INTEGER NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
|
||||
snapshot_hash TEXT NOT NULL,
|
||||
last_briefed TIMESTAMPTZ DEFAULT NOW(),
|
||||
UNIQUE (user_id, task_id)
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS ix_briefing_task_snapshot_user_id ON briefing_task_snapshot(user_id);
|
||||
```
|
||||
|
||||
`snapshot_hash` is `SHA-256(status + priority + due_date + title)`. The pipeline diffs current task state against these rows to detect what has changed since the last briefing.
|
||||
|
||||
**Settings keys (existing key-value store — no new table)**
|
||||
|
||||
- `briefing_include_topics` — JSON array of topic strings to prioritise
|
||||
- `briefing_exclude_topics` — JSON array of topics to hard-exclude from briefings
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Changes
|
||||
|
||||
### Pre-processing Stage (new, runs before parallel gather)
|
||||
|
||||
Three sequential steps added to `services/briefing_pipeline.py`. Note: `_gather_internal` currently serialises tasks as dicts without `id`. It must be updated to include `task_id` in each serialised task dict (the `Note` ORM object has `.id` available) so the post-briefing snapshot upsert has the required FK value.
|
||||
|
||||
**1. Task change detection**
|
||||
|
||||
For each of the user's current tasks, compute `SHA-256(status + priority + due_date + title)` and compare against `briefing_task_snapshot`. Split into:
|
||||
- `changed_tasks` — new hash or no snapshot row (included fully in briefing)
|
||||
- `unchanged_count` — integer count passed to the synthesis prompt as context
|
||||
|
||||
The synthesis prompt receives `changed_tasks` and the instruction: "N tasks are unchanged since the last briefing — acknowledge this briefly rather than listing them."
|
||||
|
||||
**2. RSS item filtering**
|
||||
|
||||
Load the user's `briefing_include_topics` and `briefing_exclude_topics` settings, plus reaction history (last 30 days, aggregated per topic as a net score). Score each recent classified item:
|
||||
- Hard-remove items tagged with any excluded topic
|
||||
- Boost items tagged with any included or positively-reacted topic
|
||||
- Penalise items from negatively-reacted topics
|
||||
- Sort by score, take top 10
|
||||
|
||||
Items with `classified_at IS NULL` pass through unfiltered (new feeds not yet classified) and are queued for background classification.
|
||||
|
||||
**3. Weather staleness gate**
|
||||
|
||||
Check `weather_cache.fetched_at`. If older than 24 hours: skip weather entirely, set `weather_unavailable = True`. The frontend renders a `WeatherCard` placeholder in the failure state. If fresh: pass the forecast JSON (including `past_days=1` data) to the pipeline for card rendering.
|
||||
|
||||
### RSS Classification (background, triggered at fetch time)
|
||||
|
||||
When `services/rss.py` stores new items, it queues a fire-and-forget async task to classify them. Classification is a fast, non-streaming LLM call processing batches of up to 10 items:
|
||||
|
||||
```
|
||||
Classify each news item into 1-3 topics from this vocabulary:
|
||||
technology, science, politics, business, health, environment,
|
||||
local, entertainment, sports, other, [user_defined_topics]
|
||||
Return JSON: {"item_id": ["topic1", "topic2"]}
|
||||
```
|
||||
|
||||
The vocabulary is extended with the user's declared preference topics so custom interests can be matched. Results are written to `rss_items.topics` and `classified_at`.
|
||||
|
||||
Model: the user's `default_model` setting (same as chat). If the LLM is unavailable or classification fails, the item is stored with `topics = []` and `classified_at` left NULL — it will be retried the next time new items are fetched. No retry loop; classification is best-effort.
|
||||
|
||||
### Post-briefing Stage (new, runs after `post_message()` returns)
|
||||
|
||||
1. **Upsert task snapshots** — upsert `briefing_task_snapshot` rows for all tasks included in this briefing so the next run can diff against current state.
|
||||
2. **Populate message metadata** — the `metadata` dict (`weather` + `rss_item_ids`) is assembled during pre-processing and passed through to `post_message()`, which writes it to the `Message.metadata` column. No separate post-step is needed — the metadata is stored atomically with the message.
|
||||
|
||||
---
|
||||
|
||||
## Weather Card
|
||||
|
||||
The weather section is no longer generated as prose by the synthesis LLM. Instead:
|
||||
|
||||
- `services/weather.py` is updated to request `past_days=1` from Open-Meteo, including yesterday's high/low in the same API response.
|
||||
- The pipeline parses the forecast into the `metadata.weather` schema (defined in the Data Model section) and stores it on the `Message` record when `post_message()` is called.
|
||||
- `BriefingView.vue` reads `message.metadata.weather` when loading the conversation and renders `WeatherCard.vue` above the message text if the field is present.
|
||||
- The synthesis LLM's weather section is suppressed entirely — the prompt instructs it to skip weather since it is handled by the card.
|
||||
|
||||
**`WeatherCard.vue` displays:**
|
||||
- Location name and "as of" timestamp
|
||||
- Current temperature and condition
|
||||
- Today's high / low
|
||||
- Yesterday's high / low with delta ("3° warmer than yesterday")
|
||||
- Compact 3–5 day forecast strip (day name, condition, high/low)
|
||||
|
||||
**Failure state:** If `metadata.weather` is `null`, the same card position renders a muted placeholder: "Weather data unavailable — will retry at next slot."
|
||||
|
||||
---
|
||||
|
||||
## News Cards
|
||||
|
||||
### Format
|
||||
|
||||
The synthesis LLM is instructed to format each included news item as:
|
||||
|
||||
```markdown
|
||||
**[Headline text](source_url)**
|
||||
*Outlet Name · Day Month*
|
||||
One or two sentence summary of the story.
|
||||
```
|
||||
|
||||
No prose wrapper between cards. The synthesis prompt must explicitly instruct the LLM to **present news items in the exact order provided** — `metadata.rss_item_ids` records this order and the frontend maps reaction buttons positionally. Reordering by the LLM would break the mapping.
|
||||
|
||||
The briefing message structure becomes:
|
||||
1. Greeting / task summary
|
||||
2. `WeatherCard` (rendered from `message.metadata.weather`, not prose)
|
||||
3. News cards (markdown blocks with links)
|
||||
4. Calendar / other sections
|
||||
|
||||
### Reaction Buttons
|
||||
|
||||
`BriefingView.vue` reads `message.metadata.rss_item_ids` when loading the conversation. The ordered list of IDs maps directly to the news cards in the rendered message (cards appear in synthesis output in the same order). A 👍 / 👎 pair is rendered below each card. Reaction buttons are only shown in the briefing view — not in message history exports.
|
||||
|
||||
Clicking a reaction:
|
||||
1. Optimistic UI update (button enters selected state immediately)
|
||||
2. `POST /api/briefing/rss-reactions` — `{rss_item_id, reaction}`
|
||||
3. Backend validates ownership: joins through `rss_items → rss_feeds` to confirm `rss_feeds.user_id = g.user.id` before upserting
|
||||
4. Upserts into `rss_item_reactions` — same reaction removes it, opposite flips it
|
||||
|
||||
**New endpoints in `routes/briefing.py`:**
|
||||
- `POST /api/briefing/rss-reactions` — upsert or remove reaction (ownership-checked)
|
||||
- `DELETE /api/briefing/rss-reactions/:item_id` — explicit removal (useful for MCP/external API consumers that cannot use the toggle behaviour of POST)
|
||||
|
||||
---
|
||||
|
||||
## Topic Preferences UI
|
||||
|
||||
**Settings → Briefing tab — new "News Preferences" subsection** (added below existing RSS feed management):
|
||||
|
||||
Two chip-input fields using the existing `TagInput.vue` component:
|
||||
- **Interested in** → `briefing_include_topics` setting
|
||||
- **Not interested in** → `briefing_exclude_topics` setting
|
||||
|
||||
A collapsed hint lists the standard topic vocabulary so users know valid terms. Custom terms are accepted — the RSS classifier will attempt to match them.
|
||||
|
||||
Saved via the existing `PUT /api/settings/:key` endpoint.
|
||||
|
||||
---
|
||||
|
||||
## MCP Tool Additions
|
||||
|
||||
New file: `fable-mcp/fable_mcp/tools/briefing.py`
|
||||
|
||||
Three tools registered in `server.py`:
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `add_rss_feed(url, title=None, category=None)` | Adds a feed to the user's RSS list. `title` is optional — the feed title is auto-populated from feed metadata after the first fetch, but an override can be passed. Returns the created feed object. |
|
||||
| `list_rss_feeds()` | Returns current feed list with id, title, url, category, last_fetched_at. |
|
||||
| `remove_rss_feed(feed_id)` | Removes a feed by ID. |
|
||||
|
||||
These call existing RSS endpoints in `routes/briefing.py` via `FableClient`. No new backend routes required.
|
||||
|
||||
---
|
||||
|
||||
## New Backend Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `services/briefing_preferences.py` | Load/compute topic preference weights; apply to RSS item scoring |
|
||||
| `services/rss_classifier.py` | Batch LLM classification of RSS items; background task management |
|
||||
|
||||
## Modified Backend Files
|
||||
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| `services/briefing_pipeline.py` | Add pre-processing and post-briefing stages; carry `task_id` through serialised task dicts; pass `metadata` dict to `post_message()` |
|
||||
| `services/rss.py` | Trigger background classification after storing new items |
|
||||
| `services/weather.py` | Add `past_days=1` to Open-Meteo request; expose parsed yesterday data |
|
||||
| `routes/briefing.py` | Add `POST/DELETE /api/briefing/rss-reactions` endpoints |
|
||||
| `models/rss_feed.py` | Add `topics` and `classified_at` mapped columns to `RssItem`; expose in `to_dict()` |
|
||||
| `models/conversation.py` | Add `metadata` JSONB mapped column to `Message`; update `to_dict()` to include `metadata` in the returned dict |
|
||||
| `services/briefing_conversations.py` | Extend `post_message(conversation_id, role, content)` signature to accept an optional `metadata: dict \| None = None` parameter; pass it to the `Message(...)` constructor |
|
||||
|
||||
## New Frontend Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `components/WeatherCard.vue` | Weather display card (current, today, yesterday delta, 3-5 day strip, failure state) |
|
||||
|
||||
## Modified Frontend Files
|
||||
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| `views/BriefingView.vue` | Read `message.metadata.weather` on conversation load → render `WeatherCard.vue` above message text; read `message.metadata.rss_item_ids` → attach reaction buttons to news cards in order |
|
||||
| `views/SettingsView.vue` | Add "News Preferences" subsection with two `TagInput` fields |
|
||||
| `api/client.ts` | Add `postRssReaction()`, `deleteRssReaction()` helpers |
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Android companion app changes (web-first; parity deferred)
|
||||
- Full numeric scoring system (Approach C) — can evolve to this once reaction data accumulates
|
||||
- Push notification integration for briefing reactions
|
||||
@@ -1,214 +0,0 @@
|
||||
# Internal Calendar with CalDAV Sync — Design Spec
|
||||
|
||||
## Goal
|
||||
|
||||
Add an internal event store to Fable's database, a full calendar UI (month/week grid), and a best-effort push sync to the user's existing external CalDAV server. Fable becomes the source of truth for events; CalDAV is an optional downstream target.
|
||||
|
||||
## Background
|
||||
|
||||
The existing `services/caldav.py` lets the AI assistant create, update, and delete events directly on an external CalDAV server (Nextcloud, etc.) via tool calls. There is no calendar UI and no internal event storage — all reads go to CalDAV at query time. The `events` DB table and `models/event.py` exist as dead code from an abandoned Radicale integration (created in migration `0019_add_events`); the table exists in the database but all columns are empty.
|
||||
|
||||
This design revives the internal event store, adds a REST API and calendar view, and re-wires the AI tools to write through the internal DB so all events are accessible regardless of CalDAV availability.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Source of Truth
|
||||
|
||||
Fable's `events` DB table is the single source of truth. CalDAV sync is a best-effort push: after every create, update, or delete, a background task attempts to mirror the change to the user's configured CalDAV server. If CalDAV is unconfigured or unreachable, the operation still succeeds and the event remains in Fable.
|
||||
|
||||
### Timezone Handling
|
||||
|
||||
- **Storage:** `start_dt` / `end_dt` stored as UTC (`TIMESTAMPTZ`).
|
||||
- **Display:** FullCalendar configured with `timeZone: 'local'` — renders in the browser's IANA timezone automatically.
|
||||
- **Input:** Frontend datetime inputs are in local time; converted to a timezone-aware ISO string (with UTC offset) before the API call. Backend parses to UTC.
|
||||
- **CalDAV push:** Uses the user's `caldav_timezone` setting for iCal `DTSTART`/`DTEND`, consistent with existing behaviour.
|
||||
- **AI tools:** The LLM receives the user's timezone in the system prompt and sends timezone-aware strings, as today.
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### `events` table (existing since migration 0019, extend via migration 0029)
|
||||
|
||||
| Column | Type | Notes |
|
||||
|--------|------|-------|
|
||||
| `id` | `SERIAL PK` | |
|
||||
| `user_id` | `INT FK users CASCADE` | |
|
||||
| `project_id` | `INT FK projects SET NULL` nullable | Optional link to a Fable project |
|
||||
| `uid` | `TEXT` | iCal UID — UUID generated on `create_event`, embedded in CalDAV push |
|
||||
| `caldav_uid` | `TEXT DEFAULT ''` | **New.** Same value as `uid` after a successful CalDAV push (confirms sync); empty if never synced |
|
||||
| `title` | `TEXT` | |
|
||||
| `start_dt` | `TIMESTAMPTZ` | UTC |
|
||||
| `end_dt` | `TIMESTAMPTZ` nullable | UTC; null for open-ended events |
|
||||
| `all_day` | `BOOLEAN DEFAULT false` | When true, time component is ignored in display |
|
||||
| `description` | `TEXT DEFAULT ''` | |
|
||||
| `location` | `TEXT DEFAULT ''` | |
|
||||
| `color` | `TEXT DEFAULT ''` | **New.** Hex colour for calendar display (e.g. `#6366f1`) |
|
||||
| `recurrence` | `TEXT` nullable | iCal RRULE string — stored and forwarded to CalDAV; not exposed in the UI slide-over |
|
||||
| `created_at` | `TIMESTAMPTZ` | |
|
||||
| `updated_at` | `TIMESTAMPTZ` | |
|
||||
|
||||
**Migration `0029_add_calendar_columns`:** `ALTER TABLE events ADD COLUMN IF NOT EXISTS caldav_uid TEXT DEFAULT ''` and `ADD COLUMN IF NOT EXISTS color TEXT DEFAULT ''`. Raw SQL with `IF NOT EXISTS` guards (table already exists from migration 0019).
|
||||
|
||||
**`models/event.py`:** Add two `mapped_column` declarations to the `Event` class:
|
||||
```python
|
||||
caldav_uid: Mapped[str] = mapped_column(Text, default="")
|
||||
color: Mapped[str] = mapped_column(Text, default="")
|
||||
```
|
||||
Update `to_dict()` to include `"caldav_uid": self.caldav_uid` and `"color": self.color`.
|
||||
|
||||
---
|
||||
|
||||
## Service Layer
|
||||
|
||||
**`src/fabledassistant/services/events.py`** — owns all event CRUD and CalDAV push coordination.
|
||||
|
||||
### Public functions
|
||||
|
||||
```
|
||||
create_event(user_id, title, start_dt, end_dt, all_day, description, location,
|
||||
color, recurrence, project_id,
|
||||
duration, reminder_minutes, attendees, calendar_name) → Event
|
||||
get_event(user_id, event_id) → Event
|
||||
list_events(user_id, date_from, date_to) → list[Event]
|
||||
search_events(user_id, query, days_ahead=90) → list[Event]
|
||||
update_event(user_id, event_id, **fields) → Event
|
||||
delete_event(user_id, event_id) → None
|
||||
find_events_by_query(user_id, query) → list[Event]
|
||||
```
|
||||
|
||||
`duration`, `reminder_minutes`, `attendees`, and `calendar_name` are accepted by `create_event` for forwarding to CalDAV (they are not stored in the DB). `find_events_by_query` does a case-insensitive `ILIKE` search on `title` and is used by the AI `update_event` / `delete_event` tools.
|
||||
|
||||
### CalDAV push — UID strategy
|
||||
|
||||
`create_event` generates a UUID and stores it as the event's `uid`. This same UUID must be embedded as the iCal `UID` field when pushing to CalDAV. To enable this, `services/caldav.py`'s `create_event` function is **minimally modified** to accept an optional `uid: str | None = None` parameter; when provided, `event.add("uid", uid)` is called before `cal.add_component(event)`. All other CalDAV functions are unchanged.
|
||||
|
||||
On a successful push, `caldav_uid` is set to the same UUID value in the DB (confirming sync). This means `caldav_uid` is Fable's own UID confirmed-as-pushed, not a server-assigned value — which is fine since we generated it.
|
||||
|
||||
After every write to the DB:
|
||||
|
||||
- `create_event` → `asyncio.create_task(_push_create(event, user_id, extra_fields))`
|
||||
- `update_event` → `asyncio.create_task(_push_update(event, user_id))`
|
||||
- `delete_event` → `asyncio.create_task(_push_delete(caldav_uid, user_id))` if `caldav_uid` is set
|
||||
|
||||
Each push function calls the relevant function in `services/caldav.py`, marks `caldav_uid` on success, and logs a warning on failure. CalDAV being unconfigured is treated as a no-op (not an error).
|
||||
|
||||
### Match policy for AI update/delete tools
|
||||
|
||||
`find_events_by_query` returns all events where `title ILIKE '%query%'`. The calling tool applies the same match-count policy as the existing CalDAV tools: zero matches → raise `ValueError("No event found matching '…'.")`; more than 3 matches → raise `ValueError("Too many matches (N) for '…'. Be more specific. Found: …")`. One or two matches use the first result.
|
||||
|
||||
---
|
||||
|
||||
## REST API
|
||||
|
||||
**`src/fabledassistant/routes/events.py`** — new blueprint, registered in `app.py`.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/api/events?from=&to=` | List events in ISO datetime range |
|
||||
| `POST` | `/api/events` | Create event |
|
||||
| `GET` | `/api/events/:id` | Get single event |
|
||||
| `PATCH` | `/api/events/:id` | Partial update |
|
||||
| `DELETE` | `/api/events/:id` | Delete event |
|
||||
|
||||
All routes require `@login_required`. Ownership enforced in the service layer (404 if event not owned by requesting user).
|
||||
|
||||
---
|
||||
|
||||
## AI Tool Rewiring
|
||||
|
||||
Calendar tools in `services/tools.py` are updated to call `services/events.py` instead of `services/caldav.py` directly. The `is_caldav_configured` gate that currently hides these tools is **removed** — calendar tools are always available since the internal DB is always present. The tool definitions currently grouped under `_CALDAV_TOOLS` (appended to the tools list only when `is_caldav_configured` is true) must be moved into the unconditional `_CORE_TOOLS` list (or equivalent always-included list). The tool parameter names and LLM-facing descriptions do not change.
|
||||
|
||||
| Tool | Change |
|
||||
|------|--------|
|
||||
| `create_event` | Calls `events.create_event(...)` — all existing params forwarded |
|
||||
| `list_events` | Calls `events.list_events(...)` |
|
||||
| `search_events` | Calls `events.search_events(...)` |
|
||||
| `update_event` | Calls `events.find_events_by_query(...)`, then `events.update_event(...)` |
|
||||
| `delete_event` | Calls `events.find_events_by_query(...)`, then `events.delete_event(...)` |
|
||||
|
||||
---
|
||||
|
||||
## Frontend
|
||||
|
||||
### Dependencies
|
||||
|
||||
```
|
||||
@fullcalendar/vue3
|
||||
@fullcalendar/daygrid # month view
|
||||
@fullcalendar/timegrid # week / day view
|
||||
@fullcalendar/interaction # drag-to-move, resize, click-to-create
|
||||
```
|
||||
|
||||
All MIT licensed.
|
||||
|
||||
### Components
|
||||
|
||||
**`frontend/src/views/CalendarView.vue`** — main view at `/calendar`:
|
||||
- FullCalendar instance with `timeZone: 'local'`, `initialView: 'dayGridMonth'`, header toolbar toggling between month and week
|
||||
- Loads events for the visible date range via `GET /api/events?from=&to=`
|
||||
- Re-fetches when the visible range changes
|
||||
- Click on empty date cell → opens `EventSlideOver` in create mode, pre-filled with the clicked date
|
||||
- Click on existing event → opens `EventSlideOver` in edit mode
|
||||
- Drag event to new date/time → `PATCH /api/events/:id` with updated times (optimistic update, revert on error)
|
||||
- Resize event → same
|
||||
|
||||
**`frontend/src/components/EventSlideOver.vue`** — reusable slide-over panel (same pattern as the workspace task slide-over):
|
||||
- Fields: title (required), start date/time, end date/time, all-day toggle, location, description, colour picker, optional project selector
|
||||
- `recurrence` is **not** a form field — it is stored and pushed to CalDAV via AI tools only
|
||||
- Create mode: `POST /api/events`
|
||||
- Edit mode: `PATCH /api/events/:id` + delete button (`DELETE /api/events/:id`)
|
||||
- Closes on save, cancel, or Escape
|
||||
|
||||
**`frontend/src/api/client.ts`** — add typed helpers and `EventEntry` / `CreateEventBody` interfaces:
|
||||
|
||||
```typescript
|
||||
interface EventEntry {
|
||||
id: number; uid: string; title: string;
|
||||
start_dt: string; end_dt: string | null;
|
||||
all_day: boolean; description: string; location: string;
|
||||
color: string; recurrence: string | null;
|
||||
project_id: number | null; caldav_uid: string;
|
||||
created_at: string; updated_at: string;
|
||||
}
|
||||
|
||||
listEvents(from: string, to: string): Promise<EventEntry[]>
|
||||
createEvent(body: CreateEventBody): Promise<EventEntry>
|
||||
getEvent(id: number): Promise<EventEntry>
|
||||
updateEvent(id: number, body: Partial<CreateEventBody>): Promise<EventEntry>
|
||||
deleteEvent(id: number): Promise<void>
|
||||
```
|
||||
|
||||
### Navigation
|
||||
|
||||
- `/calendar` added to Vue Router
|
||||
- Sidebar nav item added
|
||||
- Keyboard shortcut: `g` + `l` (ca**l**endar) — `c` is already taken by chat
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
- CalDAV push failures are logged at `WARNING` level and do not surface to the user
|
||||
- If CalDAV is unconfigured, push is skipped silently
|
||||
- Drag-to-move/resize failures (PATCH error) revert the event to its previous position in FullCalendar's UI via the `revert` callback
|
||||
- 404 returned for event access by non-owner
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
- `tests/test_events_service.py` — unit tests for `create_event`, `list_events`, `search_events`, `update_event`, `delete_event`, `find_events_by_query` with mocked DB session; separate test verifying CalDAV push background task is fired
|
||||
- `tests/test_events_routes.py` — route tests for all five endpoints verifying ownership enforcement and correct status codes
|
||||
- TypeScript check (`make typecheck`) after all frontend changes
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Pull sync (importing events from CalDAV into Fable) — possible future upgrade
|
||||
- Recurring event expansion in the UI (RRULE stored and forwarded to CalDAV via AI tools only)
|
||||
- Shared calendars / multi-user event invites
|
||||
- Event notifications / reminders in the Fable push system
|
||||
@@ -1,236 +0,0 @@
|
||||
# RAG Scoping and Context Isolation Design
|
||||
|
||||
> **For agentic workers:** Use superpowers:executing-plans or superpowers:subagent-driven-development to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Prevent project-associated notes from polluting global chat RAG, and give the LLM tools to discover and switch project scope during a conversation.
|
||||
|
||||
**Problem being solved:** Users with multiple projects (e.g. scifi worldbuilding, personal productivity) find that semantic search pulls notes from whichever project has the most content, contaminating general-purpose chat context. Project notes should be siloed by default.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Default RAG behavior change
|
||||
|
||||
Currently `rag_project_id=None` in `build_context()` searches all notes. After this change the semantics become a three-value system:
|
||||
|
||||
- `rag_project_id = None` → search only orphan notes (`project_id IS NULL`)
|
||||
- `rag_project_id = <positive int>` → search only that project's notes
|
||||
- `rag_project_id = -1` → search all notes (explicit opt-in to current global behavior)
|
||||
|
||||
**`semantic_search_notes()` change** (`services/embeddings.py`): add `orphan_only: bool = False` parameter. When `True`, add `.where(Note.project_id.is_(None))` to the SQLAlchemy query.
|
||||
|
||||
**`search_notes_for_context()` change** (`services/notes.py`): add `orphan_only: bool = False` parameter with the same filter.
|
||||
|
||||
**`build_context()` change** (`services/llm.py`): compute the flags before calling search:
|
||||
|
||||
```python
|
||||
# rag_project_id=None → orphan only; -1 → all notes; positive int → that project
|
||||
orphan_only = rag_project_id is None
|
||||
effective_project_id = rag_project_id if (rag_project_id is not None and rag_project_id != -1) else None
|
||||
|
||||
for score, note in await semantic_search_notes(
|
||||
user_id, user_message, exclude_ids=search_exclude or None, limit=8,
|
||||
project_id=effective_project_id,
|
||||
orphan_only=orphan_only,
|
||||
):
|
||||
...
|
||||
```
|
||||
|
||||
The same `orphan_only` / `effective_project_id` pattern applies to the keyword fallback call to `search_notes_for_context()`.
|
||||
|
||||
### Conversation scope persistence
|
||||
|
||||
**New DB column:** `conversations.rag_project_id INTEGER` (nullable, default `NULL`).
|
||||
|
||||
Semantics match the three-value system above. `NULL` is the default for all new and existing conversations after migration — existing conversations transparently gain orphan-only scoping.
|
||||
|
||||
**Model change** (`models/conversation.py`):
|
||||
```python
|
||||
rag_project_id: Mapped[int | None] = mapped_column(Integer, nullable=True, default=None)
|
||||
```
|
||||
|
||||
`to_dict()` must include `"rag_project_id": self.rag_project_id`.
|
||||
|
||||
**Route change** (`routes/chat.py`): `PATCH /api/chat/conversations/:id` must accept `rag_project_id` in the request body and call `update_conversation(conv_id, user_id, rag_project_id=value)`. `GET /api/chat/conversations/:id` returns `rag_project_id` via `to_dict()`.
|
||||
|
||||
**Service change** (`services/chat.py`): `update_conversation()` must accept and persist `rag_project_id`.
|
||||
|
||||
### Project summarization background job
|
||||
|
||||
**New DB columns** on `projects`:
|
||||
```python
|
||||
auto_summary: Mapped[str | None] = mapped_column(Text, nullable=True)
|
||||
summary_updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||
```
|
||||
|
||||
**`generate_project_summary(user_id: int, project_id: int) -> None`** (`services/projects.py`):
|
||||
- Fetches project metadata (title, description, goal)
|
||||
- Fetches up to 10 notes for that project: `SELECT title, body[:200] FROM notes WHERE project_id=? ORDER BY updated_at DESC LIMIT 10`
|
||||
- Builds an Ollama prompt: "Summarize this project in 3-4 sentences covering its purpose, themes, and content. Title: {title}. Description: {description}. Goal: {goal}. Recent notes: {sample}"
|
||||
- Calls Ollama (same `generate_completion()` helper used elsewhere, `stream=False`)
|
||||
- Stores result in `project.auto_summary` and `project.summary_updated_at = datetime.now(UTC)`
|
||||
- On Ollama failure: log debug message, return without updating (graceful degradation)
|
||||
|
||||
**`backfill_project_summaries() -> None`** (`services/projects.py`): fire-and-forget, called at startup alongside `backfill_note_embeddings()`. Generates summaries for all projects where `auto_summary IS NULL`.
|
||||
|
||||
**Trigger from `update_project()`**: after committing, call `asyncio.create_task(generate_project_summary(user_id, project_id))` unconditionally.
|
||||
|
||||
**Trigger from note saves**: in `create_note()` and `update_note()` within `services/notes.py`, when `project_id` is not None, check `project.summary_updated_at`. If `None` or more than 1 hour old, fire `asyncio.create_task(generate_project_summary(user_id, project_id))`. This avoids flooding Ollama during heavy note-editing sessions.
|
||||
|
||||
`generate_project_summary` and `backfill_project_summaries` are **internal background tasks only**, not exposed as LLM tools.
|
||||
|
||||
### New LLM tools
|
||||
|
||||
Both tools are added to `_CORE_TOOLS` in `services/tools.py`.
|
||||
|
||||
**`search_projects(query: str)`**:
|
||||
- Loads all projects for the user from the DB (title, description, goal, auto_summary)
|
||||
- Scores each project: `SequenceMatcher(None, query.lower(), combined_text.lower()).ratio()` where `combined_text = f"{title} {description or ''} {auto_summary or ''}"`, plus keyword overlap bonus
|
||||
- Returns top 5 as `[{id, title, summary_snippet, score}]` where `summary_snippet` is `auto_summary[:200]` or `description[:200]`
|
||||
- Tool result type: `"projects_list"`
|
||||
|
||||
**`set_rag_scope(project_id: int | None)`**:
|
||||
- `project_id = <positive int>` → scope to that project
|
||||
- `project_id = null` → orphan-only
|
||||
- `project_id = -1` → all notes
|
||||
- **Workspace guard:** if `workspace_project_id` is set on the current generation context, return `{success: false, error: "Cannot change RAG scope in workspace view"}` and make no changes
|
||||
- Validates positive project_id exists and belongs to user (returns error if not)
|
||||
- Calls `await update_conversation(conv_id, user_id, rag_project_id=project_id)` to persist immediately
|
||||
- Returns `{success: true, type: "rag_scope_set", scope_label: "<human-readable>"}` e.g. `"Orphan notes only"`, `"SciFi Project"`, `"All notes"`
|
||||
|
||||
**`conv_id` threading** (`services/tools.py`, `services/generation_task.py`):
|
||||
|
||||
Current `execute_tool()` signature:
|
||||
```python
|
||||
async def execute_tool(user_id: int, tool_name: str, arguments: dict) -> dict
|
||||
```
|
||||
|
||||
Updated signature:
|
||||
```python
|
||||
async def execute_tool(
|
||||
user_id: int,
|
||||
tool_name: str,
|
||||
arguments: dict,
|
||||
conv_id: int | None = None,
|
||||
workspace_project_id: int | None = None,
|
||||
) -> dict
|
||||
```
|
||||
|
||||
In `generation_task.py`, the call site in the tool execution loop must pass `conv_id=conv_id, workspace_project_id=workspace_project_id` — both are already available as local variables in `run_generation()`.
|
||||
|
||||
**SSE `new_rag_scope` wiring:**
|
||||
|
||||
In `generation_task.py`, after each tool call returns, check `if result.get("type") == "rag_scope_set" and result.get("success")`. Store `new_rag_scope = arguments["project_id"]` and `new_rag_scope_label = result["scope_label"]`.
|
||||
|
||||
When emitting the final SSE `done` event (currently `{"done": True, "message_id": msg_id, "timing": timing}`), add the scope fields when present:
|
||||
|
||||
```python
|
||||
done_payload = {"done": True, "message_id": msg_id, "timing": timing}
|
||||
if new_rag_scope_label is not None:
|
||||
done_payload["new_rag_scope"] = new_rag_scope # raw int or None
|
||||
done_payload["new_rag_scope_label"] = new_rag_scope_label
|
||||
yield f"data: {json.dumps(done_payload)}\n\n"
|
||||
```
|
||||
|
||||
In `stores/chat.ts`, the SSE `done` handler must check `event.data.new_rag_scope !== undefined` and set `currentConversation.value.rag_project_id = event.data.new_rag_scope`.
|
||||
|
||||
### Frontend scope indicator
|
||||
|
||||
**Chat store** (`stores/chat.ts`):
|
||||
- `currentConversation` already holds the full conversation object; add `rag_project_id: number | null` to the conversation interface
|
||||
- Add a computed `ragProjectId` that reads `currentConversation.value?.rag_project_id ?? null`
|
||||
- Add `async updateRagScope(convId: number, ragProjectId: number | null)` that calls `PATCH /api/chat/conversations/:id { rag_project_id }` and updates `currentConversation.value.rag_project_id` locally on success
|
||||
- In the SSE `done` handler, if `event.data.new_rag_scope !== undefined`, set `currentConversation.value.rag_project_id = event.data.new_rag_scope`
|
||||
|
||||
**ChatView** (`views/ChatView.vue`):
|
||||
- Remove the existing `ProjectSelector` from the sidebar RAG scope section
|
||||
- Add a scope chip just above the message input. Shows: `⊙ Orphan notes` (null) / `⊙ All notes` (-1) / `⊙ {project title}` (positive int)
|
||||
- Clicking opens a compact dropdown: "Orphan notes only", all active projects by title, "All notes"
|
||||
- On selection, call `chatStore.updateRagScope(convId, selectedValue)`
|
||||
- When `chatStore.ragProjectId` changes (from SSE or UI), briefly apply a CSS pulse animation to the chip
|
||||
- Load the projects list once on mount via `apiGet("/api/projects?status=active")`
|
||||
|
||||
**WorkspaceView** — no change. It hardcodes `ragProjectId` to the workspace project's id (positive int). Scope chip is not shown in workspace view.
|
||||
|
||||
---
|
||||
|
||||
## Files Changed
|
||||
|
||||
### Backend
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `alembic/versions/0030_rag_scoping.py` | Add `conversations.rag_project_id`, `projects.auto_summary`, `projects.summary_updated_at` |
|
||||
| `models/conversation.py` | Add `rag_project_id: Mapped[int \| None]`; include in `to_dict()` |
|
||||
| `models/project.py` | Add `auto_summary: Mapped[str \| None]`, `summary_updated_at: Mapped[datetime \| None]` |
|
||||
| `services/projects.py` | Add `generate_project_summary()`, `backfill_project_summaries()`; trigger from `update_project()` |
|
||||
| `services/notes.py` | Add `orphan_only` param to `search_notes_for_context()`; trigger summary regen from note saves |
|
||||
| `services/embeddings.py` | Add `orphan_only: bool = False` param to `semantic_search_notes()` |
|
||||
| `services/llm.py` | Compute `orphan_only` + `effective_project_id` from `rag_project_id`; pass to both search calls |
|
||||
| `services/tools.py` | Add `search_projects` and `set_rag_scope` definitions and handlers; update `execute_tool()` signature |
|
||||
| `services/generation_task.py` | Pass `conv_id` + `workspace_project_id` to `execute_tool()`; capture scope change; emit in SSE done |
|
||||
| `services/chat.py` | Add `rag_project_id` parameter to `update_conversation()` |
|
||||
| `routes/chat.py` | Accept `rag_project_id` in PATCH body; return in GET responses via `to_dict()` |
|
||||
| `app.py` | Call `backfill_project_summaries()` at startup |
|
||||
|
||||
### Frontend
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `api/client.ts` | Conversation type includes `rag_project_id`; helpers accept it |
|
||||
| `stores/chat.ts` | `ragProjectId` computed; `updateRagScope()` method; SSE done handler updates scope |
|
||||
| `views/ChatView.vue` | Replace sidebar `ProjectSelector` with scope chip above input bar |
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
User changes scope via chip
|
||||
→ chatStore.updateRagScope(convId, value)
|
||||
→ PATCH /api/chat/conversations/:id { rag_project_id: value }
|
||||
→ DB updated; currentConversation.rag_project_id updated locally
|
||||
→ chip re-renders immediately
|
||||
|
||||
User sends message
|
||||
→ sendMessage() reads chatStore.ragProjectId → passes as rag_project_id in POST body
|
||||
→ build_context() derives orphan_only + effective_project_id
|
||||
→ RAG results scoped accordingly
|
||||
|
||||
Model calls set_rag_scope(3) during generation
|
||||
→ execute_tool(conv_id=X, workspace_project_id=None) writes rag_project_id=3 to DB
|
||||
→ returns { success: true, type: "rag_scope_set", scope_label: "SciFi Project" }
|
||||
→ generation_task stores new_rag_scope=3, new_rag_scope_label="SciFi Project"
|
||||
→ SSE done event: { done: true, new_rag_scope: 3, new_rag_scope_label: "SciFi Project", ... }
|
||||
→ chat store done handler: currentConversation.rag_project_id = 3
|
||||
→ chip pulses → "⊙ SciFi Project"
|
||||
|
||||
User opens existing conversation
|
||||
→ GET /api/chat/conversations/:id returns rag_project_id
|
||||
→ chat store sets currentConversation; ragProjectId computed picks it up
|
||||
→ chip renders correct scope immediately
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Ollama unavailable during summary gen:** log debug, return without updating; old summary (or null) retained; `search_projects` falls back to title + description matching
|
||||
- **`set_rag_scope` called in workspace:** return `{success: false, error: "Cannot change RAG scope in workspace view"}`; no DB write
|
||||
- **`set_rag_scope` with unknown positive project_id:** return `{success: false, error: "Project not found"}`; scope unchanged
|
||||
- **`search_projects` with no summaries yet:** score on title + description only; still returns results
|
||||
- **Existing conversations after migration:** `rag_project_id` defaults to `NULL` → orphan-only; behavior silently improves without user action
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
- Unit: `semantic_search_notes(orphan_only=True)` returns only notes where `project_id IS NULL`
|
||||
- Unit: `semantic_search_notes(project_id=3, orphan_only=False)` returns only notes for project 3
|
||||
- Unit: `build_context()` passes correct `orphan_only` / `effective_project_id` for all three `rag_project_id` values (None, -1, positive)
|
||||
- Unit: `search_projects()` scoring ranks correct project first for representative queries; degrades gracefully with no summaries
|
||||
- Unit: `generate_project_summary()` builds correct Ollama prompt; handles Ollama failure gracefully
|
||||
- Integration: `set_rag_scope()` handler writes to DB, returns correct scope_label, rejects in workspace context
|
||||
- Integration: SSE `done` event includes `new_rag_scope` when scope changes mid-conversation
|
||||
- Frontend: scope chip reflects loaded conversation scope; updates reactively on model tool call
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,398 +0,0 @@
|
||||
# News Feed & Briefing View Redesign
|
||||
|
||||
> **For agentic workers:** Use superpowers:executing-plans or superpowers:subagent-driven-development to implement this spec task-by-task.
|
||||
|
||||
**Goal:** Extend RSS article retention to 90 days, introduce a unified news API, redesign the briefing view into a 3-column layout (weather · chat · news), add deep article Q&A in briefing chat, and add a `/news` archive view.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Data layer
|
||||
`rss_items` and `rss_item_reactions` already exist and contain everything needed. No new tables or migrations required. The only DB change is extending the prune window from 14 to 90 days.
|
||||
|
||||
### Unified news API
|
||||
A single `GET /api/briefing/news` endpoint serves both the briefing side panel (short window, no pagination) and the news archive view (full history, paginated). Both consumers share the same response shape and reaction logic.
|
||||
|
||||
### Briefing view
|
||||
`BriefingView.vue` restructures from a single-column `max-width: 760px` layout to a full-width CSS grid with three independently scrolling columns. Weather and news are fetched directly — no longer read from message metadata.
|
||||
|
||||
### News archive view
|
||||
A new `NewsView.vue` at `/news`, added to the sidebar nav, uses the same `/api/briefing/news` endpoint with `days=90` and offset-based pagination.
|
||||
|
||||
### Deep article Q&A
|
||||
`build_context()` in `llm.py` detects briefing conversations and injects the source article content from today's briefing into the system prompt, giving follow-up chat messages access to the full article text.
|
||||
|
||||
---
|
||||
|
||||
## Section 1 — Data & API layer
|
||||
|
||||
### 1a. Article retention (90 days)
|
||||
|
||||
**File:** `src/fabledassistant/services/rss.py`
|
||||
|
||||
Change the module-level constant:
|
||||
```python
|
||||
ITEM_MAX_AGE_DAYS = 90
|
||||
```
|
||||
|
||||
Update the SQL in `_prune_old_items`:
|
||||
```python
|
||||
AND published_at < NOW() - INTERVAL '90 days'
|
||||
```
|
||||
|
||||
### 1b. Unified news endpoint
|
||||
|
||||
**File:** `src/fabledassistant/routes/briefing.py`
|
||||
|
||||
Add `GET /api/briefing/news` endpoint (registered on `briefing_bp` which has prefix `/api/briefing`):
|
||||
|
||||
```python
|
||||
@briefing_bp.route("/news", methods=["GET"])
|
||||
@_REQUIRE
|
||||
async def list_news():
|
||||
days = min(int(request.args.get("days", 2)), 90)
|
||||
limit = min(int(request.args.get("limit", 40)), 100)
|
||||
offset = max(int(request.args.get("offset", 0)), 0)
|
||||
feed_id = request.args.get("feed_id", type=int)
|
||||
|
||||
from sqlalchemy import text as _text
|
||||
async with async_session() as session:
|
||||
result = await session.execute(
|
||||
_text("""
|
||||
SELECT
|
||||
i.id, i.title, i.url, i.content, i.published_at,
|
||||
i.topics, f.title AS feed_title,
|
||||
r.reaction
|
||||
FROM rss_items i
|
||||
JOIN rss_feeds f ON f.id = i.feed_id
|
||||
LEFT JOIN rss_item_reactions r
|
||||
ON r.rss_item_id = i.id AND r.user_id = :uid
|
||||
WHERE f.user_id = :uid
|
||||
AND (:feed_id IS NULL OR f.id = :feed_id)
|
||||
AND i.published_at >= NOW() - make_interval(days => :days)
|
||||
ORDER BY i.published_at DESC NULLS LAST
|
||||
LIMIT :limit OFFSET :offset
|
||||
""").bindparams(uid=g.user.id, days=days, limit=limit,
|
||||
offset=offset, feed_id=feed_id)
|
||||
)
|
||||
rows = result.mappings().all()
|
||||
|
||||
items = [
|
||||
{
|
||||
"id": r["id"],
|
||||
"title": r["title"],
|
||||
"url": r["url"],
|
||||
"snippet": (r["content"] or "")[:300],
|
||||
"published_at": r["published_at"].isoformat() if r["published_at"] else None,
|
||||
"topics": r["topics"] or [],
|
||||
"source": r["feed_title"],
|
||||
"reaction": r["reaction"],
|
||||
}
|
||||
for r in rows
|
||||
]
|
||||
return jsonify({"items": items, "offset": offset, "limit": limit})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 2 — Briefing view redesign
|
||||
|
||||
### 2a. Layout restructure
|
||||
|
||||
**File:** `frontend/src/views/BriefingView.vue`
|
||||
|
||||
**Layout change:** Replace `.briefing-shell` (single column, max-width 760px) with a full-width 3-column grid:
|
||||
|
||||
```css
|
||||
.briefing-shell {
|
||||
display: grid;
|
||||
grid-template-rows: auto 1fr;
|
||||
grid-template-columns: 1fr 2fr 1fr;
|
||||
height: 100%;
|
||||
min-height: 0;
|
||||
}
|
||||
|
||||
.briefing-header {
|
||||
grid-column: 1 / -1; /* spans all three columns */
|
||||
}
|
||||
|
||||
.briefing-left {
|
||||
grid-column: 1;
|
||||
border-right: 1px solid var(--color-border);
|
||||
overflow-y: auto;
|
||||
padding: 1rem;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.75rem;
|
||||
}
|
||||
|
||||
.briefing-center {
|
||||
grid-column: 2;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
min-height: 0;
|
||||
}
|
||||
|
||||
.briefing-right {
|
||||
grid-column: 3;
|
||||
border-left: 1px solid var(--color-border);
|
||||
overflow-y: auto;
|
||||
padding: 1rem;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.5rem;
|
||||
}
|
||||
|
||||
@media (max-width: 900px) {
|
||||
.briefing-shell {
|
||||
grid-template-columns: 1fr;
|
||||
grid-template-rows: auto auto 1fr auto;
|
||||
}
|
||||
.briefing-header { grid-column: 1; }
|
||||
.briefing-left, .briefing-right {
|
||||
border: none;
|
||||
border-bottom: 1px solid var(--color-border);
|
||||
max-height: 200px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2b. Weather panel (left column)
|
||||
|
||||
Remove `WeatherCard` from the message flow. Load weather independently on mount:
|
||||
|
||||
Extract the existing weather shape from `MessageMetadata` into a standalone `WeatherData` interface at the top of `BriefingView.vue` (same fields: `location`, `current_temp`, `condition`, `today_high`, `today_low`, `yesterday_high`, `yesterday_low`, `forecast[]`). The `MessageMetadata` interface can then be removed since `rss_items`/weather are no longer read from message metadata.
|
||||
|
||||
```typescript
|
||||
const weatherData = ref<WeatherData[]>([])
|
||||
|
||||
async function loadWeather() {
|
||||
try {
|
||||
const data = await apiGet<{ locations: WeatherData[] }>('/api/briefing/weather')
|
||||
weatherData.value = data.locations ?? []
|
||||
} catch { /* silent */ }
|
||||
}
|
||||
```
|
||||
|
||||
Render in left column:
|
||||
```html
|
||||
<div class="briefing-left">
|
||||
<div class="panel-label">Weather</div>
|
||||
<template v-if="weatherData.length">
|
||||
<WeatherCard v-for="loc in weatherData" :key="(loc as WeatherData).location" :weather="loc" />
|
||||
</template>
|
||||
<div v-else class="panel-empty">No weather configured</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### 2c. News panel (right column)
|
||||
|
||||
Load on mount and on background refresh:
|
||||
|
||||
```typescript
|
||||
const newsItems = ref<NewsItem[]>([])
|
||||
|
||||
async function loadNews() {
|
||||
try {
|
||||
const data = await apiGet<{ items: NewsItem[] }>('/api/briefing/news?days=2&limit=40')
|
||||
newsItems.value = data.items
|
||||
} catch { /* silent */ }
|
||||
}
|
||||
```
|
||||
|
||||
Render in right column using the existing `news-card` markup and `handleReaction` function. Remove the inline `news-cards` block from the message loop.
|
||||
|
||||
### 2d. Auto-scroll to bottom on mount
|
||||
|
||||
After messages load, scroll the center messages container to the bottom:
|
||||
|
||||
```typescript
|
||||
const messagesEl = ref<HTMLElement | null>(null)
|
||||
|
||||
function scrollToBottom() {
|
||||
nextTick(() => {
|
||||
if (messagesEl.value) {
|
||||
messagesEl.value.scrollTop = messagesEl.value.scrollHeight
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
Call `scrollToBottom()` after `loadAll()` completes and after the streaming watcher fires.
|
||||
|
||||
### 2e. Remove inline weather/news from message flow
|
||||
|
||||
In the message loop template, remove:
|
||||
- The `<WeatherCard>` block rendered above assistant messages
|
||||
- The `<div class="news-cards">` block rendered below assistant messages
|
||||
|
||||
The `msgMetadata()` helper and `MessageMetadata` interface can be removed entirely since they're no longer used in the template.
|
||||
|
||||
---
|
||||
|
||||
## Section 3 — Deep article Q&A in briefing chat
|
||||
|
||||
**File:** `src/fabledassistant/services/llm.py` (the `build_context()` function)
|
||||
|
||||
After the existing RAG context is assembled, check if the conversation is a briefing and inject article content:
|
||||
|
||||
```python
|
||||
# Inject briefing article content for follow-up Q&A
|
||||
if conversation and getattr(conversation, "conversation_type", None) == "briefing":
|
||||
article_context = await _build_briefing_article_context(conversation.id)
|
||||
if article_context:
|
||||
system_parts.append(article_context)
|
||||
```
|
||||
|
||||
New helper function in `llm.py`:
|
||||
|
||||
```python
|
||||
async def _build_briefing_article_context(conv_id: int) -> str:
|
||||
"""
|
||||
Fetch article content from today's briefing message and return
|
||||
a formatted context block for injection into the system prompt.
|
||||
Capped at 10 articles × 500 chars to keep token use reasonable.
|
||||
"""
|
||||
from sqlalchemy import select, text as _text
|
||||
from fabledassistant.models import async_session
|
||||
from fabledassistant.models.conversation import Message
|
||||
import json
|
||||
|
||||
async with async_session() as session:
|
||||
# Get most recent assistant briefing message with rss_item_ids
|
||||
result = await session.execute(
|
||||
select(Message)
|
||||
.where(
|
||||
Message.conversation_id == conv_id,
|
||||
Message.role == "assistant",
|
||||
)
|
||||
.order_by(Message.created_at.desc())
|
||||
.limit(10)
|
||||
)
|
||||
messages = result.scalars().all()
|
||||
|
||||
rss_item_ids: list[int] = []
|
||||
for msg in messages:
|
||||
meta = msg.metadata or {}
|
||||
if isinstance(meta, str):
|
||||
try:
|
||||
meta = json.loads(meta)
|
||||
except Exception:
|
||||
continue
|
||||
ids = meta.get("rss_item_ids") or []
|
||||
if ids:
|
||||
rss_item_ids = ids
|
||||
break
|
||||
|
||||
if not rss_item_ids:
|
||||
return ""
|
||||
|
||||
async with async_session() as session:
|
||||
result = await session.execute(
|
||||
_text("""
|
||||
SELECT i.title, i.url, i.content, f.title AS feed_title
|
||||
FROM rss_items i
|
||||
JOIN rss_feeds f ON f.id = i.feed_id
|
||||
WHERE i.id = ANY(:ids)
|
||||
ORDER BY i.published_at DESC NULLS LAST
|
||||
LIMIT 10
|
||||
""").bindparams(ids=rss_item_ids[:10])
|
||||
)
|
||||
rows = result.mappings().all()
|
||||
|
||||
if not rows:
|
||||
return ""
|
||||
|
||||
lines = ["ARTICLE CONTEXT (source articles from today's briefing):"]
|
||||
for row in rows:
|
||||
lines.append(f"\n[{row['feed_title']}] {row['title']}")
|
||||
if row["url"]:
|
||||
lines.append(f"URL: {row['url']}")
|
||||
if row["content"]:
|
||||
lines.append(row["content"][:500])
|
||||
return "\n".join(lines)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 4 — News archive view
|
||||
|
||||
### 4a. Frontend type
|
||||
|
||||
**File:** `frontend/src/types/news.ts` (new)
|
||||
|
||||
```typescript
|
||||
export interface NewsItem {
|
||||
id: number
|
||||
title: string
|
||||
url: string
|
||||
snippet: string
|
||||
published_at: string | null
|
||||
topics: string[]
|
||||
source: string
|
||||
reaction: 'up' | 'down' | null
|
||||
}
|
||||
```
|
||||
|
||||
### 4b. NewsView component
|
||||
|
||||
**File:** `frontend/src/views/NewsView.vue` (new)
|
||||
|
||||
- Loads feeds list from `GET /api/briefing/feeds` for the filter dropdown
|
||||
- Loads items from `GET /api/briefing/news?days=90&limit=40&offset=0&feed_id=X`
|
||||
- "Load more" button appends next page (increments offset by 40)
|
||||
- Each card: source label, title as `<a target="_blank">`, snippet, relative date, 👍/👎 buttons
|
||||
- Reactions call existing `POST /api/briefing/rss-reactions` / `DELETE /api/briefing/rss-reactions/:id`
|
||||
- Local `reactions` map tracks optimistic state (same pattern as `BriefingView.vue`)
|
||||
|
||||
```typescript
|
||||
const items = ref<NewsItem[]>([])
|
||||
const offset = ref(0)
|
||||
const hasMore = ref(true)
|
||||
const selectedFeedId = ref<number | null>(null)
|
||||
const loading = ref(false)
|
||||
|
||||
async function loadMore() {
|
||||
if (loading.value || !hasMore.value) return
|
||||
loading.value = true
|
||||
try {
|
||||
const params = new URLSearchParams({
|
||||
days: '90', limit: '40', offset: String(offset.value)
|
||||
})
|
||||
if (selectedFeedId.value) params.set('feed_id', String(selectedFeedId.value))
|
||||
const data = await apiGet<{ items: NewsItem[] }>(`/api/briefing/news?${params}`)
|
||||
items.value = [...items.value, ...data.items]
|
||||
offset.value += data.items.length
|
||||
hasMore.value = data.items.length === 40
|
||||
} finally {
|
||||
loading.value = false
|
||||
}
|
||||
}
|
||||
|
||||
function onFeedChange() {
|
||||
items.value = []
|
||||
offset.value = 0
|
||||
hasMore.value = true
|
||||
loadMore()
|
||||
}
|
||||
```
|
||||
|
||||
### 4c. Router and nav
|
||||
|
||||
**File:** `frontend/src/router/index.ts`
|
||||
```typescript
|
||||
{ path: '/news', component: () => import('@/views/NewsView.vue') }
|
||||
```
|
||||
|
||||
**File:** `frontend/src/App.vue` (nav links section)
|
||||
Add `<router-link to="/news">News</router-link>` alongside Notes/Tasks/Projects.
|
||||
|
||||
---
|
||||
|
||||
## What is NOT in scope
|
||||
|
||||
- Topic-based filtering in the news archive (reactions shape preferences; filtering can come later)
|
||||
- Inline article display / full-text reader (links open to source)
|
||||
- Changes to the RSS feed management UI in Settings
|
||||
- Push notifications for new articles
|
||||
Reference in New Issue
Block a user