Metadata-Version: 2.4
Name: hakodesh
Version: 0.2.2
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, import, and command: **hakodesh**. Not snax. Not snx.

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.2**. `pip install hakodesh` installs this release.

**0.2.0 was withdrawn** from the index (deleted, not yanked) because procedure integrity did not cover approval or routing state and parameterized replay reused last-seen literals. **0.1.0 remains** installable. 0.2.2 is the same runtime as the Watson HMAC / `--bind` fix first shipped as 0.2.1; this version only makes the public page and shipped docs match that fact.

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

## Install

```bash
pip install hakodesh
```

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

## Kernel commands

These are the runtime, not starter spells:

| Command | What it does |
|---|---|
| `hakodesh catalog` | User artifacts in the book (empty at install) |
| `hakodesh route "<intent>"` | Rank minted names plus kernel commands (may include procedure candidates) |
| `hakodesh invoke <name> [args...]` | Cast a minted spell by name |
| `hakodesh mint <name> --kind spell\|enchantment\|ward\|combo` | Scaffold into the book (preview; `--confirm` writes) |
| `hakodesh remember --intent "…" --step spell:name --source host` | Record a structured execution trace (not an opaque receipt) |
| `hakodesh recall "<intent>"` | Local deterministic procedure recall |
| `hakodesh decide "<intent>" [--bind name=value]` | `execute` / `ask_model` / `ambiguous` / `blocked` / `not_found` |
| `hakodesh run-intent "<intent>" [--bind name=value]` | Straight-through execute when decide says `execute` |
| `hakodesh next-action --intent "…" [--bind name=value]` | Next validated procedure step, or a suggestion |
| `hakodesh procedures` | List promoted procedures |
| `hakodesh approve <id> --confirm` | Approve a high-risk procedure |
| `hakodesh policy` | Show promotion policy (three-success default is an implementation policy, not SNX history) |
| `hakodesh metrics` | Recall / straight-through / re-entry / context-crossing stats |
| `hakodesh akashic` | Verify HMAC chain; `--tail N` |
| `hakodesh grimoire` | Cast ledger stats |
| `hakodesh grimoire-seal` | RFC 6962 Merkle seal (preview; `--confirm` writes; `--verify`) |
| `hakodesh enchant bind\|lift <name> --settings <path>` | Bind or lift a minted enchantment |
| `hakodesh ward status\|lock\|unlock\|check <name>` | Fail-closed ward kernel |
| `hakodesh combo seal\|cast\|list [name]` | Sealed pipelines of minted spells |
| `hakodesh <minted-name> [args...]` | Cast after mint |

`--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/`.
