Implement the oída→germ receiving side of the akousma bridge

- GET /import?akousma=<id>&mode=sound|prompt|lineage — the three buttons land:
  'sound' imports the record's audio into germ's library through the standard
  audio-import flow (lineage metadata preserved, germ.import extension stamped
  back onto the shared record); 'prompt' derives a generation prompt from the
  listening block (preferred namespaces akouo.describe > oida.moss > oida.signal);
  'lineage' serves a self-contained lineage-explorer page (record, parents,
  children, ancestry, listen-with-oída link).
- JSON surface: GET /akousma/record/{id}, GET /akousma/lineage/{id},
  POST /akousma/generation (writes a germ akousma with parent lineage; the
  audio stays in place via file:// uri + content hash).
- server/akousma_store.py: lazy shared-store access (AKOUSMATA_PATH honored at
  call time; 503 when the akousma package is absent), prompt derivation,
  record_generation helper for the pipeline.
- pyproject: akousma dep via [tool.uv.sources] (earworm/packages/py-akousma).
- docs/api_reference.md: all four routes documented (route-coverage gate).
- 7 new tests against an isolated temp store; full suite 105 passed; ruff clean.

Author: emeisazam

docs/api_reference.md

@@ -40,6 +40,44 @@ analysis, render, provenance, and retention records.
 When `persist=true`, the session JSON is written under `output/metadata/` and the
 response includes `session_file` plus the inline `session` object.
 
+## GET /import
+
+The oída→germ handoff (the three buttons). Query params: `akousma` (record id in the
+shared akousmata store), `mode` (`sound` | `prompt` | `lineage`), `format`
+(`html` default, or `json`). `sound` imports the record's audio into germ's library
+via the standard audio-import flow and stamps `extensions["germ.import"]` back onto
+the shared record; `prompt` derives a generation prompt from the record's listening
+block; `lineage` opens the lineage explorer (parents, children, ancestry).
+
+## GET /akousma/record/{akousma_id}
+
+Returns the raw akousma record from the shared store (404 if unknown, 503 if the
+`akousma` package is not installed).
+
+## GET /akousma/lineage/{akousma_id}
+
+Returns `{record, parents, children, ancestor_ids}` with parent/child records
+resolved from the shared store — the data behind the lineage explorer.
+
+## POST /akousma/generation
+
+Writes a germ generation into the shared store as a new akousma whose
+`lineage.parent_akousma_ids` point at its sources.
+
+```json
+{
+  "audio_path": "output/audio/example.wav",
+  "prompt": "make it metallic",
+  "model": "stable-audio-3",
+  "operation": "audio-to-audio",
+  "parent_akousma_ids": ["akm_..."],
+  "tags": ["metallic"]
+}
+```
+
+Unknown parent ids are rejected with 404; the response returns `akousma_id` plus the
+full record. The audio stays in place (referenced by `file://` uri + content hash).
+
 ## GET /huggingface/status
 
 Checks Hugging Face CLI auth for the gated Stable Audio 3 Python-provider weights.

pyproject.toml

@@ -6,6 +6,7 @@ readme = "README.md"
 license = "MPL-2.0"
 requires-python = ">=3.10"
 dependencies = [
+    "akousma>=0.1.0",
     "fastapi>=0.111.0",
     "httpx>=0.27.0",
     "pydantic>=2.7.0",
@@ -14,6 +15,9 @@ dependencies = [
     "uvicorn[standard]>=0.30.0",
 ]
 
+[tool.uv.sources]
+akousma = { path = "../earworm/packages/py-akousma", editable = true }
+
 [project.optional-dependencies]
 python-provider = [
     "stable-audio-3 @ git+https://github.com/Stability-AI/stable-audio-3.git",

server/akousma_store.py

@@ -0,0 +1,141 @@
+"""germ ↔ akousmata: access to the shared sonic-memory store.
+
+The akousma protocol (earworm/docs/akousma_spec_v1.md) gives every sound one memory
+record; the shared store (``~/Documents/SFL/akousmata``, ``$AKOUSMATA_PATH``) spans
+oída, germ, and algophony. germ reads records handed over by oída ("open as sound /
+prompt / explore lineage") and writes a new akousma for material it generates, with
+``lineage.parent_akousma_ids`` pointing at the sources.
+
+The ``akousma`` package is the Python reference implementation that lives in the
+earworm repo (``earworm/packages/py-akousma``). It is imported lazily so the server
+still boots without it; the routes degrade to 503.
+"""
+from __future__ import annotations
+
+from hashlib import sha256
+from pathlib import Path
+from typing import Any
+
+
+class AkousmaUnavailable(RuntimeError):
+    """The akousma reference package is not installed."""
+
+
+def _akousma():
+    try:
+        import akousma
+    except ModuleNotFoundError as exc:  # pragma: no cover - environment-dependent
+        raise AkousmaUnavailable(
+            "the 'akousma' package is not installed; "
+            "pip install -e <SFL>/earworm/packages/py-akousma"
+        ) from exc
+    return akousma
+
+
+def open_store():
+    """Open the shared akousmata store (honors AKOUSMATA_PATH at call time)."""
+    akousma = _akousma()
+    return akousma.AkousmataStore()
+
+
+def resolve_audio_path(store, record: dict[str, Any]) -> Path | None:
+    """Resolve a record's audio to a local file path (store object or file uri)."""
+    audio = record.get("audio") or {}
+    uri = str(audio.get("uri") or "")
+    if not uri:
+        return None
+    if uri.startswith("akousmata://"):
+        path = store.resolve_uri(uri)
+        return path if path and path.exists() else None
+    if uri.startswith("file://"):
+        path = Path(uri[len("file://"):])
+        return path if path.exists() else None
+    path = Path(uri).expanduser()
+    return path if path.is_absolute() and path.exists() else None
+
+
+_PROMPT_KEYS = ("summary", "caption", "description", "text", "prompt")
+_PREFERRED_NAMESPACES = ("akouo.describe", "oida.moss", "oida.signal")
+
+
+def derive_prompt(record: dict[str, Any]) -> str:
+    """Turn a record's listening block into a generation prompt for germ."""
+    listening = record.get("listening") or {}
+    fragments: list[str] = []
+
+    def collect(block: Any) -> None:
+        if isinstance(block, str) and block.strip():
+            fragments.append(block.strip())
+        elif isinstance(block, dict):
+            for key in _PROMPT_KEYS:
+                value = block.get(key)
+                if isinstance(value, str) and value.strip():
+                    fragments.append(value.strip())
+
+    for namespace in _PREFERRED_NAMESPACES:
+        collect(listening.get(namespace))
+    if not fragments:
+        for value in listening.values():
+            collect(value)
+            if fragments:
+                break
+
+    if not fragments:
+        tags = [str(t) for t in record.get("tags") or []]
+        if tags:
+            fragments.append(", ".join(tags))
+
+    seen: set[str] = set()
+    unique = [f for f in fragments if not (f in seen or seen.add(f))]
+    return ". ".join(unique[:2])
+
+
+def record_generation(
+    *,
+    audio_path: str | Path,
+    prompt: str = "",
+    model: str = "",
+    operation: str = "generate",
+    params: dict[str, Any] | None = None,
+    parent_akousma_ids: list[str] | None = None,
+    listening: dict[str, Any] | None = None,
+    tags: list[str] | None = None,
+    extensions: dict[str, Any] | None = None,
+    store=None,
+) -> dict[str, Any]:
+    """Write a germ generation into the shared store as a new akousma.
+
+    The audio stays where germ wrote it (referenced by ``file://`` uri +
+    content hash); lineage points at the source akousmata.
+    """
+    akousma = _akousma()
+    path = Path(audio_path).expanduser().resolve()
+    data = path.read_bytes()
+
+    owns_store = store is None
+    store = store or open_store()
+    try:
+        record = akousma.new_akousma(
+            audio={
+                "asset_id": path.stem,
+                "type": "generation",
+                "uri": f"file://{path}",
+                "content_hash": f"sha256:{sha256(data).hexdigest()}",
+            },
+            originating_app="germ",
+            source_type="generated",
+            origin="generated",
+            listening=listening,
+            parent_akousma_ids=parent_akousma_ids or [],
+            operation=operation,
+            prompt=prompt or None,
+            model=model or None,
+            params=params,
+            tags=tags,
+            extensions=extensions,
+        )
+        store.put(record)
+        return record
+    finally:
+        if owns_store:
+            store.close()

server/main.py

@@ -9,6 +9,7 @@
 from server.config import get_settings
 from server.identity import LEGACY_ENGINE_NAME, PRODUCT_DESCRIPTION, PRODUCT_NAME
 from server.routes import (
+    akousma,
     audio_tools,
     audio_to_audio,
     continue_audio,
@@ -69,6 +70,7 @@
 app.include_router(health.router)
 app.include_router(diagnostics.router)
 app.include_router(earworm.router)
+app.include_router(akousma.router)
 app.include_router(huggingface.router)
 app.include_router(models.router)
 app.include_router(performance.router)