Metadata-Version: 2.4
Name: akousmata
Version: 0.6.1
Summary: The listening navigator: a local-first library app over the shared akousmata store of sonic memories.
Project-URL: Homepage, https://github.com/sonicfieldlabs/akousmata
Project-URL: Repository, https://github.com/sonicfieldlabs/akousmata
Project-URL: Issues, https://github.com/sonicfieldlabs/akousmata/issues
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: akousma>=0.6.1
Requires-Dist: fastapi>=0.139
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: uvicorn>=0.29
Provides-Extra: dev
Requires-Dist: httpx2>=2.7; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: jsonschema>=4.21; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# akousmata — the listening navigator

**akousma** (ἄκουσμα, "a thing heard"; plural **akousmata**) — one sound's
memory. **Earworm is the protocol, the akousma is the shared record, the
akousmata is the whole library**: a network of listened things and their
relations. This app is how you walk it — navigating sonic memories, not audio
files.

The akousmata stores what agents listen (oída's ears, algophony's
evaluations, germ's cultivations) **and what you listen**: manual
human listening events live in the same library, with the listener declared.
Every memory carries provenance and causal lineage ("made from") plus typed
kinship ("belongs with"): variants, recurrences, series, responses. A heard
memory carries attributable listenings; a gate that closed before hearing can
instead carry a decision-only auditum without pretending that sound occurred.

Current release: `0.6.1`.

## What it is

A local-first library app over the shared akousmata store. It loads **no
models and runs no agents** — it is the quiet room of the Listening Stack:

- **Library** — filter by app, origin, tag, text, time; play resolvable
  audio; edit tags, notes, and summaries; add manual memories (heard live or
  from a file, which is content-addressed into the store); forget with a
  content-free durable receipt that leaves absence visible without retaining
  the forgotten description.
- **Graph** — the memory system as a navigable graph: solid edges are
  lineage, dashed edges are kinship, colors are originating apps.
- **Map** — the listening map: where listenings happened, not where sounds
  live. A hand-rolled Web-Mercator canvas (embedded Natural Earth coastlines,
  no map library) with clustering and click-through to the library; an OSM
  street-tile layer exists behind an explicit opt-in and is the only remote
  call the UI can make. Locations are consent-scoped (spec v1.2), editable
  from each record's "place" section, and always stripped from export packs.
- **Constellations** — saved, ordered graph selections that remain playable
  as soundwalks; forgotten members stay visible as meaningful absences.
- **Timeline** — day, month, calendar-season, and year views plus weekday/hour
  recurrence rhythms. Calendar seasons are organizational labels, never
  ecological claims.
- **Kin search** — accountable similarity from tags, description overlap,
  duration, stored DSP features, and optional already-computed local
  embeddings. The navigator never calls a remote embedding service.
- **Listening diary** — quick human capture with one maintained wiki digest
  per day.
- **Consent and export** — an audit of consent, rights notes, and capture
  conditions; restricted or unknown records are blocked from sanitized,
  manifest-bearing research packs.
- **Covenants (spec v1.3)** — records made under a listening covenant say so:
  the detail pane shows under which ethics a sound was listened (the
  covenant's identity and lineage, the rules that acted, what was withheld —
  counted and attributed, never described — and the commitments it carries),
  and one click filters the library to everything heard under that covenant.
  The navigator displays sovereignty; it never edits it.
- **Accountable auditums (spec v1.5)** — cards, detail pages, the wiki, graph,
  and Audit view expose each attributable listener and route, temporal-pass
  and provenance references, preserved disagreement, honest absences, action
  authority, route decisions, receipts, and revisions. A refusal before
  hearing is rendered as a decision-only memory with no audio or acoustic
  claim. Legacy v1.x records remain valid and are named as legacy, not
  defective.
- **Plural listening and declared ear swarms** — several listeners stay
  distinct by default. The navigator uses “ear swarm” only for an explicit
  ensemble that records influence, preserved permissions and disagreements,
  and a dissolution rule; listener count alone never manufactures consensus.
- **Listen again** — a record with resolvable audio can make a fresh pass
  through the Oída gateway; the new claims, routes, apparatus, and summary are
  filed as a new revision record that points to the earlier hearing. Re-listening
  never silently overwrites or mutates the account it revises.
- **Wiki** — an LLM-wiki (after Karpathy's llm-wiki pattern) forked into
  sonic memories: a maintained markdown layer over the records with one page
  per memory, per tag, plus topic syntheses; `index.md` catalog, `log.md`
  journal, and a lint pass for drift (dangling links, orphan pages, store
  integrity). Deterministic by default; see
  [`docs/concept.md`](docs/concept.md) and
  [`docs/wiki-conventions.md`](docs/wiki-conventions.md).
- **Research** — ask the library a question. Without an LLM it produces a
  deterministic traversal report (the graph already answers recurrence and
  kinship questions); with a BYOK provider it runs a bounded research loop
  and files the answer back as a topic page, so answers compound.
- **BYOK LLM** — optional: any OpenAI-compatible endpoint (OpenAI, xAI/Grok,
  OpenRouter, Ollama, llama.cpp), Anthropic, or a **local CLI agent**
  (codex, opencode — the prompt goes to stdin, nothing leaves your machine).
  Keys live in your local `settings.json`, never in the repo. CLI commands are
  parsed as an executable and arguments; use a wrapper script if you need shell
  pipelines or redirection.
- **Optional GERM handoff** — configure a local GERM URL to send a memory as
  sound, prompt, or lineage. With no URL configured, the library has no GERM
  dependency and shows no handoff controls.
- **Realtime** — the navigator watches the store; memories written by oída
  or germ appear as they happen.
- **Durable maintenance watcher** — immediately reconciles records created
  while the app was offline, persists a tie-safe cursor, refreshes diary
  digests, and runs scheduled lint. Intervals are live-editable in Settings.

## The store

By default the store data lives in the platform application-data directory
and is **never tracked**: `index.sqlite`, `objects/` (content-addressed
audio), `wiki/` (the maintained layer), and `settings.json`. Set
`AKOUSMATA_PATH` when the Listening Stack should share another location. The store API is
[`earworm/packages/py-akousma`](https://github.com/sonicfieldlabs/earworm)
(spec: `earworm/docs/akousma_spec_v1.md`) — this app is a navigator over
that protocol, not a fork of it.

## Listening Stack compatibility

| Component | Version / contract | Relationship |
| --- | --- | --- |
| [Earworm](https://github.com/sonicfieldlabs/earworm) | `akousma 0.6.1` / spec v1.5 | Canonical store and addressable auditum contract: decisions, lineage, attributable disagreement resolution, absence, forgetting receipts, ensembles, authority, and mechanically additive revision. |
| [AKOÚŌ](https://github.com/sonicfieldlabs/akouo) | `akouo/v0.9` | Owns claim taxonomy, provenance, temporal passes, route decisions, corpus disclosure, and situated context rendered by the navigator. |
| [OÍDA](https://github.com/sonicfieldlabs/oida) | 0.9.2 / `oida/gateway/v0.5` | Writes listening events v0.3 and decision-only route outcomes; produces additive re-listening revisions and embeds the navigator at `/library/`. |
| [GERM](https://github.com/sonicfieldlabs/germ) | 0.3.3 (optional) | Receives explicit sound, prompt, and lineage handoffs when separately configured. |
| [Algophony](https://github.com/sonicfieldlabs/algophony) | 0.5.2 | Adds batch evaluation stamps and comparison relations. |
| [ORAM](https://github.com/sonicfieldlabs/oram) | 0.4.1 | ORAM exports can enter the store through OÍDA or another akousma producer; ORAM is not a direct store writer. |

## Run

```sh
pip install -e .   # installs the canonical akousma dependency too
akousmata          # http://127.0.0.1:5180
```

Installing Oída installs and mounts this navigator at `/library/`; standalone
mode remains useful for library-only work. In the Sonic Field monorepo the
canonical sibling packages are editable. Tests: `uv run pytest -q`.

## The stack around it

- **oída** listens and remembers (and embeds this library view as its
  history); optional **GERM** can cultivate remembered sounds into new ones; **algophony**
  evaluates batches and stamps results back onto records; **AKOÚŌ** defines
  how everything listens. The akousmata is where all of it — and you —
  keep one shared memory.

## License

MIT. The store data is yours and never part of the repository.