Skip to main content

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 · Store: earworm/docs/akousmata-store.md

Install

cd packages/py-akousma
pip install -e .

Use

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)

# Optional v1.6 accountable-listening index. The full producer report remains
# namespaced in `listening`; the auditum keeps attribution and references.
rec["auditum"] = akousma.auditum(listenings=[{
    "listening_id": "lst_1",
    "listener_id": "oida",
    "listener_type": "agent",
    "created_at": rec["created_at"],
    "report_namespace": "oida.signal",
    "contract": "akouo/v0.9",
}], route_decisions=[akousma.route_decision(
    "decision-listen-1",
    gate="inference", outcome="proceed",
    subject="accountable listening pass",
    reason="The user requested an observe-only pass.",
    actor="oida-router", listening_id="lst_1",
    producer_contract="akouo/v0.9",
)])

# Shared store (platform application-data directory, 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)
    store.query(has_auditum=True)          # accountable records
    store.query(has_route_decision=True)   # auditum/v2 decisions
    store.query(has_stop_decision=True)    # refusal, withholding, forgetting, non-action...
    store.query(has_disagreement=True)     # plural hearings with preserved differences
    store.query(listener_type="human")     # exact attributable listener facet
    store.query(record_class="human")      # coarse navigator class
    store.current_head(rec["akousma_id"])  # unique latest revision, or raises on a branch

A refusal before capture is also addressable without inventing audio:

refusal = akousma.new_akousma(
    originating_app="oida",
    source_type="unknown",
    origin="live-input",
    subject="quiet-hours capture request",
    auditum=akousma.auditum(route_decisions=[akousma.route_decision(
        "decision-capture-1",
        gate="capture", outcome="refuse", subject="audio capture",
        reason="The adopted covenant closes the ear.", actor="covenant-gate",
    )]),
)

A completed human listening may also remain addressable without inventing audio. It needs an attributable listening and an explicit raw-audio absence:

human = akousma.new_akousma(
    originating_app="akousmata",
    source_type="unknown",
    origin="live-input",
    subject="night insects heard from an open window",
    auditum=akousma.auditum(
        listenings=[{
            "listening_id": "lst_human_1",
            "listener_id": "local-listener-1",
            "listener_type": "human",
            "created_at": "2026-08-11T15:00:00Z",
            "report_namespace": "human.note",
            "contract": "akouo/v0.9",
        }],
        honest_absences=[{
            "id": "absence_raw_audio_1",
            "kind": "not_retained",
            "subject": "raw audio",
            "attributed_to": "local retention boundary",
            "listening_id": "lst_human_1",
        }],
        route_decisions=[akousma.route_decision(
            "decision_memory_1", gate="memory", outcome="proceed",
            subject="human listening account", reason="The listener chose to retain it.",
            actor="local-listener-1", listening_id="lst_human_1",
        )],
    ),
)
assert akousma.listener_types(human) == ("human",)
assert akousma.record_class(human) == "human"

forget_with_receipt(...) removes a record and returns a content-free durable receipt. forgotten(id) can later prove the operation occurred without restoring summary, tags, location, hashes, URIs, or forgotten content.

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

Metadata

Release files for akousma 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for akousma 0.7.0
File Size Uploaded Provenance Actions
akousma-0.7.0.tar.gz 30.2 kB With provenance Details for akousma-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for akousma 0.7.0
File Interpreter ABI Platform Actions
akousma-0.7.0-py3-none-any.whl Python 3 none any Details for akousma-0.7.0-py3-none-any.whl

Total release size: 54.0 kB

Release files / akousma-0.7.0.tar.gz

Download URL akousma-0.7.0.tar.gz
Size 30.2 kB
Tags Source
SHA-256 checksum
How to use checksums
3d78e508238835db073dbb24a09e6cc696454fe65dd9ce654f024ffe2a4a32ce
BLAKE2b-256 checksum
How to use checksums
5105ae13303010062edf1975a09cf2e64f71c60ffe307d3b86c2c06251c6a5be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 11, 2026.

Transparency log

Release files / akousma-0.7.0-py3-none-any.whl

Download URL akousma-0.7.0-py3-none-any.whl
Size 23.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b071ab5de79156529425f72092daee0dae430fdf1bb9ca354d5082b0956c45cc
BLAKE2b-256 checksum
How to use checksums
4b73a6577b2d137c456b85cdf44c991952ee45f655f19399448184190e462d51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 11, 2026.

Transparency log

Security for akousma 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for akousma-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page