Metadata-Version: 2.4
Name: scriptoria
Version: 0.9.0
Summary: Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base
Project-URL: Homepage, https://github.com/coredipper/scriptorium
Project-URL: Changelog, https://github.com/coredipper/scriptorium/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/coredipper/scriptorium/issues
License: MIT
Keywords: agent,knowledge-base,markdown,provenance,staleness,wiki
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: duckdb>=1.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: embeddings
Requires-Dist: model2vec>=0.3; extra == 'embeddings'
Requires-Dist: numpy>=1.24; extra == 'embeddings'
Provides-Extra: ingest
Requires-Dist: pypdf>=4.0; extra == 'ingest'
Requires-Dist: trafilatura>=1.8; extra == 'ingest'
Description-Content-Type: text/markdown

# scrip

The deterministic keeper of a [scriptorium](../README.md) 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

```sh
uv tool install ./scrip      # installs the `scrip` command
# or, without installing:
uv run --project scrip scrip --help
```

## Commands

| Command | What it does |
|---|---|
| `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_id`s 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`.

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.
