Lesson 5 · Assemble the pipeline¶
Forty-five minutes. At the end you understand the package well enough to change any part, and you have a session on disk.
From scripts to a package¶
The three scripts work. They also have a problem: each loads its model on every run. Whisper small.en takes two seconds to load, medium.en ten. The language model server keeps its own model warm, but the scribe needs somewhere to keep the transcriber, remember what has been done, and write things down. That somewhere is the scribe package.
scribe/
├── config.py every setting, read once from SCRIBE_* environment variables
├── audio.py record(), load(), save_wav() <- Lesson 2
├── transcribe.py WhisperTranscriber, VoskTranscriber <- Lesson 3
├── notes.py LLMClient, templates <- Lesson 4
├── storage.py Store: sessions, audit log, purge <- Lesson 7
├── pipeline.py Pipeline: chains the above <- this lesson
├── cli.py the `scribe` command
└── server.py the review app <- Lesson 6
Each module does one thing and can be used alone. pipeline.py is the only one that imports all the others.
The pipeline in fifteen lines¶
"""Lesson 5 - the three pieces, chained, using the scribe package.
python steps/04_pipeline.py samples/visit-01.wav [template]
This is what `scribe run` does. Read scribe/pipeline.py next; it is about 70 lines.
"""
import sys
from scribe.pipeline import Pipeline
audio = sys.argv[1]
template = sys.argv[2] if len(sys.argv) > 2 else "soap"
pipe = Pipeline() # reads SCRIBE_* environment variables
meta = pipe.ingest(audio, label="lesson 5") # 1. session folder + audio.wav
transcript = pipe.transcribe(meta.id) # 2. transcript.json
draft = pipe.draft(meta.id, template) # 3. note.md
print(transcript.as_lines())
print("\n" + "=" * 60 + "\n")
print(draft.text)
print(f"\nsession {meta.id}: {transcript.elapsed_seconds}s to transcribe, {draft.elapsed_seconds}s to draft",
file=sys.stderr)
Now read scribe/pipeline.py. Three things to notice:
Lazy loading. Pipeline.transcriber and .llm are properties that create the model on first use. Starting the review app is instant; the first transcription pays the load cost once.
Sessions. ingest() creates a folder under scribe_data/sessions/<id>/ and stores the audio as a normalised WAV. Everything after that is keyed by the session id. You can stop after transcribing and draft later, or draft again with a different template.
Injection. The constructor accepts a transcriber, an LLM client and a store. That is how the test suite runs the whole server with fake models in a third of a second (tests/test_server.py). It is also how you would plug in a different speech engine without touching anything else.
What is on disk¶
scribe_data/
├── audit.log one JSON line per event, append only
├── templates/ your own templates go here (Lesson 9)
└── sessions/
└── 20261109-074309-2f4500/
├── audio.wav deleted when the note is signed
├── transcript.json segments with timestamps
├── note.md the draft, then your edited version
└── meta.json status, template, model, event history
Everything is a plain file. You can grep it, back it up with rsync, and read it in ten years. No database until you need one, and a single clinician never does.
The command line¶
scribe/cli.py is one function per subcommand, no framework. scribe run is Pipeline.run() and a print. If you want a scribe export that writes the note to a USB stick, it is a ten-line function and a parser entry. The CLI reference lists what exists.
Try¶
- Run
steps/04_pipeline.pytwice in a row and compare the transcription times. They are the same: eachpythonprocess loads Whisper fresh. The review app in the next lesson is a single long-running process, which is why it feels faster after the first visit. - Add a
SCRIBE_DEFAULT_TEMPLATEsetting. It touchesconfig.py(one field) andcli.py(two default values). There is no such setting today on purpose: templates are chosen per draft. Deciding whether that is the right call is the exercise.
Next: Lesson 6 · The review app.