poddrill 0.2.1 → 0.3.0

package/.agents/skills/poddrill/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # PodDrill
 
-PodDrill maps an episode (the audio) to cues, clusters those cues into speaker groups, and stores summaries. You decide how to use the toolset to answer the user's request. You read the text, name the voices, and write the summary words. PodDrill stores the episode.
+PodDrill maps an episode (the audio) to cues, clusters those cues into speaker groups, and stores summaries. You name the voices and you write the summary words. PodDrill stores the episode. When the user wants that episode handled, follow the order below. Do not skip a step.
 
 Install once, with the sequence below. After that, read the one guide for the part you are doing. Leave the other guides unread. If an episode already has the asset you need, read it.
 
@@ -19,15 +19,15 @@ Do this once on the computer that will transcribe. Each step is safe to repeat.
 
 1. Install Node.js 20.19 or newer and `ffmpeg`. Use the Node `.tar.gz` archive from `https://nodejs.org/dist/v20.19.0/`, or run `npx -y node@20.19.0`. On macOS, `brew install ffmpeg`. On Linux, `sudo apt-get install -y ffmpeg`.
 
-2. Install the npm package. Read the published `version` and run `npm install -g poddrill@<version>`. Do not use `@latest`. Cloning the git repository is not required. If you clone it, set `GIT_TERMINAL_PROMPT=0`.
+2. Install the npm package. Run `npm install -g poddrill@0.3.0`. Do not use `@latest`. Cloning the git repository is not required. If you clone it, set `GIT_TERMINAL_PROMPT=0`.
 
 3. Run `poddrill install-python`. This creates `~/.cache/poddrill/venv` and installs cactus-needle 3.2.0, numpy 2.5.4, and onnxruntime 1.31.0. It uses `uv` when `uv` is on PATH, and otherwise `python3 -m venv`. The npm package named cactus-needle is a different package.
 
 4. Run `poddrill fetch-weights`. This downloads `voxceleb_ECAPA512.onnx` from the pinned WeSpeaker commit, checks the byte size and SHA-256, and writes `~/.cache/poddrill/ecapa/voxceleb_ECAPA512.onnx`. WeSpeaker ECAPA-TDNN512 pretrained on VoxCeleb. VoxCeleb is used under CC BY 4.0. A later run leaves a matching file in place.
 
-5. Run `poddrill client doctor --client cursor --json`. Use `grok_build` or `grok_bot` in place of `cursor` when that is the client. For every check whose `state` is `bad`, run the `fix` command on that check, then run doctor again. `yt-dlp` is optional and does not fail the command. `workspace` stays `pending` until setup. Stop this loop when doctor exits 0, or when the only `bad` check is `link`.
+5. Run `poddrill client doctor --client cursor --json`. Use `grok_build` or `grok_bot` in place of `cursor` when that is the client. For every check whose `state` is `bad`, run the `fix` command on that check, then run doctor again. Skip a check whose `state` is `optional`. Do not install it. Do not mention it. Do not ask the user about it. `workspace` stays `pending` until setup. Stop this loop when doctor exits 0, or when the only `bad` check is `link`.
 
-6. Run `poddrill setup --provider localhost --queue-length 4`. Without `PODDRILL_WORKSPACE`, setup and every other command use `~/poddrill`. For `ja`, `ko`, or `zh`, read the weights guide and pass `--model-weights` on that same command. `en`, `de`, `fr`, `es`, `it`, `nl`, and `pl` do not need Moonshine weights.
+6. Run `poddrill setup --provider localhost --queue-length 4`. Without `PODDRILL_WORKSPACE`, setup and every other command use `~/poddrill`. When the episode language is `ja`, `ko`, or `zh`, read the weights guide before this command. Ask the user before you install anything that guide names.
 
    `poddrill bootstrap --provider localhost --queue-length 4` runs steps 3, 4, and 6.
 
@@ -39,7 +39,7 @@ A later refresh of clients that already have an entry is `poddrill client plan -
 
 ## Python
 
-`PODDRILL_PYTHON` selects the interpreter. Pass `--python` or set `PODDRILL_PYTHON` on setup to store an absolute path in `poddrill.json`. Otherwise PodDrill uses `~/.cache/poddrill/venv/bin/python` when that file exists, then `python3`. Install yt-dlp and moonshine-voice into that same interpreter. The current yt-dlp and moonshine-voice releases are unpinned.
+`PODDRILL_PYTHON` selects the interpreter. Pass `--python` or set `PODDRILL_PYTHON` on setup to store an absolute path in `poddrill.json`. Otherwise PodDrill uses `~/.cache/poddrill/venv/bin/python` when that file exists, then `python3`.
 
 ## Stop
 
@@ -55,7 +55,9 @@ Read cues only after the embedding is ready. A ready transcript can still be not
 
 An asset clusters cues that sound like one voice. That cluster is a speaker group. You assign the group a name, `quote`, `ending`, or `undetermined`. The utility does not choose the name.
 
-A summary does not require those labels.
+Label the speaker groups before you write a summary. Do not write a summary from the transcript text alone.
+
+The order is `poddrill start`, then poll `poddrill episode` until the transcript and the embedding are `ready`, then `poddrill cues` and `poddrill label-groups` from the speaker guide, then `poddrill start-summary`, `poddrill post-paragraph`, and `poddrill set-summary` from the summary guide. Present the text from `poddrill summary`. A summary written in chat before those commands is not the result.
 
 ## Summaries
 
@@ -83,7 +85,7 @@ Parse the JSON line on stdout. `episode` exits 0 when the id is unknown. `not-re
 
 ## Present the summary
 
-Present the summary in the format preferred or prescribed by users, but always grounded by the summary constructed via poddrill.
+Present the text returned by `poddrill summary`. Match the format the user asked for. Do not replace that text with a summary you wrote from the transcript.
 
 ## Guides
 
@@ -92,8 +94,8 @@ Each file tells you how to do one part of the task.
 - For a feed or a YouTube page, and for telling a new episode from one already handed to poddrill, read [references/track-sources.md](references/track-sources.md).
 - For finding the audio, downloading it, and writing the 16 kHz WAV, read [references/fetch-audio.md](references/fetch-audio.md).
 - For Japanese, Korean, or Chinese weights, read [references/select-models.md](references/select-models.md).
-- For a voice name, a quote, an ending, or cues left undetermined, read [references/assign-speakers.md](references/assign-speakers.md).
-- For an episode summary, read [references/create-summary.md](references/create-summary.md).
+- Before any summary, read [references/assign-speakers.md](references/assign-speakers.md) and label the groups.
+- After those labels, read [references/create-summary.md](references/create-summary.md) and store the summary with its commands.
 
 ## Finish
 

package/.agents/skills/poddrill/references/create-summary.md

@@ -1,38 +1,48 @@
 # Create an episode summary
 
-Build one summary of an episode from its cues. One episode can hold many summaries. Each one is a YAML file. You do not write that file yourself. Use the commands below.
+Build one summary of an episode from its cues. Do this after the speaker groups are labeled. Do not write a summary from the transcript text. One episode can hold many summaries. Each one is a YAML file. You do not write that file yourself. Use the commands below.
 
 Read the cues first with `poddrill cues`. Page them as in [Speaker assignment](assign-speakers.md).
 
 The requirement is what the user asked you to summarize. Cite the cues that answer the requirement. You do not need to include a cue if it does not contribute to answering the requirement.
 
-Before you write, mark the parts that are actually there. An episode can hold several. A part the cues do not support is left out.
+Before you write, mark the parts that are actually there. An episode can hold several. A part the cues do not support is left out. When you mark a part, mark which cues hold each piece below. A piece the speaker never gives is absent. Do not invent it.
 
 ### News commentary
 
-News commentary is what happened, and the opinions on what happened. An opinion is that person's statement about what happened.
+What happened. Each opinion about it. Who holds that opinion.
 
 ### Explanation
 
-An explanation is how something works or why it is that way.
+How it works or why it is that way. Naming the subject is not that piece.
 
 ### Advice
 
-Advice is what the listener should do, how they should decide, or how to get better.
+What the listener should do. When the speaker gives a how or a decision rule, include that piece.
 
 ### Claim
 
-A claim is what someone holds, how they elaborate it, and the backup they offer. The elaboration is how they explain the claim. A claim can include a correction of who is speaking, and a place they stop.
+What the speaker holds, including a hedge. How they explain it. The evidence they give. When the cues correct who is speaking, or show where they stop, include that piece.
 
 ### Discussion
 
-A discussion is one topic, the perspectives on that topic, and how the people respond to each other. A perspective is a claim.
+The topic. Each person's view, written as a claim. How the people respond to each other.
+
+## Check coverage
+
+The paragraph `text` and its `cues` must include every piece the speaker gave for that part. When a part spans several paragraphs, check those paragraphs together.
+
+When a piece the type normally has is absent, say so in the paragraph. Write "He gives no reason." Do not leave the gap unstated.
+
+A hedge is part of what the speaker holds. Keep it. The rule in [Orwell's rules](orwell.md) that cuts a word does not remove a hedge.
+
+Before `setSummary`, check every marked part. Replace a paragraph that misses a piece the speaker gave with `putParagraph`. The summary must not state a part more completely, or more certainly, than its paragraphs do.
 
 ## Paragraphs and the summary
 
 A cue belongs in a paragraph when it supports a part you marked for the requirement.
 
-You decide how the parts sit in the paragraphs. A part may take more than one paragraph. Link the cues that belong to one part, and cover what holds that part together. The summary written from those paragraphs stays clear, concise, and structured.
+You decide how the parts sit in the paragraphs. A part may take more than one paragraph. Link the cues that belong to one part. Then run the coverage check.
 
 Write `summary` after those paragraphs exist. Write it from the paragraph `text`.
 
@@ -94,7 +104,7 @@ The MCP tool is `putParagraph`. Pass `episodeId`, `summaryId`, `index`, `text`,
 
 ## Set the episode summary
 
-Write this after the paragraphs. `setSummary` rejects a file that has no paragraphs.
+Write this after the paragraphs, and after the coverage check. `setSummary` rejects a file that has no paragraphs.
 
 `summary` is the prose for the whole episode. Those words follow [Orwell's rules](orwell.md). An empty string is rejected.
 

package/.agents/skills/poddrill/references/fetch-audio.md

@@ -12,18 +12,18 @@ Download that URL with the script in this skill. The file is `scripts/fetch-audi
 node <skill-dir>/scripts/fetch-audio.mjs <url> <output-path> [expected-bytes]
 ```
 
-The script refuses a destination inside the git tree that contains the script. Pass the byte length when the feed lists one. The script leaves an existing file of that size in place.
+Run this script even when the installed copy is not inside a git repository. Do not replace it with a script of your own. It refuses a destination inside a git tree that contains the script. Pass the byte length when the feed lists one. The script leaves an existing file of that size in place.
 
 ## yt-dlp
 
-If the feed has no audio URL, or the script does not get the file, install the current yt-dlp into the PodDrill Python and run that module. The version is unpinned. On a PEP 668 Python, install into the venv from `poddrill install-python`, or set `PODDRILL_PYTHON` to an interpreter that allows pip. A pipx install or a standalone yt-dlp binary also works. The printed line is the download path.
+Ask the user before you install yt-dlp. Do that only when the feed has no audio URL, or the script did not write the file. Then install the current yt-dlp into the PodDrill Python and run that module. The version is unpinned. On a PEP 668 Python, install into the venv from `poddrill install-python`, or set `PODDRILL_PYTHON` to an interpreter that allows pip. A pipx install or a standalone yt-dlp binary also works. The printed line is the download path.
 
 ```
 "$PODDRILL_PYTHON" -m pip install --upgrade yt-dlp
 "$PODDRILL_PYTHON" -m yt_dlp -x --no-playlist --print after_move:filepath -o "<directory>/download.%(ext)s" "<page-url>"
 ```
 
-`poddrill client doctor` reports yt-dlp as optional and prints that pip command when it is missing. Write `<directory>` outside this git repository. If that command does not get the audio, read [Usage and options](https://github.com/yt-dlp/yt-dlp#usage-and-options).
+Write `<directory>` outside this git repository. If that command does not get the audio, read [Usage and options](https://github.com/yt-dlp/yt-dlp#usage-and-options).
 
 ## Other audio
 

package/.agents/skills/poddrill/references/select-models.md

@@ -1,6 +1,6 @@
 # Set up Moonshine weights
 
-PodDrill does not download the Moonshine weights. Install the current moonshine-voice release into the PodDrill Python, download the model with word timestamps, then pass the returned directory to setup. The version is unpinned. On a PEP 668 Python, use the venv from `poddrill install-python`.
+Read this only when the episode language is `ja`, `ko`, or `zh`. Ask the user before you install moonshine-voice. PodDrill does not download the weights. After the user agrees, install the current moonshine-voice release into the PodDrill Python, download the model with word timestamps, then pass the returned directory to setup. The version is unpinned. On a PEP 668 Python, use the venv from `poddrill install-python`.
 
 Install the package first. `$PODDRILL_PYTHON` is the interpreter PodDrill spawns.
 

package/.agents/skills/poddrill/scripts/fetch-audio.mjs

@@ -1,4 +1,4 @@
-import { createWriteStream } from "node:fs";
+import { createWriteStream, realpathSync } from "node:fs";
 import { mkdir, realpath, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";
@@ -15,7 +15,7 @@ export async function downloadTo(url, outputPath, expectedByteLength) {
   const expected = readExpectedByteLength(expectedByteLength);
   const destination = await canonicalPath(outputPath);
   const root = await gitRoot();
-  if (isInside(root, destination)) {
+  if (root !== undefined && isInside(root, destination)) {
     throw new Error(`refusing to write inside the git tree: ${destination}`);
   }
   await mkdir(path.dirname(destination), { recursive: true });
@@ -90,7 +90,7 @@ async function gitRoot() {
       }
       const parent = path.dirname(current);
       if (parent === current) {
-        throw new Error("refusing to download because no git tree contains the script");
+        return undefined;
       }
       current = parent;
     }
@@ -131,7 +131,8 @@ function parseCliByteLength(raw) {
 }
 
 const entry = process.argv[1];
-if (entry !== undefined && path.resolve(entry) === fileURLToPath(import.meta.url)) {
+const invoked = entry === undefined ? undefined : realpathSync(entry);
+if (invoked !== undefined && invoked === fileURLToPath(import.meta.url)) {
   const url = process.argv[2];
   const outputPath = process.argv[3];
   const rawLength = process.argv[4];

package/README.md

@@ -1,18 +1,37 @@
 # PodDrill
 
-PodDrill is a skill that transcribes episode audio into timed text, groups the voices, and stores a summary.
+PodDrill is a tool that helps an agent to transcribe podcast audio into timed text, group the voices, and store a summary. It provides an agent skill and a set of best practices how to summarize a podcast efficiently and with clear structures.
 
-## Say this
+## Quick start
 
-Copy this to the agent.
+### Set up your agent
+
+Ask your agent:
+
+```text
+Set up PodDrill skill and tool: https://github.com/JeromeZhao/PodDrill
+```
+
+### Monitor a podcast
+
+Set up a monitor on a podcast and summarize new episode:
+
+```text
+/PodDrill monitor <podcast name you want to monitor> podcast and summary newly released episode.
+```
+
+### Summarize your own way
+
+Identify books mentioned in an episode and what it is about:
 
 ```text
-Set up PodDrill on this computer.
+/PodDrill for new episode from <podcast name you want to monitor>, extract what books it mentioned and what the book is about.
 ```
 
-The supported install is the npm package. Read the published `version` and run `npm install -g poddrill@<version>`. Cloning this repository is not required. If you clone it, set `GIT_TERMINAL_PROMPT=0`. The agent then follows the skill shipped in the package.
+## For LLM and Agent
+The supported install is the npm package. Run `npm install -g poddrill@0.3.0`. Do not use `@latest`. Cloning this repository is not required. If you clone it, set `GIT_TERMINAL_PROMPT=0`. The agent then follows the skill shipped in the package.
 
-## Requirements
+### Requirements
 
 The computer that runs PodDrill needs:
 
@@ -31,7 +50,7 @@ Grok Bot cannot write its server entry. It prints the custom server to add: the
 
 `npm test` runs the unit tests. Those tests use `node --experimental-strip-types`.
 
-`npm run test:smoke` runs a clean-home install, downloads the ECAPA file, and transcribes a short generated clip through `dist/cli.js`. It needs `python3` with `ensurepip`, `ffmpeg`, and `espeak-ng`. If one of those is missing, the test skips and names the missing tool. This repository has no CI workflow. Run `npm run test:smoke` on a computer that has those tools. Build `dist/` with `npm run build` first.
+`npm run test:smoke` runs a clean-home install, downloads the ECAPA file, and transcribes a short generated clip through `dist/cli.js`. It needs `python3` with `ensurepip`, `ffmpeg`, and `espeak-ng`. If one of those is missing, the test skips and names the missing tool. Run `npm run test:smoke` on a computer that has those tools. Build `dist/` with `npm run build` first.
 
 ## License
 

package/dist/client.js

@@ -885,7 +885,7 @@ async function ytDlpCheck(env, python) {
     return {
         name: "yt-dlp",
         state: "optional",
-        detail: "yt-dlp is optional. Install the current release into the PodDrill Python, or use a standalone yt-dlp binary.",
+        detail: "Not required for setup.",
         fix: ytDlpFix(python),
     };
 }

package/dist/owner.js

@@ -393,10 +393,33 @@ function parseRequest(value) {
     if (op === "labelGroups" && typeof record["episodeId"] === "string") {
         return { op: "labelGroups", episodeId: record["episodeId"], groups: record["groups"] };
     }
-    if (typeof op === "string") {
-        return summaryRequest(op, record);
+    return socketSummary(record);
+}
+function socketSummary(record) {
+    const op = record["op"];
+    const episodeId = record["episodeId"];
+    if (typeof episodeId !== "string") {
+        return undefined;
+    }
+    if (op === "startSummary") {
+        return { op: "startSummary", episodeId };
+    }
+    const summaryId = record["summaryId"];
+    if (typeof summaryId !== "string") {
+        return undefined;
+    }
+    switch (op) {
+        case "setSummary":
+            return { op: "setSummary", episodeId, summaryId, summary: record["summary"] };
+        case "putParagraph":
+            return { op: "putParagraph", episodeId, summaryId, body: record["body"] };
+        case "postParagraph":
+            return { op: "postParagraph", episodeId, summaryId, body: record["body"] };
+        case "summary":
+            return { op: "summary", episodeId, summaryId };
+        default:
+            return undefined;
     }
-    return undefined;
 }
 function summaryRequest(name, args) {
     const episodeId = args["episodeId"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poddrill",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Transcribe episode audio into timed text, group the voices, and store a summary.",
   "license": "MIT",
   "author": "Jianyu Zhao",