Lumotia/docs/architecture-map/04-llm-formatting-mcp/llm-extract-tasks.md

---
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: `lumotia-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)