Metadata-Version: 2.4
Name: hakodesh
Version: 0.2.3
Summary: Host-agnostic empty book with a deterministic procedural-memory runtime.
Author: Shelleyguitar
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://pypi.org/project/hakodesh/
Keywords: cli,sdk,spells,agents,receipts,akashic,grimoire
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: platformdirs<5,>=4.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# hakodesh

Host-agnostic Python CLI and SDK. After `pip install hakodesh` the user book is empty. Your LLM or agents **mint** spells, enchantments, wards, and combos as they need them. Repeated structured workflows can be **remembered** and, after a configurable promotion policy, executed as deterministic procedures **without another LLM pass**.

PyPI name and import: **hakodesh**. The command you type is **devra** — that is the `snx` role: `devra <spell> [args...]` casts a minted spell. `hakodesh` is the same CLI binary.

This package does **not** prove SNX token savings. Measurements are recall, correctness, straight-through execution, re-entry, model turns, and host-reported context crossing.

## Release

Current PyPI version is **0.2.3**. `pip install hakodesh` installs this release. The command you type is **devra**.

**0.2.0 and 0.2.1 were withdrawn** from the index (deleted, not yanked). 0.2.0's procedure integrity did not cover approval or routing state and parameterized replay reused last-seen literals. **0.1.0 remains** installable. **0.2.2 remains** as the previous current. 0.2.3 is the same runtime as 0.2.2; it teaches `devra` (the `snx` role), `spellbook`, and first-class `enchant` / `ward` / `combo`.

Procedures are HMAC-authenticated with the home chain key. Arguments that vary across training traces become required slots; `decide` / `run` take `--bind name=value`. Unsigned 0.2.0 `vN.json` files fail closed until re-promoted.

## Install

```bash
pip install hakodesh
devra hello
```

Data home: `HAKODESH_HOME` or the platform user-data directory for `hakodesh`. Never `~/spells`.

## Kernel commands

These are the runtime, not starter spells. Minted spell names are **kebab-case**. Kernel verbs are single tokens (`devra`, `spellbook`, `run`). Two-word leftovers stay kebab as aliases (`grimoire-seal`, `run-intent`, `next-action`).

### Cast

| Command | What it does |
|---|---|
| `devra <spell> [args...]` | Cast a minted spell. Same job `snx <spell>` has on Magus. Alias: `hakodesh devra …` / `invoke` |

### Spellbook

| Command | What it does |
|---|---|
| `devra mint <name> --kind spell\|enchantment\|ward\|combo` | Scaffold into the spellbook (preview; `--confirm` writes) |
| `devra spellbook` | List user artifacts (empty at install). Aliases: `catalog`, `book` |
| `devra route "<intent>"` | Rank minted names plus kernel commands (may include procedure candidates) |

### Kinds — enchantments, wards, combos

These were never gone. They are first-class kernel commands:

| Command | What it does |
|---|---|
| `devra enchant bind\|lift <name> --settings <path>` | Bind or lift a minted **enchantment** |
| `devra ward status\|lock\|unlock\|check <name>` | Fail-closed **ward** |
| `devra combo seal\|cast\|list [name]` | Sealed **combo** pipelines of minted spells |

### Memory

| Command | What it does |
|---|---|
| `devra remember --intent "…" --step spell:name --source host` | Record a structured execution trace (not an opaque receipt) |
| `devra recall "<intent>"` | Local deterministic procedure recall |
| `devra decide "<intent>" [--bind name=value]` | `execute` / `ask_model` / `ambiguous` / `blocked` / `not_found` |
| `devra run "<intent>" [--bind name=value]` | Straight-through execute when decide says `execute`. Alias: `run-intent` |
| `devra next --intent "…" [--bind name=value]` | Next validated procedure step, or a suggestion. Alias: `next-action` |
| `devra rites` | List promoted procedures. Alias: `procedures` |
| `devra approve <id> --confirm` | Approve a high-risk procedure |
| `devra promote [--replace]` | Run promotion now (remember already tries after each success) |
| `devra policy` | Show promotion policy (three-success default is an implementation policy, not SNX history) |
| `devra metrics` | Recall / straight-through / re-entry / context-crossing stats |
| `devra benchmark` | Isolated tempfile-home bench (not the operator home) |

### Ledger

| Command | What it does |
|---|---|
| `devra akashic` | Verify HMAC chain; `--tail N` |
| `devra grimoire` | Cast ledger stats. `grimoire seal --confirm` writes the Merkle seal; `grimoire verify` checks it. Alias: `grimoire-seal` |
| `devra protocol` | Print the `hakodesh.event/v1` contract descriptor |

`--like` on an empty book uses the **kind template** in the wheel. After one spell exists, `--like <that>` copies its shape.

Every mint and cast emits `hakodesh.event/v1`. Akashic is SHA-256 linked and HMAC-SHA256 signed. Grimoire is Merkle-sealed with the same chain key. Promoted procedures use that same home key for `procedure_mac`. The keystore is `$HAKODESH_HOME/keys` (0700/0600), minted on first seal, never in the wheel.

Notifications default to `none`. The package does not write LaunchAgents or editor hooks until you mint and bind an enchantment.

## SDK

```python
from hakodesh.catalog import catalog
from hakodesh.mint import mint
from hakodesh import events, akashic, grimoire
from hakodesh.enchant import bind, lift
from hakodesh.ward import unlock
from hakodesh.combo import seal, cast
from hakodesh.memory import remember, recall, decide, run_intent, next_action, approve
```

See `docs/PROCEDURAL_MEMORY.md` and `docs/MIGRATION.md`.

## Empty book law

A fresh install has zero user spells, enchantments, wards, combos, or promoted procedures. Discovery picks up a file the moment it lands under `HAKODESH_HOME/book/`.
