@karaoke-cms/enrich 0.6.2 → 0.9.0
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.
- package/README.md +48 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# @karaoke-cms/enrich
|
|
2
|
+
|
|
3
|
+
AI enrichment pipeline for karaoke-cms. Reads published vault content and writes AI-generated metadata (reading time, tags, description, related posts) back into frontmatter.
|
|
4
|
+
|
|
5
|
+
## Where it belongs
|
|
6
|
+
|
|
7
|
+
`packages/enrich/` in the monorepo. Runs as a pre-commit hook — not in CI:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
# .githooks/pre-commit
|
|
11
|
+
node scripts/enrich.js --staged
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Or manually against the full vault:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
node scripts/enrich.js
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Requires `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in the environment (or `.env`).
|
|
21
|
+
|
|
22
|
+
## What it does
|
|
23
|
+
|
|
24
|
+
For each published Markdown file in the vault that has not been enriched yet (or whose body has changed since last enrichment):
|
|
25
|
+
|
|
26
|
+
1. **Reading time** — counts words, estimates minutes at 200 wpm, writes `reading_time` to frontmatter
|
|
27
|
+
2. **Tags** — asks the AI to suggest 3–5 tags; writes `tags` array to frontmatter
|
|
28
|
+
3. **Description** — asks the AI for a one-sentence summary; writes `description` to frontmatter
|
|
29
|
+
4. **Related posts** — computes overlap between tag arrays across all posts; writes `related` array (slugs) to frontmatter
|
|
30
|
+
|
|
31
|
+
Supported AI providers: Anthropic Claude and OpenAI GPT. Provider is selected based on which API key is present.
|
|
32
|
+
|
|
33
|
+
Results are cached in `.enrich-cache.json` (gitignored) — files are skipped if their body hash has not changed. A per-run cap (`MAX_ENRICHMENTS_PER_RUN`) prevents runaway API costs.
|
|
34
|
+
|
|
35
|
+
**Privacy gate**: only processes files with `publish: true`. Private vault notes are never sent to an AI provider.
|
|
36
|
+
|
|
37
|
+
## Status
|
|
38
|
+
|
|
39
|
+
**Stub** — the package entry point (`bin/enrich`) is declared but the implementation has not yet been migrated from `apps/template/scripts/enrich.js`. Until migration is complete, use the script directly from your project's `scripts/` directory.
|
|
40
|
+
|
|
41
|
+
The canonical implementation is at `apps/template/scripts/enrich.js` in this monorepo and at `scripts/enrich.js` in scaffolded projects.
|
|
42
|
+
|
|
43
|
+
## How it changes the behavior of the system
|
|
44
|
+
|
|
45
|
+
- Enrichment is additive and non-destructive — it only writes fields that are absent or stale. Manually written frontmatter values are never overwritten.
|
|
46
|
+
- Enriched fields (`reading_time`, `tags`, `description`, `related`) are consumed by theme components: reading time appears on post cards, tags power the `/tags` routes, related posts appear in the post sidebar.
|
|
47
|
+
- The pre-commit hook means enrichment runs automatically on staged content — authors never need to think about it.
|
|
48
|
+
- Enrichment is disabled in CI by default (`ENRICH_ENABLED` env var). It runs locally on the author's machine, so enriched frontmatter is committed alongside the content.
|