Metadata-Version: 2.4
Name: scriptoria
Version: 0.5.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]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
| `scrip index` | v0 stub for the embeddings retrieval rung. |

Every command accepts `--root DIR` and `--json`.

## 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.
