Metadata-Version: 2.4
Name: akousma
Version: 0.4.0
Summary: Python reference implementation of the Sonic Field akousma sonic-memory protocol (part of Earworm).
Author: Sonic Field Labs
License: MPL-2.0
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# akousma (Python)

Reference implementation of the Sonic Field **akousma** sonic-memory protocol. Consumed by
**oída**, **germ** (backend), and **algophony** (pipelines) so all three share one memory layer
with one lineage model.

Spec: [`earworm/docs/akousma_spec_v1.md`](../../docs/akousma_spec_v1.md) ·
Store: [`earworm/docs/akousmata-store.md`](../../docs/akousmata-store.md)

## Install

```sh
pip install -e ~/workspace/earworm/packages/py-akousma
```

## Use

```python
import akousma

# Build + validate a record
rec = akousma.new_akousma(
    audio={"asset_id": "asset_1", "content_hash": "sha256:...", "duration_seconds": 10.0},
    originating_app="oida", source_type="recorded", origin="live-input",
    listening={"oida.signal": {"class": "music-like"}},
)
assert akousma.is_valid(rec)

# Shared store (defaults to ~/workspace/akousmata, or $AKOUSMATA_PATH)
with akousma.AkousmataStore() as store:
    uri = store.put_audio(open("clip.wav", "rb").read())   # content-addressed
    rec["audio"]["uri"] = uri
    store.put(rec)

    child = akousma.new_akousma(
        audio={"asset_id": "asset_2"}, originating_app="germ",
        source_type="generated", origin="generated",
        parent_akousma_ids=[rec["akousma_id"]], operation="transform", prompt="make it metallic",
    )
    store.put(child)
    store.ancestors(child["akousma_id"])   # -> [rec["akousma_id"]]  (germ lineage explorer)
    store.query(originating_app="oida")    # -> [rec]                (algophony batch)
```

The bundled `akousma/akousma.schema.json` is the canonical schema, kept in sync with
`earworm/packages/core/schemas/akousma.schema.json`.
