Metadata-Version: 2.4
Name: witful
Version: 0.3.0
Summary: Typed knowledge, reusable lessons, and evidence-based decision replay
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: knowledge,lessons,audit,privacy,replay
Requires-Python: >=3.12,!=3.14.1,<4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: postgres
Provides-Extra: sapience
Requires-Dist: attrs (>=26.1.0,<26.2)
Requires-Dist: cattrs (>=26.2.1,<26.3)
Requires-Dist: cryptography (>=50.0.2,<51)
Requires-Dist: jsonschema (>=4.26,<5)
Requires-Dist: matplotlib (>=3.11.2,<3.12)
Requires-Dist: mcp (>=2.3.0,<3) ; extra == "sapience"
Requires-Dist: networkx (>=3.7,<3.8)
Requires-Dist: psycopg[binary] (>=3.3.6,<3.4) ; extra == "postgres"
Project-URL: Documentation, https://github.com/astrivant/identity/tree/main/docs
Project-URL: Homepage, https://github.com/astrivant/identity
Project-URL: Issues, https://github.com/astrivant/identity/issues
Description-Content-Type: text/markdown

# Witful

Witful is the Python library and CLI for [Identity](https://github.com/astrivant/identity):
a user-owned record of lessons, skills, decisions, tools, and project experience.
It validates sources, builds searchable indexes, generates evidence figures, and
supports explicit sharing through optional integrations.

<!-- toc:start -->
**Table of contents**

- [Install](#install)
- [Responsibilities](#responsibilities)
- [Guides](#guides)
<!-- toc:end -->

## Install

Requires Python 3.12+ on macOS or Linux, excluding Python 3.14.1.

```bash
pip install witful
witful --help
```

Use `witful init ./my-collection` to create an empty collection when you need a new
one. Keep existing collections in place and pass `--repo` to the relevant commands.
See [CLI contracts and first run](https://github.com/astrivant/identity/blob/main/docs/CLI.md).

Optional extras are `postgres` for PostgreSQL and `sapience` for MCP transport.
The Sapience adapter is under development in this checkout until the next release;
use `pip install '.[sapience]'` here to try it. The core package does not install
Sapience or its vector database.

## Responsibilities

- Validate the attrs/cattrs hierarchy and append-only journals.
- Index lessons in SQLite or optional PostgreSQL.
- Preserve concise decisions and source snapshots for reproducible replay.
- Record observed applications, tool use, and project checkpoints.
- Track explicit runtime provenance, reconcile pending tasks, and compare native evidence across instances.
- Render plots from recorded evidence and explicitly export selected awareness figures.
- Check publication inputs with the PII scanner and configurable deny terms.
- Install and synchronize encrypted, signed private collections.
- Isolate concurrent sleeves, sign backups, and reconcile their histories before closure.
- Optionally project reviewed concepts into Sapience and save generated review proposals.

The package does not infer experience from installed dependencies or promote model
summaries to reviewed lessons. Source journals remain owned by the collection.

## Guides

- [Completion audits](completion.md): review every concept before handing work back.

[Architecture and collection conventions](https://github.com/astrivant/identity#readme),
[CLI](https://github.com/astrivant/identity/blob/main/docs/CLI.md),
[Sapience integration](https://github.com/astrivant/identity/blob/main/docs/sapience.md),
[awareness figures](https://github.com/astrivant/identity/blob/main/docs/awareness.md),
[private collection setup](https://github.com/astrivant/identity/blob/main/docs/private-collections.md),
[multisleeving](https://github.com/astrivant/identity/blob/main/docs/multisleeving.md),
[observed instances](https://github.com/astrivant/identity/blob/main/docs/instances.md),
[security](https://github.com/astrivant/identity/blob/main/SECURITY.md), and
[development](https://github.com/astrivant/identity/blob/main/CONTRIBUTING.md).


## Hierarchy terminology

The hierarchy is `Identity -> Discipline -> Skill -> Lesson -> Insight`. An Insight
is a concrete, reusable takeaway from a sourced Lesson. The Python type is
`Insight`, and lessons and catalog annotations expose an `insights` tuple.

New catalogs use version 2 and the `insights` field. Version-1 catalogs with
`lemmas` remain readable and serialize with their original spelling, preserving
content-addressed snapshots and decision chains. To migrate a current catalog,
change its version to 2 and rename each annotation's `lemmas` key to `insights`
together. Keep concept IDs unchanged. Do not edit historical journals or snapshots.

Checkpoint comparisons retain their existing digest representation, so the rename
alone does not count as learning. Current plots, CLI output, and MCP projections
use Insight; existing projected memory IDs remain stable. Historical replay still
requires acknowledgment of renderer changes before producing different plot bytes.

