docs: architecture map (initial 5-slice generation, 105 pages)
Five-slice navigable map of the entire codebase under
docs/architecture-map/. Each slice is a self-contained
breadcrumbed sub-tree:
01-frontend (16) Svelte/SvelteKit UI
02-tauri-runtime (26) src-tauri commands + lifecycle
03-audio-transcription (16) audio + transcription crates
04-llm-formatting-mcp (19) llm, ai-formatting, mcp, cloud
05-core-storage-hotkey-build core, storage, hotkey, workspace,
(26) CI, dev glue
Plus master README.md and data-flow-end-to-end.md tracing
audio bytes from microphone to FTS5 search to MCP read.
Generated by 5 parallel subagents on 2026/05/09 against
HEAD 3c47000. Each page has YAML frontmatter, file:line code
refs, sibling cross-links, plain-English summaries.
Aggregated debt surfaced (full lists in master README):
RB-08 macOS power assertion, schema head drift v14 vs v15,
VAD blocked on ort version conflict, streaming primitives
not wired into live.rs, no prompt versioning, MCP has no
auth, cloud-providers in-memory keystore, SettingsPage
2 484 LOC, commands/live.rs 1 737 LOC, dual theme system,
brand rename to Lumenote pending across the codebase.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
jars
@@ -0,0 +1,85 @@
|
||||
---
|
||||
name: LLM extract_tasks surface
|
||||
type: architecture-map-page
|
||||
slice: 04-llm-formatting-mcp
|
||||
last_verified: 2026/05/09
|
||||
---
|
||||
|
||||
# LLM `extract_tasks` surface
|
||||
|
||||
> **Where you are:** [Architecture map](../README.md) → [LLM, Formatting, MCP](README.md) → extract_tasks
|
||||
|
||||
**Plain English summary.** `extract_tasks` reads a transcript and pulls out the action items the speaker actually committed to. Output is a JSON array of imperative sentences, possibly empty. The GBNF accepts an empty array, the prompt asks the model to return one when nothing was committed. A feedback-conditioned variant supports HITL few-shot examples.
|
||||
|
||||
## At a glance
|
||||
|
||||
- Crate: `magnotia-llm`
|
||||
- Path: `crates/llm/src/lib.rs:294` (`extract_tasks`) and `:358` (`extract_tasks_with_feedback`)
|
||||
- LOC: ~50 across both methods
|
||||
- Public surface:
|
||||
- `pub fn extract_tasks(&self, transcript: &str) -> Result<Vec<String>, EngineError>`
|
||||
- `pub fn extract_tasks_with_feedback(&self, transcript: &str, examples: &[prompts::FeedbackExample]) -> Result<Vec<String>, EngineError>`
|
||||
- External deps that matter: GBNF sampler from llama-cpp-2; `serde_json` for the array parse.
|
||||
- Tauri command that calls this (slice 2, best guess): `commands::tasks::extract_tasks_from_transcript_cmd` (`src-tauri/src/commands/tasks.rs:346`), wired via `src-tauri/src/lib.rs:366`. The actual call is at `tasks.rs:364` — `tokio::task::spawn_blocking(move || engine.extract_tasks_with_feedback(&transcript, &examples))`.
|
||||
|
||||
## What's in here
|
||||
|
||||
### `extract_tasks` (`crates/llm/src/lib.rs:294`)
|
||||
|
||||
Convenience wrapper that calls `extract_tasks_with_feedback(transcript, &[])`.
|
||||
|
||||
### `extract_tasks_with_feedback` (`crates/llm/src/lib.rs:358`)
|
||||
|
||||
Steps:
|
||||
|
||||
1. If `transcript.trim().is_empty()`, return `Ok(Vec::new())` immediately. No model touch — distinct from `cleanup_text` which returns an empty string. The empty-vec convention matches what callers expect from "the speaker said nothing actionable".
|
||||
2. Borrow the loaded model via `loaded_model_arc()`. `EngineError::NotLoaded` if no model is loaded.
|
||||
3. Build the system prompt: `prompts::build_conditioned_system_prompt(prompts::EXTRACT_TASKS_SYSTEM, examples)`. Same conditioning logic as `decompose_task_with_feedback`.
|
||||
4. Render a chat prompt with two messages — `("system", system)` and `("user", &format!("Transcript:\n{transcript}"))`.
|
||||
5. Call `generate` with:
|
||||
- `max_tokens: 768`
|
||||
- `temperature: 0.0`
|
||||
- `stop_sequences: ["<|im_end|>", "<|im_end_of_text|>"]`
|
||||
- `grammar: Some(grammars::OPTIONAL_TASK_ARRAY_GRAMMAR.to_string())`
|
||||
6. Parse the raw output via `parse_string_array`.
|
||||
|
||||
The empty-array case is the difference from `decompose_task`: `OPTIONAL_TASK_ARRAY_GRAMMAR` permits `[]` as a valid root expansion; `TASK_ARRAY_GRAMMAR` does not.
|
||||
|
||||
## Data flow
|
||||
|
||||
```
|
||||
(transcript: &str, examples: &[FeedbackExample])
|
||||
→ empty-transcript short-circuit (returns Vec::new())
|
||||
→ loaded_model_arc()
|
||||
→ build_conditioned_system_prompt(EXTRACT_TASKS_SYSTEM, examples)
|
||||
→ render_chat_prompt([(system, system), (user, "Transcript:\n{transcript}")])
|
||||
→ generate(prompt, GenerationConfig {
|
||||
max_tokens: 768, temp: 0.0,
|
||||
stops: [<|im_end|>, <|im_end_of_text|>],
|
||||
grammar: Some(OPTIONAL_TASK_ARRAY_GRAMMAR),
|
||||
})
|
||||
→ parse_string_array(raw)
|
||||
→ Vec<String>
|
||||
```
|
||||
|
||||
## Prompts and grammars
|
||||
|
||||
- System prompt: `prompts::EXTRACT_TASKS_SYSTEM` at `crates/llm/src/prompts.rs:40`. Crucial line: "Output an empty array if there are no action items."
|
||||
- GBNF: `grammars::OPTIONAL_TASK_ARRAY_GRAMMAR` at `crates/llm/src/grammars.rs:30`. Two root alternatives: `"[" ws "]"` for the empty case, or `"[" ws string tail ws "]"` with a recursive tail for one-or-more strings.
|
||||
|
||||
See [`llm-prompts-and-grammars.md`](llm-prompts-and-grammars.md) for full text.
|
||||
|
||||
## Watch-outs
|
||||
|
||||
- **Empty array is a valid, expected output.** UI and downstream code must treat `Ok(Vec::new())` as the "no tasks" success path, not as an error. `extract_corrections`-style learning loops should skip empty results entirely.
|
||||
- **`max_tokens: 768` is larger than `decompose_task`'s 512.** A long meeting transcript can produce many actions; the looser cap reflects that. It does not bound the count of items, only the total tokens of the JSON literal.
|
||||
- **The system prompt is the only thing telling the model "explicit commitments only".** A model that ignores instruction would happily list observations and wishes; the GBNF is silent on content. If the cleanup_text-style "translator not editor" framing is ever copied here, that is a deliberate prompt-engineering decision, not a refactor.
|
||||
- **Feedback conditioning weight.** Recent-first ordering in `examples` is preserved; the prompt builder appends them as a `- Input: ... \n Good output: ...` bullet list. Long lists dilute the weighting; the Tauri command at `src-tauri/src/commands/tasks.rs` decides how many examples to pass.
|
||||
- **Same GBNF parse-vs-serde concerns as `decompose_task`.** The grammar guarantees a valid JSON array shape; `serde_json::from_str` can still fail on an unfortunate truncation when output approaches `max_tokens`.
|
||||
|
||||
## See also
|
||||
|
||||
- [LLM engine](llm-engine.md)
|
||||
- [LLM decompose_task (sibling array surface, stricter GBNF)](llm-decompose-task.md)
|
||||
- [Prompts and grammars catalogue](llm-prompts-and-grammars.md)
|
||||
- [Slice README](README.md)
|
||||
Reference in New Issue
Block a user