@dzhechkov/skills-book-digitizer 0.2.0 → 0.2.2
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 +77 -0
- package/package.json +2 -2
- package/scripts/book-ingest.mjs +0 -0
package/README.md
CHANGED
|
@@ -33,6 +33,83 @@ dz init --target claude-code --select digitize-book
|
|
|
33
33
|
Prerequisites: `poppler-utils` (ingest) and, for the KB, `dz setup --memory agentdb`
|
|
34
34
|
(installs `agentdb` + `better-sqlite3`).
|
|
35
35
|
|
|
36
|
+
## Usage scenarios
|
|
37
|
+
|
|
38
|
+
The digitizer produces three durable artifacts from one book: (1) an installable **skill pack**, (2) a
|
|
39
|
+
per-project **two-store KB** (`book-kb-index` → `.dz/memory/books.sqlite` lexical + shared agentdb
|
|
40
|
+
vector), and (3) a promote path into a durable cross-project **Knowledge Brain** (`~/.dz/brain/`).
|
|
41
|
+
Full design + the RU version: [ADR-001 Knowledge Brain](https://github.com/djd1m/dz-harness-hub/blob/main/features/book-brain/ADR-001-knowledge-brain.md).
|
|
42
|
+
|
|
43
|
+
### 1. Digitize a book → skills + KB
|
|
44
|
+
|
|
45
|
+
The core pipeline. Install the orchestrator, then hand it a PDF; it runs `book-ingest → extract →
|
|
46
|
+
distill → assemble → book-kb-index` through 5 human checkpoints.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
dz init --target claude-code --select digitize-book
|
|
50
|
+
# then, in your agent: «оцифруй вот эту книгу — хочу, чтобы агент проектировал по её методикам»
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Output: a `skills-book-<slug>` pack (decision-moment skills) **and** the two-store KB behind it. Live
|
|
54
|
+
run: DDIA → «Высоконагруженные приложения» digitized to **116 Knowledge Units**.
|
|
55
|
+
|
|
56
|
+
### 2. Query one book's knowledge
|
|
57
|
+
|
|
58
|
+
Lexical (FTS5) recall over a single digitized book's KB, in the project that ingested it. `--book`
|
|
59
|
+
narrows the search to one book slug:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
dz recall --books --book <slug> "replication topology"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Pull-based: you ask, you get KU hits back with source + page anchors. No hook, no injection.
|
|
66
|
+
|
|
67
|
+
### 3. Build a cross-project brain from N books
|
|
68
|
+
|
|
69
|
+
Promote each project's digitized-book KUs into **one shared brain** (`~/.dz/brain/` — lexical
|
|
70
|
+
`books.sqlite` + vector `agentdb.db`), then query across every ingested book at once:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
dz brain add --source <slug> # promote this project's KUs into the brain (idempotent)
|
|
74
|
+
dz brain list # what's in the brain: slug, kind, KU count, corpus version
|
|
75
|
+
dz brain query "replication topology" # cross-source recall over ALL books
|
|
76
|
+
dz brain query "replication topology" --source <slug> # optional: narrow to one book
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
One shared store, not per-book packages: you do **not** install anything to query the brain — it
|
|
80
|
+
accretes on `dz brain add`. The *right* book surfaces by **relevance** (KUs rank on one common scale,
|
|
81
|
+
each hit labelled with its source book + page); `--source` is a label filter, not a manual routing
|
|
82
|
+
pick. Cross-source is the default — multiple books scoring on a query is a feature (richer grounding),
|
|
83
|
+
not a bug.
|
|
84
|
+
|
|
85
|
+
### 4. Grounded answering (the hook)
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
dz brain init # opt-in: wire the grounding UserPromptSubmit hook (once)
|
|
89
|
+
dz brain ground "<prompt>" # what the hook runs: retrieve + emit citations (or nothing)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`dz brain init` (opt-in) wires a single `UserPromptSubmit` hook that runs `dz brain ground` on each
|
|
93
|
+
prompt. On a *relevant* prompt (relevance-gated, so it stays quiet on unrelated turns) the hook
|
|
94
|
+
mechanically retrieves top-K brain KUs and injects them — with source + page citations — into that
|
|
95
|
+
turn's context, so the agent answers **from the book, not from training data**. Off by default; a
|
|
96
|
+
prompt with no lexical overlap (e.g. "what's the weather") injects nothing.
|
|
97
|
+
|
|
98
|
+
Honesty boundary: the injection is **mechanical** (the hook forces the grounding block into context and
|
|
99
|
+
the agent literally cannot start the turn without it); "answering from it" is **agent discipline** — the
|
|
100
|
+
hook can force the context but not the completion. The hook is **generic and wired once** (one hook over
|
|
101
|
+
the whole brain across all sources — *not* per book), and needs **no edits to `CLAUDE.md` or governance
|
|
102
|
+
shards** — the injection channel is the hook's stdout (`hookSpecificOutput.additionalContext`).
|
|
103
|
+
|
|
104
|
+
### 5. Sharing a digitized book
|
|
105
|
+
|
|
106
|
+
The `skills-book-<slug>` **pack** (via GitHub / `npx`) carries the behavior — the decision-moment
|
|
107
|
+
skills and `references/` deep-lookup. The design (ADR §8.1, P2) also ships the book's **KB slice inside
|
|
108
|
+
the pack** under the same CP5 licence decision that gates the pack itself: copyrighted books stay
|
|
109
|
+
`private: true` (structural, mechanically enforced — no auto-publish, no preset entry), permissive
|
|
110
|
+
sources are publishable. Your whole personal **brain is never published** — it is a local accretion you
|
|
111
|
+
back up, not a distributable.
|
|
112
|
+
|
|
36
113
|
## Design guarantees — structural vs. protocol (stated honestly)
|
|
37
114
|
|
|
38
115
|
Two kinds of guarantee, and the difference matters:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dzhechkov/skills-book-digitizer",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.2",
|
|
4
4
|
"description": "Canonical book-digitizer skill pack — 6 skills that turn an engineering book/textbook/monograph into an installable skill pack whose skills make AI coders work within the book's methodologies: digitize-book (orchestrator), book-ingest, book-knowledge-extract, book-skill-distill, book-pack-assemble, book-kb-index.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "dzhechko",
|
|
@@ -36,4 +36,4 @@
|
|
|
36
36
|
"directory": "packages/@dzhechkov/skills-book-digitizer"
|
|
37
37
|
},
|
|
38
38
|
"homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/skills-book-digitizer#readme"
|
|
39
|
-
}
|
|
39
|
+
}
|
package/scripts/book-ingest.mjs
CHANGED
|
File without changes
|