Skip to content

feat(source): pdf and audio sources with page/timestamp receipts #613

Description

@plind-junior

What you're trying to do

a lot of the knowledge worth keeping arrives as a pdf (a spec, a paper, a
contract) or as audio (a recorded call, a voice note). vouch's source pipeline
handles text; neither of those can currently become a cited source, so the
knowledge inside them either never enters the KB or enters it as an
unattributable paraphrase.

ditto accepts pdfs and audio as attachments and analyses them inline
(heyditto.ai/docs/attachments) — but their own docs don't claim the content
becomes durably searchable memory, and nothing about it is citable afterwards.
vouch's receipt primitive is exactly what makes this worth doing properly:
"page 7, characters 1200–1340" is a receipt; "the pdf said something like this"
is not.

What you've tried

  • vouch source add / vouch source fetch → registers and fetches; text
    extraction only.
  • extracting to text by hand and ingesting that → loses the offset mapping back
    to the original, so receipts point at a derived artifact nobody has.

Suggested shape

  • pdf: extract the text layer, keep a page + character-offset mapping so a
    receipt resolves to a real location in the original file. scanned pdfs with
    no text layer are out of scope (say so, fail loudly, don't silently OCR).
  • audio: transcribe through a configured command — the compile.llm_cmd
    pattern, deployment config, no baked model dependency — and store the
    transcript as the verbatim artifact with timestamp offsets as the receipt
    coordinate.
  • both register as ordinary sources, so vouch ingest, the receipt gate,
    kb.source_verify and receipt-coverage scoring all work unchanged.

Compatibility considerations

additive. the receipt coordinate model may need a variant for page/timestamp
offsets alongside byte offsets — that is the one part touching stored shape and
it deserves care, since receipts are the load-bearing primitive.

hard requirement: no new hard dependency. pdf text extraction needs a pure-ish
optional extra, and transcription must stay a configured command. if a pdf
library cannot be added as an optional extra cleanly, ship audio first.

Alternatives

  • pre-convert externally and ingest the text — works today, loses the link back
    to the original, so source_verify cannot re-check anything.
  • store the binary and skip receipts — abandons the property that makes vouch
    different.

part of the ditto-style track — see .superpowers/DITTO-STYLE-PLAN.md (T4.2).

Metadata

Metadata

Assignees

No one assigned

    Labels

    clicommand line interfaceenhancementNew feature or requeststoragekb storage, migrations, schemas, and proposals

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions