document-summarize

Handles uploaded document attachments in snappy-chat. Extracts text server-side and lets the LLM summarize, analyze key points, answer questions, render tables, and compare documents.

Supported formats

Install requirements

All parsers are installed in ~/projects/snappy-os:

cd ~/projects/snappy-os
npm install pdf-parse mammoth csv-parse
# optional:
npm install xlsx

Architecture

1. file-attach-button.tsx - user drops/selects PDF/DOCX/XLSX/CSV:

• Binary files read as ArrayBuffer → btoa() → base64 string
• Encoded as [Document: name.pdf]\ndata:application/pdf;base64,<data>\n\n
• Added to pendingAttachment.content (same as text/image path)

1. server.ts (POST /dispatch/chat):

• Extracts [Document: ...] blocks via regex (parallel to image extraction)
• Calls state/lib/document-parse.ts → parseDocumentFromBase64()
• Builds <document name="..." [N page(s)]>extracted text</document> blocks
• Injects into promptForLLM as: "The user has attached the following document(s)...\n\n<document>...\n\nUser request: <intent>"

1. state/lib/document-parse.ts - document parsing library:

• parseDocumentFromBase64(name, mimeType, base64) → DocumentParseResult
• Truncates to 12000 chars to stay within LLM context budget
• CLI self-test: npx tsx state/lib/document-parse.ts <path-to-file>

Steps

1. User attaches a document via the paperclip button or drag-drop in snappy-chat.
2. file-attach-button.tsx detects binary doc (isBinaryDoc()) → reads as ArrayBuffer → encodes as [Document: ...] marker.
3. User types intent ("summarize this", "what are the key points", etc.) and sends.
4. App.tsx prepends pendingAttachment.content to the intent string before dispatch.
5. server.ts extracts the [Document: ...] block, calls parseDocumentFromBase64().
6. Extracted text is wrapped in <document> tags and prepended to promptForLLM.
7. LLM receives clean prompt with document context; responds with summary/analysis.
8. For follow-up questions (step 5-7 in the flow), prior conversation history includes the assistant's previous summary so the LLM can reference it.

Key points / limitations

• PDF text extraction requires selectable text (scanned/image PDFs will yield empty or garbled text).
• Max 12000 chars extracted per document; large documents are truncated with a note.
• XLSX requires npm install xlsx separately (not installed by default).
• For .docx files, only raw text is extracted (no table structure, no images).
• CSV files render as a markdown table (max 200 rows; excess noted).
• "Compare this PDF to the previous one" works via conversation history - the previous summary is in the prior_conversation block.
• "Extract the table on page 3 as a Lang Table" works for PDFs with selectable table text; the LLM will structure it using OpenUI Table primitive.

Testing

# Verify PDF parsing works:
npx tsx state/lib/document-parse.ts /path/to/test.pdf

# Verify CSV:
npx tsx state/lib/document-parse.ts /path/to/test.csv

# Verify DOCX:
npx tsx state/lib/document-parse.ts /path/to/test.docx

# Verify the server extracts documents (direct API):
curl -X POST 127.0.0.1:3147/dispatch/chat \
  -H "Content-Type: application/json" \
  -d "{\"intent\":\"[Document: test.pdf]\\ndata:application/pdf;base64,$(base64 -i /path/to/test.pdf | tr -d '\\n')\\n\\nSummarize this.\"}" \
  | grep -o '"delta":"[^"]*' | head -5

document-summarize - loader

Per-turn rules for document attachment + summarization in snappy-chat. Full skill: state/skills/document-summarize/SKILL.md.

Critical Rules

1. Binary docs use ArrayBuffer, not readAsText. readAsText() on PDF/DOCX/XLSX = garbage. Route via isBinaryDoc() → readAsArrayBuffer() → base64.
2. Encoding: [Document: name]\ndata:<mime>;base64,<data>\n\n. Server regex /\[Document:([^\]]+)\]\ndata:([^;]+);base64,([^\n]+)\n*/g - exact format or silent extraction fail.
3. Parser at state/lib/document-parse.ts. Import: await import("../../lib/document-parse.ts"). Test: npx tsx state/lib/document-parse.ts <file>.
4. PDF: PDFParse class, not default import. Wrong: import pdfParse from 'pdf-parse'. Correct: import { PDFParse } from 'pdf-parse'.
5. mammoth: extractRawText({ buffer: buf }) → { value: string }. Import: import { extractRawText } from 'mammoth'.
6. csv-parse: sync path with { columns: true, skip_empty_lines: true, relax_column_count: true }. Renders as markdown table.
7. LLM context block: <document name="filename" [N page(s)]>...text...</document>. Prepended with "The user has attached the following document(s) for analysis:\n\n".
8. Empty intent allowed when document attached. Defaults to "Please summarize this document."
9. 12000 char truncation intentional. Suffix: [...document truncated at 12000 chars].
10. Follow-ups via conversation history. User does NOT need to re-attach. Works via priorMessages.
11. XLSX requires separate install. npm install xlsx - not default.
12. Drag-drop same as click. useFileDrop hook routes via readAsArrayBuffer().

Commands

Self-Test

• [ ] Binary docs use readAsArrayBuffer(), not readAsText()?
• [ ] Encoding format: [Document: name]\ndata:<mime>;base64,...?
• [ ] Parser location: state/lib/document-parse.ts?
• [ ] PDF uses PDFParse class import?
• [ ] mammoth uses extractRawText({ buffer })?
• [ ] csv-parse uses sync path with correct options?
• [ ] 12000 char truncation is intentional (context budget)?
• [ ] Follow-ups work via priorMessages (no re-attach)?
• [ ] XLSX needs separate install?
• [ ] Drag-drop routes same as click (via readAsArrayBuffer)?

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] document-summarize: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind is the SECOND pairing predicate. Pick the value that describes what you actually did:
• shape-ok - frontmatter-shape verification only
• skill-ran - the skill ran end-to-end with eval row in state/log/evals.ndjson
• loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case), OR regen rewrote it
• pattern-elevated - you promoted a recurring failure to a Critical Rule

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.