monograph 0.1.0__tar.gz

monograph-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+
+# monograph — never commit anyone's private content or large artifacts
+# (diaries, voices, generated books, model caches)
+*.wav
+*.mp3
+*.m4a
+/out/
+/book/
+/audio/
+/narration_audio/
+my-diary/
+voice.wav
+pronunciation.txt
+*.index
+*.faiss
+.chroma/
+models/
+.cache/

monograph-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: monograph
+Version: 0.1.0
+Summary: Turn a personal diary into a memoir — explore it, find its arcs, draft it, and narrate it in your own voice. Local-first.
+Author: Bonnie Bingham
+License: MIT
+Keywords: diary,memoir,rag,tts,voice-cloning,writing
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Provides-Extra: all
+Requires-Dist: f5-tts>=1.0; extra == 'all'
+Requires-Dist: pandas>=1.5; extra == 'all'
+Requires-Dist: pytest>=7; extra == 'all'
+Requires-Dist: python-docx>=0.8; extra == 'all'
+Requires-Dist: scikit-learn>=1.1; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2; extra == 'all'
+Requires-Dist: soundfile>=0.12; extra == 'all'
+Requires-Dist: streamlit>=1.30; extra == 'all'
+Provides-Extra: app
+Requires-Dist: streamlit>=1.30; extra == 'app'
+Provides-Extra: arc
+Requires-Dist: pandas>=1.5; extra == 'arc'
+Requires-Dist: scikit-learn>=1.1; extra == 'arc'
+Provides-Extra: dev
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: python-docx>=0.8; extra == 'dev'
+Requires-Dist: scikit-learn>=1.1; extra == 'dev'
+Requires-Dist: soundfile>=0.12; extra == 'dev'
+Provides-Extra: index
+Requires-Dist: sentence-transformers>=2.2; extra == 'index'
+Provides-Extra: ingest
+Requires-Dist: python-docx>=0.8; extra == 'ingest'
+Provides-Extra: llm-ollama
+Provides-Extra: llm-openai
+Requires-Dist: openai>=1.0; extra == 'llm-openai'
+Provides-Extra: narrate
+Requires-Dist: soundfile>=0.12; extra == 'narrate'
+Provides-Extra: narrate-f5
+Requires-Dist: f5-tts>=1.0; extra == 'narrate-f5'
+Requires-Dist: soundfile>=0.12; extra == 'narrate-f5'
+Provides-Extra: narrate-xtts
+Requires-Dist: coqui-tts>=0.24; extra == 'narrate-xtts'
+Requires-Dist: soundfile>=0.12; extra == 'narrate-xtts'
+Description-Content-Type: text/markdown
+
+# monograph
+
+Turn a personal diary into a memoir: **explore** it, find its **arcs**, **write**
+it, and **narrate** it in your own voice. Local-first by design.
+
+`monograph` is a pipeline with five stages, each usable on its own:
+
+1. **ingest** — parse a diary (any format) into structured entries.
+2. **index** — build a searchable index and query it (retrieval over your own writing).
+3. **arc** — find scenes, propose narrative spines, and reconstruct a memoir structure.
+4. **write** — draft prose from the chosen spine, in a style you supply.
+5. **narrate** — turn the finished text into audio read in the author's own cloned voice.
+
+A thin `cli` wires the stages together, and an optional `app` gives a GUI.
+
+## Privacy, first
+
+A diary is the most sensitive text someone owns. `monograph` runs **local by
+default** — local parsing, local embeddings, local files, local TTS — and never
+sends your words anywhere unless you explicitly choose a cloud backend and pass a
+key. `Config.local\_only` defaults to `True`, and any backend that would make a
+network call must check it and refuse when it's set. Treat that flag as a
+load-bearing contract, not a suggestion.
+
+## Getting started (step by step)
+
+If you don't write code, follow this once and you'll have a working setup. You need
+**Python 3.10 or newer** installed first (python.org → Downloads; on Windows, tick
+"Add Python to PATH" during install).
+
+**1. Open a terminal.**
+
+* macOS: open the **Terminal** app (Cmd-Space, type "Terminal").
+* Windows: open **PowerShell** (Start menu, type "PowerShell").
+
+**2. Go to the folder that holds monograph.** Use `cd` ("change directory"):
+
+```bash
+cd path/to/monograph          # e.g.  cd Desktop/monograph
+```
+
+Tip: type `cd ` (with a space), then drag the folder onto the terminal window — it
+fills in the path for you.
+
+**3. Create a virtual environment** (a private sandbox for this project's packages),
+and **activate** it:
+
+```bash
+# macOS / Linux
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Windows (PowerShell)
+python -m venv .venv
+.venv\\Scripts\\Activate.ps1
+```
+
+When it's active you'll see `(.venv)` at the start of the line. Do this (step 3,
+activate) every time you open a new terminal to work on the project.
+
+**4. Install monograph** and the pieces you want:
+
+```bash
+pip install -e ".\[app,arc,index]"      # GUI + arc engine + local search
+pip install -e ".\[narrate-f5]"         # add the F5 narrator (big download)
+pip install -e ".\[all]"                # everything at once
+```
+
+Narration and model backends are heavy and optional — install only what you'll use.
+
+**5. Launch the app:**
+
+```bash
+monograph app
+```
+
+That opens the GUI in your web browser. Close it with Ctrl-C in the terminal.
+
+## Using it from the command line
+
+You can also drive each stage directly (handy for long narration runs):
+
+```bash
+monograph prepare-voice --src recording.m4a --out voice.wav
+monograph narrate --text chapters/ --out audio/ --voice voice.wav --ref-text "I am recording my voice ..."
+```
+
+## Using it from Python
+
+```python
+from monograph import Config
+from monograph.narrate import get\_narrator
+
+cfg = Config(voice\_ref="voice.wav", voice\_ref\_text="I am recording my voice ...")
+get\_narrator("f5", cfg).narrate\_dir("chapters/", "audio/")   # one wav per .txt, resumable
+```
+
+## File names: how the stages connect
+
+You never have to rename your diary to match the code — every path is an argument
+(the original scripts hardcoded names like `journal\_all.docx`; this doesn't). Two
+things matter:
+
+* **Your diary** can have any name and live anywhere. Point `--diary` (or the app's
+sidebar, or `Config.diary\_path`) at it — `.docx`, `.txt`/`.md`, `.json`, `.csv`,
+`.pkl`, or a folder of them.
+* **The index** is saved under a base name you choose with `--out` (default
+`diary\_index`); building it writes `<base>.npy` and `<base>.meta.json`. Every stage
+that *reads* the index — `search`, `write`, and `app` — takes that same base name
+via `--index` (the app via its sidebar or the `MONOGRAPH\_INDEX` env var). The one
+rule: **use the same base name to build and to read.**
+
+A consistent run:
+
+```bash
+monograph index  --diary my\_journal.docx --out diary\_index
+monograph scenes --diary my\_journal.docx
+monograph search --index diary\_index "feeling alone"
+monograph write  --index diary\_index "breaking the cycle"
+monograph app                      # reads diary\_index by default
+```
+
+Change `diary\_index` everywhere together if you want a different name — nothing is
+hardcoded, and no file needs renaming. (Age labels in the app are optional: add a
+`monograph.toml` with a `\[people]` table of `Name = "YYYY-MM-DD"` birthdates.)
+
+## Package layout
+
+```
+monograph/
+  config.py        Config + privacy defaults
+  types.py         shared dataclasses (DiaryEntry, Scene, Spine, Chapter, ...)
+  ingest/          parse diaries -> entries
+  index/           build + search (pluggable: base.Index, local.LocalIndex)
+  arc/             scenes, spine, recon  (the memoir-structure engine)
+  write/           memoir engine + style profiles
+  narrate/         Narrator backends (F5, XTTS) + chapterize + pronunciation + voice prep
+  llm/             LLM interface (pluggable; local or cloud, opt-in)
+  cli.py           thin command line
+  app.py           optional Streamlit front-end
+```
+
+Each backend sits behind a small interface (`index.Index`, `llm.LLM`,
+`narrate.Narrator`) so anyone can swap in their own without touching the core.
+
+## Status
+
+All five stages are implemented and tested — `ingest`, `index`, `arc`, `write`,
+`narrate` — so the full chain runs end to end: parse the diary, build the index,
+run recon / scene / spine analysis, draft the memoir, and narrate it in the
+author's voice. The `write` stage drafts a passage from a theme or date range, and
+`write\_memoir()` assembles one chapter per aspect a chosen spine draws on; treat
+that assembly as a sensible default to reorder or merge to taste.
+

monograph-0.1.0/README.md

@@ -0,0 +1,154 @@
+# monograph
+
+Turn a personal diary into a memoir: **explore** it, find its **arcs**, **write**
+it, and **narrate** it in your own voice. Local-first by design.
+
+`monograph` is a pipeline with five stages, each usable on its own:
+
+1. **ingest** — parse a diary (any format) into structured entries.
+2. **index** — build a searchable index and query it (retrieval over your own writing).
+3. **arc** — find scenes, propose narrative spines, and reconstruct a memoir structure.
+4. **write** — draft prose from the chosen spine, in a style you supply.
+5. **narrate** — turn the finished text into audio read in the author's own cloned voice.
+
+A thin `cli` wires the stages together, and an optional `app` gives a GUI.
+
+## Privacy, first
+
+A diary is the most sensitive text someone owns. `monograph` runs **local by
+default** — local parsing, local embeddings, local files, local TTS — and never
+sends your words anywhere unless you explicitly choose a cloud backend and pass a
+key. `Config.local\_only` defaults to `True`, and any backend that would make a
+network call must check it and refuse when it's set. Treat that flag as a
+load-bearing contract, not a suggestion.
+
+## Getting started (step by step)
+
+If you don't write code, follow this once and you'll have a working setup. You need
+**Python 3.10 or newer** installed first (python.org → Downloads; on Windows, tick
+"Add Python to PATH" during install).
+
+**1. Open a terminal.**
+
+* macOS: open the **Terminal** app (Cmd-Space, type "Terminal").
+* Windows: open **PowerShell** (Start menu, type "PowerShell").
+
+**2. Go to the folder that holds monograph.** Use `cd` ("change directory"):
+
+```bash
+cd path/to/monograph          # e.g.  cd Desktop/monograph
+```
+
+Tip: type `cd ` (with a space), then drag the folder onto the terminal window — it
+fills in the path for you.
+
+**3. Create a virtual environment** (a private sandbox for this project's packages),
+and **activate** it:
+
+```bash
+# macOS / Linux
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Windows (PowerShell)
+python -m venv .venv
+.venv\\Scripts\\Activate.ps1
+```
+
+When it's active you'll see `(.venv)` at the start of the line. Do this (step 3,
+activate) every time you open a new terminal to work on the project.
+
+**4. Install monograph** and the pieces you want:
+
+```bash
+pip install -e ".\[app,arc,index]"      # GUI + arc engine + local search
+pip install -e ".\[narrate-f5]"         # add the F5 narrator (big download)
+pip install -e ".\[all]"                # everything at once
+```
+
+Narration and model backends are heavy and optional — install only what you'll use.
+
+**5. Launch the app:**
+
+```bash
+monograph app
+```
+
+That opens the GUI in your web browser. Close it with Ctrl-C in the terminal.
+
+## Using it from the command line
+
+You can also drive each stage directly (handy for long narration runs):
+
+```bash
+monograph prepare-voice --src recording.m4a --out voice.wav
+monograph narrate --text chapters/ --out audio/ --voice voice.wav --ref-text "I am recording my voice ..."
+```
+
+## Using it from Python
+
+```python
+from monograph import Config
+from monograph.narrate import get\_narrator
+
+cfg = Config(voice\_ref="voice.wav", voice\_ref\_text="I am recording my voice ...")
+get\_narrator("f5", cfg).narrate\_dir("chapters/", "audio/")   # one wav per .txt, resumable
+```
+
+## File names: how the stages connect
+
+You never have to rename your diary to match the code — every path is an argument
+(the original scripts hardcoded names like `journal\_all.docx`; this doesn't). Two
+things matter:
+
+* **Your diary** can have any name and live anywhere. Point `--diary` (or the app's
+sidebar, or `Config.diary\_path`) at it — `.docx`, `.txt`/`.md`, `.json`, `.csv`,
+`.pkl`, or a folder of them.
+* **The index** is saved under a base name you choose with `--out` (default
+`diary\_index`); building it writes `<base>.npy` and `<base>.meta.json`. Every stage
+that *reads* the index — `search`, `write`, and `app` — takes that same base name
+via `--index` (the app via its sidebar or the `MONOGRAPH\_INDEX` env var). The one
+rule: **use the same base name to build and to read.**
+
+A consistent run:
+
+```bash
+monograph index  --diary my\_journal.docx --out diary\_index
+monograph scenes --diary my\_journal.docx
+monograph search --index diary\_index "feeling alone"
+monograph write  --index diary\_index "breaking the cycle"
+monograph app                      # reads diary\_index by default
+```
+
+Change `diary\_index` everywhere together if you want a different name — nothing is
+hardcoded, and no file needs renaming. (Age labels in the app are optional: add a
+`monograph.toml` with a `\[people]` table of `Name = "YYYY-MM-DD"` birthdates.)
+
+## Package layout
+
+```
+monograph/
+  config.py        Config + privacy defaults
+  types.py         shared dataclasses (DiaryEntry, Scene, Spine, Chapter, ...)
+  ingest/          parse diaries -> entries
+  index/           build + search (pluggable: base.Index, local.LocalIndex)
+  arc/             scenes, spine, recon  (the memoir-structure engine)
+  write/           memoir engine + style profiles
+  narrate/         Narrator backends (F5, XTTS) + chapterize + pronunciation + voice prep
+  llm/             LLM interface (pluggable; local or cloud, opt-in)
+  cli.py           thin command line
+  app.py           optional Streamlit front-end
+```
+
+Each backend sits behind a small interface (`index.Index`, `llm.LLM`,
+`narrate.Narrator`) so anyone can swap in their own without touching the core.
+
+## Status
+
+All five stages are implemented and tested — `ingest`, `index`, `arc`, `write`,
+`narrate` — so the full chain runs end to end: parse the diary, build the index,
+run recon / scene / spine analysis, draft the memoir, and narrate it in the
+author's voice. The `write` stage drafts a passage from a theme or date range, and
+`write\_memoir()` assembles one chapter per aspect a chosen spine draws on; treat
+that assembly as a sensible default to reorder or merge to taste.
+

monograph-0.1.0/examples/lenses_parenting.py

@@ -0,0 +1,65 @@
+"""A worked, domain-specific Lenses config — an intergenerational *parenting*
+memoir (present: parenting your own kids; past: how you were parented).
+
+This is the kind of thing that used to be hardcoded at the top of memoir_recon.py
+and spine_proposer.py. It lives here as an *example of customization*, not in the
+library: swap the seeds and aspects for whatever your memoir is about.
+
+    from examples.lenses_parenting import LENSES
+    report = recon_report(entries, embed, lenses=LENSES)
+"""
+from datetime import date
+from monograph.types import Lenses, StyleProfile
+
+# Age context for the write stage (name -> birthdate). Pass as people= to
+# MemoirEngine so a child's age at each entry's date is always right.
+PEOPLE = {
+    "Cash":    date(2007, 1, 10),
+    "Camille": date(2008, 1, 31),
+    "Ruby":    date(2010, 4, 15),
+}
+
+# Sample the author's voice from older entries, where it's truest.
+VOICE_WINDOW = ("2018-01-01", "2021-12-31")
+
+# The voice characterization that used to be hardcoded in memoir.py — now a
+# StyleProfile the engine drops into its prompt.
+STYLE = StyleProfile(
+    name="author",
+    notes=("Her voice is dry and sarcastic, with dark humor. She makes light of hard "
+           "things and deflects pain with wit — MATCH that voice; the sarcasm and humor "
+           "are essential to sounding like her."),
+)
+
+
+LENSES = Lenses(
+    aspects={
+        "pride":       "pride in my child, so proud of them, celebrating who they are",
+        "cycle":       "the parent I want to be, breaking the cycle, not repeating how I "
+                       "was raised, doing it differently than my own parents did",
+        "repair":      "repairing things with my child after I got it wrong, apologizing "
+                       "to my kid, reconnecting after a rupture with them",
+        "temper":      "losing my temper, yelling at my kids, snapping, and the guilt after",
+        "overwhelm":   "exhausted, depleted, no patience left, burned out, stretched too thin",
+        "worry":       "worried and afraid for my child, scared something is wrong",
+        "affection":   "a tender, close moment with my child, warmth, holding them",
+        "discipline":  "setting a limit, a consequence, correcting behavior",
+        "letting_go":  "my child growing up, becoming independent, learning to let them go",
+        "faith":       "my faith, God, church, prayer, what I believe and how it steadies me",
+    },
+    emo_pos=["joy and happiness", "love and tenderness", "pride", "gratitude", "calm and peace"],
+    emo_neg=["anger and frustration", "fear, anxiety and worry", "sadness and grief",
+             "guilt and shame", "exhaustion and being overwhelmed"],
+    strands={
+        "present": ["parenting my children", "being a mom to my kids", "raising my children",
+                    "disciplining my child", "comforting my child when upset",
+                    "bedtime with the kids", "losing my patience with my kids",
+                    "apologizing to my child", "being proud of my kid",
+                    "worrying about my child", "being a single parent"],
+        "past": ["how I was parented", "the way I was raised", "when I was a child",
+                 "growing up", "my mother", "my father", "my parents", "my childhood",
+                 "how my parents treated me", "my own upbringing"],
+    },
+    name_stop=Lenses.default().name_stop | {"Mom", "Dad", "Happy", "Christmas",
+                                            "Thanksgiving", "Easter", "New", "Year"},
+)

monograph-0.1.0/examples/run_pipeline.py

@@ -0,0 +1,48 @@
+"""End-to-end sketch: diary -> memoir -> audio in the author's voice.
+
+The `arc` and `narrate` stages are implemented; `ingest`/`index`/`write` run once
+you've ported your own logic into their stubs. This file *uses* the library — it's
+the general version of your project-specific driver scripts.
+"""
+from monograph import Config
+from monograph.narrate import get_narrator
+
+
+def narrate_only():
+    """Works today: a folder of chapter .txt -> one .wav each, resumable."""
+    cfg = Config(
+        voice_ref="voice.wav",
+        voice_ref_text="I am recording my voice so I can read my own book aloud, "
+                       "in a calm and natural tone, the way I would read a story to someone I love.",
+        narrate_backend="f5",
+        cross_fade=0.30,
+    )
+    get_narrator(cfg.narrate_backend, cfg).narrate_dir("chapters/", "audio/")
+
+
+def find_the_arc():
+    """Works today (needs the `arc` + `index` extras and a local LLM via Ollama).
+    Turns parsed entries into a recon report and candidate spines."""
+    from monograph.ingest import parse_diary
+    from monograph.index import get_embedder
+    from monograph.arc import recon_report, build_evidence, propose_spines
+    from monograph.llm import get_llm
+    from monograph.types import Lenses
+
+    # Bring your own lenses; see examples/lenses_parenting.py, or Lenses.default().
+    lenses = Lenses.default()
+
+    entries = parse_diary("./my-diary")          # once ingest is ported
+    embed = get_embedder("local")
+
+    open("recon_report.md", "w").write(recon_report(entries, embed, lenses=lenses))
+
+    cfg = Config(llm_backend="ollama", options={"llm_model": "llama3.1:8b"})
+    evidence = build_evidence(entries, embed, lenses=lenses)
+    spines = propose_spines(evidence, get_llm(cfg.llm_backend, cfg))
+    for s in spines:
+        print(s.title, "—", s.premise)
+
+
+if __name__ == "__main__":
+    narrate_only()

monograph-0.1.0/examples/sample_diary/2019-06-02.md

@@ -0,0 +1,5 @@
+# June 2, 2019
+
+Synthetic sample entry (safe to commit — not anyone's real diary). Rain all day.
+Started the garden boxes anyway and got soaked. Felt good to build something with
+my hands for once instead of staring at a screen.

monograph-0.1.0/examples/sample_diary/2019-06-09.md

@@ -0,0 +1,4 @@
+# June 9, 2019
+
+Synthetic sample entry. The seedlings came up. Small thing, but I keep going back
+to the window to look at them. A week ago it was just dirt and a stubborn idea.

monograph-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "monograph"
+version = "0.1.0"
+description = "Turn a personal diary into a memoir — explore it, find its arcs, draft it, and narrate it in your own voice. Local-first."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Bonnie Bingham" }]
+keywords = ["diary", "memoir", "writing", "tts", "voice-cloning", "rag"]
+
+# Core stays tiny and dependency-light. Heavy pieces are opt-in extras so the
+# library installs small and runs local-first; a user only pulls the backend
+# they actually use.
+dependencies = [
+    "numpy>=1.23",
+]
+
+[project.optional-dependencies]
+ingest = ["python-docx>=0.8"]                                 # read .docx diaries
+index = ["sentence-transformers>=2.2"]                        # local embeddings (store is numpy; no faiss)
+arc = ["pandas>=1.5", "scikit-learn>=1.1"]                    # signal extraction + clustering
+narrate = ["soundfile>=0.12"]                                 # shared audio I/O
+narrate-f5 = ["monograph[narrate]", "f5-tts>=1.0"]
+narrate-xtts = ["monograph[narrate]", "coqui-tts>=0.24"]
+llm-ollama = []                                               # local LLM via stdlib HTTP (just run Ollama)
+llm-openai = ["openai>=1.0"]
+app = ["streamlit>=1.30"]
+dev = ["pytest>=7", "soundfile>=0.12", "pandas>=1.5", "scikit-learn>=1.1", "python-docx>=0.8"]
+all = ["monograph[ingest,index,arc,narrate-f5,app,dev]"]
+
+[project.scripts]
+monograph = "monograph.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/monograph"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

monograph-0.1.0/src/monograph/__init__.py

@@ -0,0 +1,11 @@
+"""monograph — diary -> memoir -> narrated audio, local-first.
+
+Only light things are imported at top level so `import monograph` stays cheap and
+free of heavy optional dependencies. Pull backends from their submodules
+(`monograph.narrate`, `monograph.index`, ...) when you need them.
+"""
+from .config import Config
+from . import types
+
+__version__ = "0.1.0"
+__all__ = ["Config", "types", "__version__"]

monograph-0.1.0/src/monograph/app.py

@@ -0,0 +1,113 @@
+"""Diary Companion — a local, private Streamlit app for exploring a journal:
+find forgotten entries, follow a thread across the years, see your story freshly.
+Ported from diary_app.py. Retrieval goes through monograph's LocalIndex (no faiss
+/ pickle), and the family age context is optional config, not hardcoded.
+
+Launch it with:   monograph app
+
+It reads an index built by `monograph index` (default base name "diary_index").
+Age labels appear if a monograph.toml with a [people] table sits in the folder:
+
+    [people]
+    Cash = "2007-01-10"
+    Camille = "2008-01-31"
+"""
+from __future__ import annotations
+import os
+from datetime import date
+from pathlib import Path
+
+import streamlit as st
+
+
+@st.cache_resource
+def _load_index(base: str):
+    from monograph.index.local import LocalIndex
+    return LocalIndex.load(base)
+
+
+def _load_people() -> dict:
+    try:
+        import tomllib
+        p = Path("monograph.toml")
+        if p.exists():
+            data = tomllib.loads(p.read_text(encoding="utf-8"))
+            return {k: date.fromisoformat(v) for k, v in data.get("people", {}).items()}
+    except Exception:
+        pass
+    return {}
+
+
+def _age_at(birth: date, d: date) -> int:
+    return d.year - birth.year - ((d.month, d.day) < (birth.month, birth.day))
+
+
+def run():
+    st.set_page_config(page_title="Diary Companion", page_icon="📖", layout="wide")
+    st.title("📖 Diary Companion")
+    st.caption("A private, local space to find, revisit, and reflect on your own "
+               "entries. Nothing leaves this machine.")
+
+    base = st.sidebar.text_input("Index path",
+                                 value=os.environ.get("MONOGRAPH_INDEX", "diary_index"))
+    try:
+        idx = _load_index(base)
+    except Exception as e:
+        st.error(f"Couldn't load an index at '{base}'. Build one first:\n\n"
+                 f"`monograph index --diary <your diary> --out {base}`\n\n({e})")
+        st.stop()
+
+    people = _load_people()
+    dated = [e for e in idx.entries if e.entry_date]
+    span = (f"{min(e.entry_date for e in dated)} → {max(e.entry_date for e in dated)}"
+            if dated else "no dates")
+    st.sidebar.success(f"{len(idx.entries)} entries loaded ({span})")
+
+    st.sidebar.header("Find a thread")
+    theme = st.sidebar.text_input("Search by theme or feeling",
+                                  placeholder="e.g. a recovery, feeling alone, hope")
+    k = st.sidebar.slider("How many entries to surface", 5, 100, 30, step=5)
+    min_score = st.sidebar.slider("Relevance threshold", 0.0, 0.6, 0.20, step=0.02,
+                                  help="Higher = only stronger matches.")
+    order = st.sidebar.radio("Show in order of", ["Chronological", "Relevance"])
+
+    if not theme:
+        st.info("Enter a theme or feeling in the sidebar to surface related entries "
+                "from across your journal, shown with their dates so you can follow "
+                "how a thread developed over time.")
+        st.stop()
+
+    hits = [(e, s) for e, s in idx.search(theme, k=k) if s >= min_score]
+    if not hits:
+        st.warning("No entries matched. Lower the relevance threshold or rephrase.")
+        st.stop()
+
+    if order == "Chronological":
+        hits.sort(key=lambda es: es[0].entry_date or date.min)
+    else:
+        hits.sort(key=lambda es: es[1], reverse=True)
+
+    st.subheader(f"{len(hits)} entries related to “{theme}”")
+    years = [e.entry_date.year for e, _ in hits if e.entry_date]
+    if years:
+        counts = {y: years.count(y) for y in range(min(years), max(years) + 1)}
+        st.caption("When these entries fall (a first glimpse of the pattern):")
+        st.bar_chart({"entries": counts})
+    st.divider()
+
+    for e, score in hits:
+        d = e.entry_date
+        weekday = e.meta.get("weekday") or (d.strftime("%A") if d else "")
+        cols = st.columns([3, 1])
+        cols[0].markdown(f"**{d or '?'} · {weekday}**")
+        if people and d:
+            ages = " · ".join(f"{n} {_age_at(b, d)}" for n, b in people.items())
+            cols[1].markdown(f"<div style='text-align:right;color:gray;font-size:0.8em'>"
+                             f"{ages}</div>", unsafe_allow_html=True)
+        st.write(e.text)
+        st.caption(f"relevance {score:.2f}")
+        st.divider()
+
+
+if __name__ == "__main__":
+    run()