narra 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
narra-0.0.1/.gitignore ADDED
@@ -0,0 +1,31 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .venv/
6
+ build/
7
+ dist/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .coverage
11
+ htmlcov/
12
+
13
+ # AppleDouble files on exFAT
14
+ ._*
15
+
16
+ # Local config and output
17
+ narra.yaml
18
+ .narra.yaml
19
+ podcasts/
20
+ output/
21
+ *.mp3.tmp
22
+
23
+ # Tauri / Rust
24
+ desktop/src-tauri/target/
25
+ desktop/src-tauri/gen/
26
+
27
+ # OS
28
+ .DS_Store
29
+
30
+ # Node (Tauri CLI)
31
+ node_modules/
narra-0.0.1/CLAUDE.md ADDED
@@ -0,0 +1,83 @@
1
+ # Narra — agent handover
2
+
3
+ `SPEC.md` is the source of truth. This file is the short working note.
4
+
5
+ ## What it is
6
+
7
+ A privacy-first **source → podcast episode** tool. Point it at a PDF or text
8
+ file, choose a format (deep-dive, brief, critique, debate, or a custom
9
+ briefing), a *writer* (the LLM that writes the script) and a *voice* (TTS, one
10
+ per speaker). Get an MP3. Same shape as Limn and Canturía: Python core + Typer
11
+ CLI + FastAPI single page + Tauri v2 shell. PyPI package and CLI: `narra`.
12
+
13
+ Two provider abstractions, chosen independently:
14
+ - **writer** — `gemini` (default), `openai-compatible` (BYOK), `ollama` (local)
15
+ - **voice** — `edge` (default, free), `openai` / `openai-compatible`
16
+ (`/v1/audio/speech`), `gemini` (native), `piper` (local CPU), `kokoro`
17
+ (local CPU / Speaches)
18
+
19
+ ## Status (0.0.1 — skeleton)
20
+
21
+ - Package frame only: installs, imports, `narra --version` / `narra --help` /
22
+ `narra init-config` work.
23
+ - `config.py` (layered, `${VAR}`), `formats.py`, `speakers.py`, `script.py`
24
+ (read_source only) are real.
25
+ - Every writer, every voice, `core.generate()`, and `serve` are **stubs** that
26
+ raise `NotImplementedError` with a TODO.
27
+ - No infographic / show-notes card — that is a separate tool.
28
+ - Next: M1 (see SPEC §10).
29
+
30
+ ## Local commands
31
+
32
+ ```bash
33
+ export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/narra" # repo is on exFAT
34
+ uv sync --all-groups
35
+ uv run --no-sync ruff check src tests
36
+ uv run --no-sync basedpyright
37
+ uv run --no-sync pytest
38
+ ```
39
+
40
+ ## Publish (skeleton → PyPI)
41
+
42
+ ```bash
43
+ uv build
44
+ twine upload dist/narra-0.0.1* # uses ~/.pypirc
45
+ ```
46
+
47
+ CI `publish.yml` also builds on `v*` tags via `pypa/gh-action-pypi-publish`, but
48
+ it needs a `PYPI_API_TOKEN` repo secret; the manual twine path is the reliable
49
+ one until that secret is set.
50
+
51
+ ## Machine gotchas
52
+
53
+ - The repo is on an exFAT drive. Keep the venv on the internal disk via
54
+ `UV_PROJECT_ENVIRONMENT`; macOS writes AppleDouble `._*` files that break
55
+ `uv sync` otherwise. `.gitignore` and the build exclude `._*`.
56
+ - Source material lives in `../` siblings: `generate_podcast.py` (this folder,
57
+ truncated at the Gemini TTS branch) and `~/Downloads/generate_notebook.py`
58
+ (the complete original it was split from — use it to reconstruct the Gemini
59
+ voice path).
60
+
61
+ ## Decisions
62
+
63
+ - Two providers (writer + voice), like Canturía's lyricist + ACE-Step split.
64
+ - Ship edge as the free default voice; Gemini writer as the default writer to
65
+ match the original script's behaviour.
66
+ - Formats are a registry, not hardcoded; the four shipped presets came from the
67
+ original `STYLE_PROMPTS`.
68
+ - 1–N speakers with per-speaker voice override (open-notebook idea); Alex/Sam
69
+ are the two defaults.
70
+ - Default serve port 5372 ("NARR").
71
+ - Attribution retained for GroqCasters (J. Gravelle, MIT) and Open Notebook
72
+ (MIT) — see SPEC §8.
73
+ - Build order: skeleton → M1 CLI/web → M2 → M3 local voices → M4 desktop.
74
+
75
+ ## Reference
76
+
77
+ - Original script: `generate_podcast.py` (this dir) and the complete
78
+ `~/Downloads/generate_notebook.py`.
79
+ - Pattern siblings: `../limn` (providers, serve, Tauri), `../song-gen`
80
+ (canturía — lyricists, serve, pyproject, workflows), `../talk-buddy`
81
+ (Piper bridge, sha256 model install).
82
+ - External ideas: https://github.com/jgravelle/GroqCasters,
83
+ https://github.com/lfnovo/open-notebook.
narra-0.0.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Michael Borck
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
narra-0.0.1/PKG-INFO ADDED
@@ -0,0 +1,113 @@
1
+ Metadata-Version: 2.5
2
+ Name: narra
3
+ Version: 0.0.1
4
+ Summary: A small, privacy-first source-to-podcast tool: a PDF or text file in, a multi-speaker episode out. Bring your own writer and voice.
5
+ Project-URL: Homepage, https://github.com/michael-borck/narra
6
+ Project-URL: Repository, https://github.com/michael-borck/narra
7
+ Project-URL: Issues, https://github.com/michael-borck/narra/issues
8
+ Author-email: Michael Borck <michael.borck@curtin.edu.au>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai,audio,cli,notebooklm,podcast,text-to-speech,tts
12
+ Classifier: Development Status :: 2 - Pre-Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: End Users/Desktop
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Multimedia :: Sound/Audio
24
+ Requires-Python: >=3.10
25
+ Requires-Dist: pydantic>=2.0.0
26
+ Requires-Dist: pyyaml>=6.0.0
27
+ Requires-Dist: requests>=2.31.0
28
+ Requires-Dist: rich>=13.0.0
29
+ Requires-Dist: typer>=0.9.0
30
+ Provides-Extra: audio
31
+ Requires-Dist: pydub>=0.25.1; extra == 'audio'
32
+ Provides-Extra: edge
33
+ Requires-Dist: edge-tts>=6.1.0; extra == 'edge'
34
+ Provides-Extra: gemini
35
+ Requires-Dist: google-genai>=0.3.0; extra == 'gemini'
36
+ Provides-Extra: local
37
+ Requires-Dist: kokoro-onnx>=0.4.0; extra == 'local'
38
+ Requires-Dist: numpy>=1.24.0; extra == 'local'
39
+ Requires-Dist: piper-tts>=1.2.0; extra == 'local'
40
+ Provides-Extra: serve
41
+ Requires-Dist: fastapi>=0.110.0; extra == 'serve'
42
+ Requires-Dist: uvicorn>=0.29.0; extra == 'serve'
43
+ Description-Content-Type: text/markdown
44
+
45
+ # Narra — tell it into a podcast
46
+
47
+ > *narra (Spanish): "tell!" / "narrate!"*
48
+
49
+ A small, privacy-first tool that turns a source document into a two (or more)
50
+ speaker podcast episode. Give it a PDF or text file, pick a format, choose who
51
+ writes the script and which voices speak it, and get an MP3. No account, no
52
+ telemetry, bring your own providers.
53
+
54
+ ## Install
55
+
56
+ ```bash
57
+ pip install "narra[edge,audio]" # core + free edge-tts voice + pydub
58
+ export GEMINI_API_KEY=... # default writer
59
+ ```
60
+
61
+ ## Use
62
+
63
+ ```bash
64
+ narra "paper.pdf" --format deep-dive --out episode.mp3
65
+ narra "notes.txt" --format brief --voice edge
66
+ narra init-config # write an example narra.yaml
67
+ narra serve # local web UI (pip install "narra[serve]")
68
+ ```
69
+
70
+ Or as a library:
71
+
72
+ ```python
73
+ from narra.config import load_config
74
+ from narra import core
75
+
76
+ settings = load_config()
77
+ episode = core.generate("paper.pdf", settings, format="deep-dive")
78
+ ```
79
+
80
+ ## Providers
81
+
82
+ - **Writer** (writes the script): `gemini` (default), `openai-compatible` (BYOK,
83
+ any `/v1/chat/completions`), `ollama` (local).
84
+ - **Voice** (speaks each line): `edge` (free, default), `openai` /
85
+ `openai-compatible` (OpenAI standard `/v1/audio/speech`), `gemini` (native
86
+ TTS), `piper` (local CPU), `kokoro` (local CPU).
87
+
88
+ Keys live in `~/.narra.yaml` (or `${VAR}` references), never in the browser.
89
+
90
+ ## Status
91
+
92
+ **0.0.1 — skeleton.** The package installs, imports, and `narra --version` works;
93
+ providers and `narra generate` are stubbed and raise "not implemented yet". See
94
+ `SPEC.md` for the full design and milestones.
95
+
96
+ ## Privacy
97
+
98
+ No account. No telemetry. The only network egress is the request to the writer
99
+ and voice providers you configure. Piper and Kokoro run locally; Ollama is
100
+ local. Audio saves to `~/Podcasts/Narra` with a JSON sidecar.
101
+
102
+ ## Credits
103
+
104
+ Narra borrows ideas, with acknowledgment, from
105
+ [GroqCasters](https://github.com/jgravelle/GroqCasters) (J. Gravelle, MIT),
106
+ [Open Notebook](https://github.com/lfnovo/open-notebook) (MIT), and the author's
107
+ own [limn](https://github.com/michael-borck/limn),
108
+ [canturía](https://github.com/michael-borck/canturia), and
109
+ [talk-buddy](https://github.com/michael-borck/talk-buddy).
110
+
111
+ ## Licence
112
+
113
+ MIT © Michael Borck.
narra-0.0.1/README.md ADDED
@@ -0,0 +1,69 @@
1
+ # Narra — tell it into a podcast
2
+
3
+ > *narra (Spanish): "tell!" / "narrate!"*
4
+
5
+ A small, privacy-first tool that turns a source document into a two (or more)
6
+ speaker podcast episode. Give it a PDF or text file, pick a format, choose who
7
+ writes the script and which voices speak it, and get an MP3. No account, no
8
+ telemetry, bring your own providers.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ pip install "narra[edge,audio]" # core + free edge-tts voice + pydub
14
+ export GEMINI_API_KEY=... # default writer
15
+ ```
16
+
17
+ ## Use
18
+
19
+ ```bash
20
+ narra "paper.pdf" --format deep-dive --out episode.mp3
21
+ narra "notes.txt" --format brief --voice edge
22
+ narra init-config # write an example narra.yaml
23
+ narra serve # local web UI (pip install "narra[serve]")
24
+ ```
25
+
26
+ Or as a library:
27
+
28
+ ```python
29
+ from narra.config import load_config
30
+ from narra import core
31
+
32
+ settings = load_config()
33
+ episode = core.generate("paper.pdf", settings, format="deep-dive")
34
+ ```
35
+
36
+ ## Providers
37
+
38
+ - **Writer** (writes the script): `gemini` (default), `openai-compatible` (BYOK,
39
+ any `/v1/chat/completions`), `ollama` (local).
40
+ - **Voice** (speaks each line): `edge` (free, default), `openai` /
41
+ `openai-compatible` (OpenAI standard `/v1/audio/speech`), `gemini` (native
42
+ TTS), `piper` (local CPU), `kokoro` (local CPU).
43
+
44
+ Keys live in `~/.narra.yaml` (or `${VAR}` references), never in the browser.
45
+
46
+ ## Status
47
+
48
+ **0.0.1 — skeleton.** The package installs, imports, and `narra --version` works;
49
+ providers and `narra generate` are stubbed and raise "not implemented yet". See
50
+ `SPEC.md` for the full design and milestones.
51
+
52
+ ## Privacy
53
+
54
+ No account. No telemetry. The only network egress is the request to the writer
55
+ and voice providers you configure. Piper and Kokoro run locally; Ollama is
56
+ local. Audio saves to `~/Podcasts/Narra` with a JSON sidecar.
57
+
58
+ ## Credits
59
+
60
+ Narra borrows ideas, with acknowledgment, from
61
+ [GroqCasters](https://github.com/jgravelle/GroqCasters) (J. Gravelle, MIT),
62
+ [Open Notebook](https://github.com/lfnovo/open-notebook) (MIT), and the author's
63
+ own [limn](https://github.com/michael-borck/limn),
64
+ [canturía](https://github.com/michael-borck/canturia), and
65
+ [talk-buddy](https://github.com/michael-borck/talk-buddy).
66
+
67
+ ## Licence
68
+
69
+ MIT © Michael Borck.
narra-0.0.1/SPEC.md ADDED
@@ -0,0 +1,301 @@
1
+ # Narra — specification
2
+
3
+ > *narra (Spanish): "tell!" / "narrate!" — the second-person command to tell a story.*
4
+
5
+ A small, privacy-first tool that turns a source document into a two (or more)
6
+ speaker podcast episode. Give it a PDF or text file, pick a format, choose who
7
+ writes the script and which voices speak it, and get an MP3. No account, no
8
+ telemetry, bring your own providers.
9
+
10
+ ---
11
+
12
+ ## 1. Vision
13
+
14
+ Most "NotebookLM-style" audio tools are a single locked-in web service (an
15
+ account, your documents on their servers) or a heavy research platform
16
+ (notebooks, embeddings, chat, Docker). **Narra sits deliberately in between:**
17
+ the simplest possible "source → podcast episode" surface that you own.
18
+
19
+ - **Give it a source → get an episode.** That's the whole interaction.
20
+ - **No account, no lock-in, privacy by default.** Your documents and audio are
21
+ yours. On the desktop nothing leaves your machine except the request to the
22
+ writer and voice providers *you* configure.
23
+ - **Bring your own providers.** A *writer* (an LLM that turns source text into a
24
+ script) and a *voice* (text-to-speech), each configured independently. Use a
25
+ cloud key, an OpenAI-compatible endpoint, or a local CPU model.
26
+ - **Minimal by design.** Format, speakers, and one Generate button. Advanced
27
+ knobs live in the providers and the config, not in the main flow.
28
+
29
+ ## 2. Principles
30
+
31
+ 1. **Simple beats powerful.** One source in, one episode out. Advanced options
32
+ stay in config.
33
+ 2. **Local-first & private.** No account, no telemetry, no server-side storage
34
+ of sources or audio. The web UI keeps its session gallery in memory; nothing
35
+ is written to disk unless you press Save.
36
+ 3. **Provider-shaped, not provider-locked.** The core does not depend on any one
37
+ writer or voice. Writers and voices are thin modules behind one interface.
38
+ 4. **Progressive surfaces.** The same core powers a CLI, a web UI, and a desktop
39
+ app. Each is optional.
40
+ 5. **Fail visibly.** A provider error stops the run with a clear message; no
41
+ silent fallback to a different provider.
42
+
43
+ ## 3. Surfaces
44
+
45
+ ### v1 — CLI
46
+
47
+ ```bash
48
+ narra "paper.pdf" --format deep-dive --out episode.mp3
49
+ narra "notes.txt" --format brief --writer openai-compatible --voice edge
50
+ narra init-config # write an example narra.yaml
51
+ narra compare "paper.pdf" --voice edge --voice gemini # A/B two voices
52
+ narra serve # local web UI
53
+ ```
54
+
55
+ Options: `--format`, `--writer`, `--voice`, `--speakers`, `--out`, `--out-dir`,
56
+ `--config`, `--base-url`, `--api-key`, `--model`, `--voice-model`, `--timeout`.
57
+
58
+ ### v2 — Web UI (`narra serve`)
59
+
60
+ A single page (FastAPI + a self-contained HTML page, no CDNs):
61
+
62
+ - A **source** box (paste text or pick a file).
63
+ - A **format** selector: your shipped presets as chips, plus a custom briefing.
64
+ - A **speaker strip**: 1–N speakers, each with a name, a persona, and a voice
65
+ picked from any configured voice provider.
66
+ - **Generate** → a pending card (writing script, then voicing lines) → an audio
67
+ card with a player.
68
+ - **Preview script** before committing audio: edit the lines, then **Speak
69
+ this script**.
70
+ - In-memory session gallery (capped) with **Save / Download / Again / Delete**.
71
+ - A **Help** sheet: what each format does, where the script comes from, BYOK,
72
+ local voices, and where files are saved.
73
+
74
+ Binds `127.0.0.1` by default; an optional shared password gates hosted
75
+ instances. Keys live in config, never in the browser.
76
+
77
+ ### v3 — Desktop (Tauri v2 + Python sidecar)
78
+
79
+ A native, installable app. Tauri v2 uses the OS webview. On first launch it
80
+ bootstraps a private runtime with `uv`, creates a venv in the app-data
81
+ directory, installs `narra[serve]==<pin>`, runs `narra serve` on a random
82
+ localhost port, and shows the served UI. A Settings sheet reads/writes
83
+ `~/.narra.yaml` (merge-preserving, chmod 600) — the same file the CLI uses.
84
+ Saves land in `~/Podcasts/Narra`. Distributed as a signed installer; not on the
85
+ Mac App Store (runtime-download rules).
86
+
87
+ ### Demo — "try before install" (later)
88
+
89
+ A hosted instance that is rate-limited and non-storing: generate a couple of
90
+ episodes, nothing saved server-side, with a banner inviting users to install
91
+ locally for full control and privacy.
92
+
93
+ ## 4. The pipeline
94
+
95
+ ```
96
+ source (pdf/txt)
97
+ │ read_source()
98
+ ▼
99
+ writer (LLM) ──► script: [DialogueLine] (outline → expand → dialogue)
100
+ │
101
+ ▼
102
+ speakers: each line assigned a speaker → a voice from a voice provider
103
+ │
104
+ ▼
105
+ voices (TTS) ──► per-line audio ──► concatenate (pauses) ──► episode.mp3
106
+ │
107
+ ▼
108
+ save + <episode>.json sidecar
109
+ ```
110
+
111
+ ### Formats (writer styles)
112
+
113
+ `formats.py` is a registry mapping a format key to a prompt fragment. Shipped:
114
+
115
+ | Key | Shape |
116
+ |---|---|
117
+ | `deep-dive` | 18–24 lines, two hosts (Alex storyteller, Sam skeptic) |
118
+ | `brief` | 6–8 short lines, single host (Alex), under 90 s |
119
+ | `critique` | 16–20 lines, candid domain reviewers (Alex + Sam) |
120
+ | `debate` | 18–22 lines, optimistic pro vs tough skeptic |
121
+
122
+ A format may also be a **custom briefing** (free text) for open-notebook-style
123
+ "episode profiles". Writer rules are appended to every format: cold open (no
124
+ "welcome back"), cite concrete facts, avoid AI clichés, no stage directions.
125
+
126
+ ### Writers (write the script)
127
+
128
+ | Name | What | Auth |
129
+ |---|---|---|
130
+ | `gemini` | Google Gemini (`google-genai`), default `gemini-3.5-flash` | `GEMINI_API_KEY` |
131
+ | `openai-compatible` | Any `/v1/chat/completions`: OpenAI, LM Studio, llama.cpp, OpenRouter | Bearer key (optional locally) |
132
+ | `ollama` | Local Ollama chat model | none |
133
+
134
+ The writer receives the source text plus the format and returns structured
135
+ `[DialogueLine]`. Gemini uses a typed schema; the OpenAI-compatible writer asks
136
+ for JSON and validates.
137
+
138
+ ### Voices (speak each line)
139
+
140
+ `tts/` exposes one interface, `synthesize(text, voice, opts) -> audio bytes`.
141
+ Shipped:
142
+
143
+ | Name | What | Auth / notes |
144
+ |---|---|---|
145
+ | `edge` | edge-tts neural voices, free | none (default) |
146
+ | `openai` / `openai-compatible` | OpenAI standard `POST {base}/audio/speech` (`model`, `input`, `voice`, `response_format`, `speed`) | Bearer key (optional for local Speaches/LocalAI) |
147
+ | `gemini` | Gemini native TTS (single- or multi-speaker), 24 kHz PCM | `GEMINI_API_KEY` |
148
+ | `piper` | Local CPU, tiny ONNX voices, ~0.05× realtime | sha256-verified first-run download |
149
+ | `kokoro` | Local CPU via `kokoro-onnx` (~120 MB), or a Speaches server | local or server URL |
150
+
151
+ Two concatenation strategies must be supported: **per-line** (edge, piper,
152
+ kokoro, openai-compatible — synthesize each line, stitch with 180–420 ms pauses)
153
+ and **single-call** (gemini native multi-speaker — one request returns the whole
154
+ dialogue).
155
+
156
+ ### Speakers
157
+
158
+ A `Speaker` has a `name`, an optional `persona` (fed to the writer), and a
159
+ `voice` reference `{provider, voice_id, model}`. Two defaults ship: **Alex**
160
+ (male) and **Sam** (female). A format that is single-host uses Alex only. The
161
+ web UI and config can define 1–N speakers; each may point at a *different* voice
162
+ provider (open-notebook's per-speaker override).
163
+
164
+ ## 5. Config
165
+
166
+ Layered, later wins (mirrors limn/canturía):
167
+
168
+ 1. Built-in defaults.
169
+ 2. `~/.narra.yaml` — your providers + keys, set once.
170
+ 3. `./narra.yaml` (or `--config FILE`).
171
+ 4. CLI flags / environment.
172
+
173
+ ```yaml
174
+ writer: gemini # gemini | openai-compatible | ollama
175
+ voice: edge # edge | openai-compatible | gemini | piper | kokoro
176
+ format: deep-dive
177
+
178
+ writers:
179
+ gemini:
180
+ model: gemini-3.5-flash
181
+ api_key: "${GEMINI_API_KEY}"
182
+ openai-compatible:
183
+ base_url: https://api.openai.com/v1
184
+ model: gpt-4o-mini
185
+ api_key: "${OPENAI_API_KEY}"
186
+ ollama:
187
+ base_url: http://127.0.0.1:11434
188
+ model: qwen3.5:4b
189
+
190
+ voices:
191
+ edge: {}
192
+ openai-compatible:
193
+ base_url: https://api.openai.com/v1
194
+ model: gpt-4o-mini-tts
195
+ api_key: "${OPENAI_API_KEY}"
196
+ gemini:
197
+ model: gemini-3.8-flash-tts
198
+ api_key: "${GEMINI_API_KEY}"
199
+ piper:
200
+ voice: en_GB-alan-low
201
+ kokoro:
202
+ voice: bm_george
203
+
204
+ speakers:
205
+ - name: Alex
206
+ persona: Storyteller who sees the big picture.
207
+ voice: { provider: edge, voice_id: en-US-AndrewNeural }
208
+ - name: Sam
209
+ persona: Curious skeptic who asks sharp follow-ups.
210
+ voice: { provider: edge, voice_id: en-US-AvaNeural }
211
+
212
+ serve:
213
+ host: 127.0.0.1
214
+ port: 5372
215
+ password: "${NARRA_SERVE_PASSWORD}"
216
+ out_dir: ~/Podcasts/Narra
217
+ ```
218
+
219
+ Secrets are referenced as `${VAR}` so no plaintext keys live in files. Default
220
+ serve port **5372** ("NARR" on a phone keypad).
221
+
222
+ ## 6. Architecture
223
+
224
+ ```
225
+ narra/
226
+ config.py layered config + ${VAR} expansion
227
+ formats.py format registry + writer rules
228
+ speakers.py Speaker dataclass, defaults, voice refs
229
+ writers/
230
+ base.py Writer ABC, ScriptRequest/ScriptResult
231
+ gemini.py openai_compatible.py ollama.py
232
+ tts/
233
+ base.py VoiceProvider ABC, SpeakRequest
234
+ edge.py openai_compat.py gemini.py piper.py kokoro.py
235
+ script.py read_source(), outline→dialogue, text cleanup
236
+ core.py generate(): script → per-line audio → episode + sidecar
237
+ cli.py Typer CLI
238
+ serve.py FastAPI app factory [serve extra]
239
+ serve_page.html self-contained web UI (package data)
240
+ desktop/ Tauri v2 shell + uv-bootstrapped sidecar
241
+ tests/
242
+ ```
243
+
244
+ - **Python 3.10+**, `typer`, `rich`, `requests`, `pyyaml`, `pydantic`.
245
+ - **Extras:** `audio=[pydub]`, `edge=[edge-tts]`, `gemini=[google-genai]`,
246
+ `local=[piper-tts, kokoro-onnx, numpy]`, `serve=[fastapi, uvicorn]`.
247
+ - **Packaging:** hatchling; `pip install narra`, publish to PyPI.
248
+
249
+ ## 7. Privacy and storage
250
+
251
+ - No account, no telemetry, no logging of sources or scripts.
252
+ - The only egress is the request to the writer and voice providers you
253
+ configure. Piper and Kokoro run locally; Ollama is local.
254
+ - The web session gallery is in memory, capped, and dies with the process.
255
+ - Save writes the audio plus a `<episode>.json` sidecar (writer, voice,
256
+ format, source hash, settings) into `~/Podcasts/Narra` (configurable). Save
257
+ never overwrites.
258
+ - Keys are never exposed to the browser.
259
+
260
+ ## 8. Attribution
261
+
262
+ Narra borrows ideas, with acknowledgment, from:
263
+
264
+ - **GroqCasters** by J. Gravelle (MIT) — the outline → expand → dialogue
265
+ pipeline, host personas, and voice cloning from a short sample. © J. Gravelle;
266
+ a mention is retained per the licence.
267
+ - **Open Notebook** by lfnovo and contributors (MIT) — episode profiles,
268
+ per-speaker voice-model overrides, the "what each model sees" privacy framing,
269
+ and background-job retry.
270
+ - The author's own **limn**, **canturía**, and **talk-buddy** — the
271
+ provider/config/serve architecture, the `compare` workflow, and the
272
+ sha256-verified first-run model download for Piper.
273
+
274
+ ## 9. Non-goals
275
+
276
+ - Not a research notebook, chat, or embeddings tool. Narra makes one thing:
277
+ an episode from a source.
278
+ - Not a DAW or audio editor.
279
+ - Not a model host — Narra calls the providers you point it at.
280
+ - No infographic / show-notes card in v1 (a separate tool handles that).
281
+
282
+ ## 10. Milestones
283
+
284
+ 1. **M1 — Core + CLI.** `narra "source" --format ... --out ...`; Gemini writer +
285
+ OpenAI-compatible writer; edge + OpenAI-compatible voices; layered config;
286
+ PyPI publish.
287
+ 2. **M2 — Web UI.** `narra serve` with source box, format chips, speaker strip,
288
+ preview/edit script, session gallery with Save/Download/Again/Delete, password
289
+ gate, Help sheet.
290
+ 3. **M3 — Local + BYOK voices.** Piper + Kokoro (CPU) with sha256 model
291
+ download, Gemini native TTS (single + multi-speaker), per-speaker voice
292
+ override, `narra compare` voices.
293
+ 4. **M4 — Desktop + landing.** Tauri shell, first-run uv runtime, Settings
294
+ sheet, CI installers, demo mode, landing page.
295
+
296
+ ## 11. Skeleton (0.0.1)
297
+
298
+ The first PyPI upload is a frame, not a product: it installs, imports,
299
+ `narra --version` and `narra init-config` work, and every provider plus
300
+ `generate()` raise a clear "not implemented yet" error. This exists so the
301
+ package name, repo, CI, and packaging are proven before M1 fills the modules.