scrip
The deterministic keeper of a scriptorium knowledge base.
The agent owns judgment (synthesis, fact extraction, reconciliation, promotion).
scrip owns only what LLMs are unreliable or expensive at: content hashing,
staleness over a dependency graph, provenance-anchor integrity, and
structured queries over the facts layer. Files are the source of truth;
.kb/manifest.json is only a regenerable speed cache.
Install
uv tool install ./scrip # installs the `scrip` command
# or, without installing:
uv run --project scrip scrip --help
Commands
| Command | What it does |
|---|---|
scrip init [DIR] |
Create the root skeleton — vault/{raw,facts,wiki}/ plus the .kb/ cache and its manifest — in DIR (default: the current directory). Idempotent in an existing root; refuses to nest a new instance inside one. |
scrip status |
Report STALE / OK / UNCOMPILED artifacts from the dependency graph. --no-cache recomputes from files; --rebuild-manifest regenerates the cache. |
scrip verify |
Check every provenance anchor still resolves to text in its source; check referenced sources exist and claim_ids are unique. Fails on BROKEN and AMBIGUOUS by default; --allow-ambiguous downgrades AMBIGUOUS to a warning. |
scrip query [claims|entities|edges|contradictions|reconciliations] |
Structured query over vault/facts/*.ndjson via DuckDB. --sql "<duckdb>", --where, --limit. |
scrip ontology |
Validate and summarize optional vault/ontology.yaml vocabulary for fact predicates, entity kinds, and edge kinds. |
scrip ingest <url|file> |
Fetch/read a source and write canonical vault/raw/<slug>.md plus sidecar metadata. HTML/PDF need the optional [ingest] extra. |
scrip new concept|entity <slug> --from raw/... |
Scaffold a derived wiki page for the agent to fill. |
scrip anchor "<quote>" --source raw/<slug> |
Mint a content-anchored footnote for a verbatim source quote. |
scrip fact add --table claims|entities|edges|reconciliations |
Validate and append facts under the write lock; claims mint verified anchors, reconciliations mint ids/timestamps. |
scrip span --claim <id> |
Resolve a claim anchor and print the cited span. |
scrip similar --title ... --from ... |
Score overlap with existing wiki pages before PROMOTE. |
scrip search "<question>" |
Retrieve source blocks for a miss; uses embeddings if an index exists, otherwise lexical grep. Add --long-docs pageindex to try the PageIndex cache first. |
scrip index |
Build the optional embeddings index over vault/raw/ when scriptoria[embeddings] is installed; otherwise exits cleanly and search falls back to grep. |
scrip pageindex build raw/<slug> |
Build the optional PageIndex cache for one raw source when a compatible backend is importable; otherwise exits cleanly. |
scrip pageindex search "<question>" [--source raw/<slug>] |
Search cached PageIndex sections, returning only snippets mapped back to canonical vault/raw/ text. |
scrip watch / scrip unlock |
Watch vault health in a poll loop; clear a stale advisory write lock. |
Every command accepts --root DIR and --json (init takes its target as a
positional path instead of --root).
The optional scrip-harness package adds the model-bearing commands, including
scrip-harness answer "<question>", which gathers evidence with these primitives
and verifies every citation before printing or saving an answer.
Exit codes
| Code | Meaning |
|---|---|
0 |
clean / success |
1 |
actionable finding (stale artifacts; broken citations) |
2 |
usage error |
3 |
data error (malformed frontmatter / NDJSON; missing source; duplicate id) |
4 |
internal error |
Code 1 is an expected outcome the agent branches on, not a crash.
1 maintainer
Metadata
1 maintainer
Release files for scriptoria 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| scriptoria-0.11.0.tar.gz | 165.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| scriptoria-0.11.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 225.1 kB
Release files / scriptoria-0.11.0.tar.gz
| Download URL | scriptoria-0.11.0.tar.gz |
|---|---|
| Size | 165.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
686d04f9456edd9f404b8a13569fdd512ad733526a56cd492e38dfda53e4e4a3
|
|
BLAKE2b-256 checksum How to use checksums |
5c543c6d194042c5a7de16f5406e987907cf20a85094bd827f9ce29d630ec4f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / scriptoria-0.11.0-py3-none-any.whl
| Download URL | scriptoria-0.11.0-py3-none-any.whl |
|---|---|
| Size | 59.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ac23da5eea944b1019dc0577952088dbc7e1d92935d2e1a3f8c5f6bd155c530
|
|
BLAKE2b-256 checksum How to use checksums |
ad8ba6748b28d480fb2799f384aa88b7f6037598dcadfe129d40bfb8f1609d69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
