Metadata-Version: 2.4
Name: witful
Version: 0.1.3
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
Requires-Dist: attrs (>=26.1.0,<26.2)
Requires-Dist: cattrs (>=26.2.1,<26.3)
Requires-Dist: jsonschema (>=4.26,<5)
Requires-Dist: matplotlib (>=3.11.2,<3.12)
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

Turn engineering lessons into a searchable, typed knowledge base. Witful
connects lessons across disciplines, records where they were applied, and
preserves decisions with replayable evidence. Your records stay in your own
collection; this repository ships reusable code and synthetic examples.

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

- [Install](#install)
- [Model](#model)
- [Privacy and operations](#privacy-and-operations)
<!-- toc:end -->

## Install

Requires Python 3.12+ on macOS or Linux (excluding Python 3.14.1).

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

Use `pip install 'witful[postgres]'` for a shared PostgreSQL index. SQLite is
the default and needs no server. See [CLI and first run](docs/CLI.md).

## Model

`Identity -> Discipline -> Skill -> Lesson -> Lemma` is a composed hierarchy.
Cross-discipline relationships form a separate graph. Recorded applications
measure observed reuse, not intelligence or hidden model reasoning. Life
preserves explicit choices, revisions, and the inputs behind their plots.

- Closed schemas generated from attrs models, with cattrs conversion.
- Append-only lesson, application, and decision journals with validated IDs.
- Local SQLite or optional PostgreSQL search and decision archive seeding.
- Deterministic plots, source snapshots, and explicit renderer drift checks.
- Project checkpoints comparing documented learning and skill use across Git boundaries.
- A toolbox and problem taxonomy with source-backed task-frequency plots.
- Batched PyPI name checks with TTL caching and rate-limit cooldowns.
- A redacted PII scanner usable locally, in pre-commit, and in CI.

## Privacy and operations

Run `witful privacy scan` before sharing a collection. The scanner detects
defined patterns and configured literal deny terms; it cannot prove text is
free of personal data. Review output and publication contents as described in
[SECURITY.md](SECURITY.md).

See [development](CONTRIBUTING.md), [storage and orchestration](docs/storage.md),
[project checkpoints](docs/checkpoints.md), [releases](docs/releases.md), and [SKILL.md](SKILL.md) for agent-assisted use.

