228 lines
9.4 KiB
Markdown
228 lines
9.4 KiB
Markdown
# Article Reading Design
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Allow the LLM to fetch and read the full text of any URL on demand, fix conversation history so tool context survives follow-up turns, and make the briefing Discuss button inject article content as a persisted tool exchange rather than raw user-message text.
|
||
|
||
**Architecture:** Four self-contained changes — history reconstruction fix (prerequisite), `read_article` tool, Discuss endpoint, and content cap removal.
|
||
|
||
**Tech Stack:** Python/Quart backend, trafilatura (already installed), SQLAlchemy async, Vue 3 frontend.
|
||
|
||
---
|
||
|
||
## Problem summary
|
||
|
||
Three interrelated issues observed in briefing conversations:
|
||
|
||
1. **Missing `read_article` tool** — when a user pastes a URL, the LLM calls `search_web` (a SearXNG text search), which returns generic site descriptions instead of article content.
|
||
2. **History reconstruction bug** — `routes/chat.py:166` builds the `history` list with only `role` + `content`, silently dropping all `tool_calls` and their results from prior turns. Tool context is lost on every follow-up.
|
||
3. **Discuss button UX** — inlines raw article text into the user message bubble. Feels clumsy, and the model sometimes searches notes on follow-ups anyway because the article isn't clearly marked as "loaded" context.
|
||
|
||
---
|
||
|
||
## Components
|
||
|
||
### 1. History reconstruction fix
|
||
**File:** `src/fabledassistant/routes/chat.py`
|
||
|
||
The loop at line ~164 that builds `history` must be updated to replay tool exchanges:
|
||
|
||
```python
|
||
history = []
|
||
for msg in conv.messages:
|
||
if msg.role == "system":
|
||
continue
|
||
msg_dict = {"role": msg.role, "content": msg.content or ""}
|
||
if msg.tool_calls:
|
||
msg_dict["tool_calls"] = [
|
||
{"function": {"name": tc["function"], "arguments": tc["arguments"]}}
|
||
for tc in msg.tool_calls
|
||
]
|
||
history.append(msg_dict)
|
||
for tc in msg.tool_calls:
|
||
history.append({"role": "tool", "content": json.dumps(tc.get("result", {}))})
|
||
else:
|
||
history.append(msg_dict)
|
||
```
|
||
|
||
The `tool_calls` JSONB column already stores `[{function, arguments, result}]` per call. No schema change needed.
|
||
|
||
### 2. `read_article` tool
|
||
**Files:** `src/fabledassistant/services/research.py`, `src/fabledassistant/services/tools.py`, `src/fabledassistant/services/rss.py`
|
||
|
||
Move `_fetch_full_article` from `rss.py` to `research.py` (imported back into `rss.py` to avoid breaking existing calls). This makes it available to `execute_tool` without a circular import.
|
||
|
||
Tool definition added to `_TOOLS` in `tools.py`:
|
||
|
||
```python
|
||
{
|
||
"type": "function",
|
||
"function": {
|
||
"name": "read_article",
|
||
"description": (
|
||
"Fetch and read the full text of a web page or article from a URL. "
|
||
"Use when the user shares a URL and wants you to read it, "
|
||
"or to get the full content of a linked page. "
|
||
"Do not use search_web for URLs — use this tool instead."
|
||
),
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"url": {"type": "string", "description": "The URL to fetch"}
|
||
},
|
||
"required": ["url"],
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
`execute_tool` handler:
|
||
|
||
```python
|
||
elif tool_name == "read_article":
|
||
from fabledassistant.services.research import _fetch_full_article
|
||
url = arguments.get("url", "").strip()
|
||
if not url:
|
||
return {"success": False, "error": "No URL provided"}
|
||
content = await _fetch_full_article(url)
|
||
if not content:
|
||
return {"success": False, "error": f"Could not fetch article content from {url}"}
|
||
TOOL_CONTENT_CAP = 40_000
|
||
truncated = len(content) > TOOL_CONTENT_CAP
|
||
return {
|
||
"success": True,
|
||
"type": "article_content",
|
||
"url": url,
|
||
"content": content[:TOOL_CONTENT_CAP],
|
||
"truncated": truncated,
|
||
}
|
||
```
|
||
|
||
### 3. `add_message` — add `tool_calls` parameter
|
||
**File:** `src/fabledassistant/services/chat.py`
|
||
|
||
`add_message` needs to accept and store `tool_calls` so the Discuss endpoint can create synthetic messages:
|
||
|
||
```python
|
||
async def add_message(
|
||
conversation_id: int,
|
||
role: str,
|
||
content: str,
|
||
context_note_id: int | None = None,
|
||
status: str | None = None,
|
||
tool_calls: list | None = None,
|
||
) -> Message:
|
||
```
|
||
|
||
Set `msg.tool_calls = tool_calls` when provided.
|
||
|
||
### 4. Discuss endpoint
|
||
**File:** `src/fabledassistant/routes/briefing.py`
|
||
|
||
New route: `POST /api/briefing/articles/<int:item_id>/discuss`
|
||
|
||
Request body: `{"conv_id": <int>}`
|
||
|
||
Steps:
|
||
1. Look up `rss_items` row by `item_id` — verify it belongs to the user via feed ownership. Return 404 if not found.
|
||
2. Look up conversation by `conv_id` — verify it belongs to the user. Return 404 if not found.
|
||
3. If generation already running for `conv_id` → return 409.
|
||
4. Fetch stored content: `article_content = item.content or item.snippet or ""`
|
||
5. Store synthetic assistant message (status=`"complete"`, role=`"assistant"`, content=`""`, tool_calls as below):
|
||
```python
|
||
synthetic_tool_calls = [{
|
||
"function": "read_article",
|
||
"arguments": {"url": item.url},
|
||
"result": {
|
||
"success": True,
|
||
"type": "article_content",
|
||
"url": item.url,
|
||
"content": article_content,
|
||
"truncated": False,
|
||
},
|
||
}]
|
||
await add_message(conv_id, "assistant", "", status="complete", tool_calls=synthetic_tool_calls)
|
||
```
|
||
6. Store user message: `await add_message(conv_id, "user", "Please summarize and discuss this article.")`
|
||
7. Build `history` from `conv.messages` (using the fixed builder above).
|
||
8. Create assistant placeholder, create buffer, launch `run_generation` as normal.
|
||
9. Return `{"assistant_message_id": ..., "status": "generating"}` 202.
|
||
|
||
### 5. Frontend: BriefingView.vue
|
||
**File:** `frontend/src/views/BriefingView.vue`
|
||
|
||
Replace `discussArticle()`:
|
||
|
||
```typescript
|
||
async function discussArticle(item: NewsItem) {
|
||
if (!todayConvId.value) return
|
||
if (!isToday.value) selectedConvId.value = todayConvId.value
|
||
await nextTick(() => {
|
||
document.querySelector('.briefing-center')?.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
|
||
})
|
||
await apiClient.post(`/api/briefing/articles/${item.id}/discuss`, {
|
||
conv_id: todayConvId.value,
|
||
})
|
||
// Re-fetch conversation so the new messages appear, then start SSE streaming.
|
||
// The existing chatStore.fetchConversation + startStreaming pattern handles this.
|
||
await chatStore.fetchConversation(todayConvId.value)
|
||
chatStore.startStreaming(todayConvId.value)
|
||
}
|
||
```
|
||
|
||
The exact method names (`fetchConversation`, `startStreaming`) should match what `BriefingView.vue` already uses for the reply flow — confirm during implementation.
|
||
|
||
The article no longer appears as wall-of-text in the user bubble. The chat UI shows it as a `read_article` tool call card (already handled by `ToolCallCard.vue`).
|
||
|
||
### 6. Content cap removal
|
||
**File:** `src/fabledassistant/services/rss.py`
|
||
|
||
Remove `[:CONTENT_MAX_CHARS]` from:
|
||
- `content = _html_to_text(content)[:CONTENT_MAX_CHARS]` in `extract_item()`
|
||
- `item.content = full_text[:CONTENT_MAX_CHARS]` in the enrichment task
|
||
|
||
The `CONTENT_MAX_CHARS` constant can be removed entirely. Trafilatura extracts only article body text (typically 2K–15K chars for news articles), so content is naturally bounded.
|
||
|
||
---
|
||
|
||
## Data flow
|
||
|
||
### User pastes a URL in chat
|
||
1. User sends message with a URL
|
||
2. LLM calls `read_article(url)`
|
||
3. `execute_tool` calls `_fetch_full_article(url)` → trafilatura extracts clean text
|
||
4. Tool result appended in-memory as `{role: "tool", content: json}`
|
||
5. LLM responds based on article content
|
||
6. Generation saves assistant message with `tool_calls=[{function:"read_article", arguments, result}]`
|
||
7. Follow-up turns: history builder replays tool_call + tool result → article stays in context
|
||
|
||
### User clicks Discuss on a briefing article
|
||
1. Frontend calls `POST /api/briefing/articles/{item_id}/discuss` with `{conv_id}`
|
||
2. Backend fetches stored article text from DB (no network request)
|
||
3. Backend stores synthetic assistant message with `read_article` tool result
|
||
4. Backend stores user message `"Please summarize and discuss this article."`
|
||
5. Generation runs — LLM sees pre-loaded article in history
|
||
6. Follow-ups retain context via fixed history builder
|
||
|
||
---
|
||
|
||
## Error handling
|
||
|
||
| Scenario | Behaviour |
|
||
|---|---|
|
||
| `_fetch_full_article` returns `None` (network/extraction failure) | Tool returns `{success: False, error: "Could not fetch article content from [url]"}` — LLM reports conversationally |
|
||
| Discuss: `item_id` not found or wrong user | 404 |
|
||
| Discuss: `conv_id` not found or wrong user | 404 |
|
||
| Discuss: article has no stored content | Falls back to empty string — LLM works with what it has |
|
||
| Discuss: generation already running | 409 |
|
||
| Messages with `tool_calls = None` | History builder unchanged — no regression for existing conversations |
|
||
|
||
---
|
||
|
||
## Tests
|
||
|
||
- **Unit:** `_fetch_full_article` returns `None` → `read_article` tool result has `success: False`
|
||
- **Unit:** History builder with a stored message that has `tool_calls` → output includes assistant tool_call dict + a `{role: "tool"}` dict
|
||
- **Unit:** History builder with messages where `tool_calls = None` → output unchanged from current behaviour
|
||
- **Integration:** `POST /api/briefing/articles/{item_id}/discuss` → two messages stored (synthetic assistant + user message), generation triggered, returns 202
|