marimba-audio 0.1.0__tar.gz

marimba_audio-0.1.0/.dockerignore

@@ -0,0 +1,11 @@
+**
+!pyproject.toml
+!README.md
+!LICENSE
+!THIRD_PARTY_NOTICES.md
+!src/
+!src/**
+!.runpod/
+!.runpod/handler.py
+**/__pycache__/
+**/*.pyc

marimba_audio-0.1.0/.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,json,md}]
+indent_style = space
+indent_size = 2

marimba_audio-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @solanovisitor

marimba_audio-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns:
+          - "*"

marimba_audio-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,6 @@
+## Checklist
+
+- [ ] Tests and checks have been run.
+- [ ] Documentation has been updated.
+- [ ] Only public or synthetic data is included.
+- [ ] No internal names, non-public identifiers, or secrets are included.

marimba_audio-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - run: uv sync --locked --extra datasets --extra pipecat --group dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - run: uv run pytest -q
+      - run: uv build

marimba_audio-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          enable-cache: false
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/marimba-audio
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

marimba_audio-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,62 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  zizmor:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: zizmorcore/zizmor-action@53290badfa369cb0bf7ad16342cb62c2fa47ac7b # v0.8.0
+        with:
+          advanced-security: false
+          annotations: true
+          min-severity: high
+          version: 1.29.0
+
+  gitleaks:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Run Gitleaks
+        env:
+          GITLEAKS_VERSION: 8.21.2
+          GITLEAKS_SHA256: 5bc41815076e6ed6ef8fbecc9d9b75bcae31f39029ceb55da08086315316e3ba
+        run: |
+          curl --fail --silent --show-error --location \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
+            --output gitleaks.tar.gz
+          printf '%s  gitleaks.tar.gz\n' "$GITLEAKS_SHA256" | sha256sum --check
+          tar -xzf gitleaks.tar.gz gitleaks
+          ./gitleaks git . --log-opts=HEAD --redact --no-banner --exit-code 1
+
+  public-text:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Check public text
+        env:
+          PUBLIC_CHECK_TERMS: ${{ secrets.PUBLIC_CHECK_TERMS }}
+        run: python3 scripts/check_public.py

marimba_audio-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+
+# Node
+node_modules/
+.next/
+
+# Environment and local checks
+.env*
+.public-check-terms
+
+# Audio and model artifacts
+*.wav
+*.flac
+*.mp3
+*.pt
+*.safetensors
+*.onnx
+
+# OS
+.DS_Store

marimba_audio-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff check
+        entry: uv run --with ruff ruff check
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: Ruff format
+        entry: uv run --with ruff ruff format --check
+        language: system
+        types: [python]
+      - id: public-text-check
+        name: Public text check
+        entry: python3 scripts/check_public.py
+        language: system
+        pass_filenames: false
+        always_run: true
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks:
+      - id: gitleaks

marimba_audio-0.1.0/.runpod/Dockerfile

@@ -0,0 +1,16 @@
+FROM runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404
+
+ENV HF_HUB_ENABLE_HF_TRANSFER=0 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# The base image's Debian cryptography installation has no pip RECORD.
+RUN python -m pip install --no-cache-dir --ignore-installed cryptography
+
+COPY pyproject.toml README.md LICENSE THIRD_PARTY_NOTICES.md ./
+COPY src/ ./src/
+RUN python -m pip install --no-cache-dir '.[torch]' 'runpod==1.8.1'
+
+COPY .runpod/handler.py ./handler.py
+CMD ["python", "-u", "/app/handler.py"]

marimba_audio-0.1.0/.runpod/README.md

@@ -0,0 +1,192 @@
+# Marimba decoder worker
+
+This Runpod Serverless worker answers Language and Term questions on a CUDA GPU.
+It loads Marimba once with the Torch backend and calls `decide_snapshot` without
+changing the package's inference path. Term detection retains greedy decoding
+plus four beam hypotheses. Encoder questions stay on the client.
+
+## Container and environment
+
+Build from the repository root:
+
+```sh
+docker build -f .runpod/Dockerfile -t marimba-decoder:local .
+docker run --rm --gpus all --env HF_TOKEN marimba-decoder:local
+```
+
+`HF_TOKEN` is an optional Hugging Face read token, required only while model
+access requires authentication. Pass it at runtime; never bake it into an image
+or put its value in Hub metadata. `HF_HUB_ENABLE_HF_TRANSFER=0` is set in the image
+because the base image enables an optional transfer package it does not install.
+The worker uses the package's default model and pinned revision.
+
+The Hub configuration selects one GPU from the 24 GB or larger `ADA_24` and
+`AMPERE_48` pools, a 30 GB container disk, and CUDA 12.8. Model files download at
+startup into the Hugging Face cache; startup requires network and model access.
+The Hub smoke test uses one second of synthetic silence and a Language question
+on an RTX 4090. It checks execution, not language accuracy on silence.
+
+The files follow the [Runpod Hub publishing guide](https://docs.runpod.io/hub/publishing-guide).
+Hub publication is a separate step: it requires accessible source and model
+artifacts and a GitHub release. Adding these files does not publish a repository,
+model, image, release, or Hub listing.
+
+## Request
+
+Send a Runpod job with an `input` object:
+
+```json
+{
+  "input": {
+    "lane": "decoder",
+    "sample_rate": 16000,
+    "pcm16_b64": "BASE64_PCM16_LE",
+    "mask_b64": "BASE64_UINT8_MASK",
+    "window_start_s": 0.0,
+    "window_end_s": 1.0,
+    "questions": [
+      {
+        "text": "What language is being spoken?",
+        "kind": "choice",
+        "options": ["English", "Portuguese"],
+        "task": "language",
+        "threshold": 0.5
+      }
+    ]
+  }
+}
+```
+
+`pcm16_b64` encodes mono, signed, little-endian PCM16 at 16 kHz. `mask_b64`
+encodes one byte per sample: zero for padding, one for valid audio (including
+silence). Both arrays must have the same nonzero sample count, at most 30 seconds,
+and at least one sample must be valid. Timestamps are finite seconds with
+`0 <= window_start_s <= window_end_s`. Audio may include left padding, so the
+valid interval can be shorter than the array duration.
+
+Questions are serialized with `dataclasses.asdict(Question(...))`; JSON options
+are restored to tuples. Only `language` and `term` tasks are supported. A Term
+example is `Question.noul('Did someone say "hello"?')`. Encoder questions and
+other tasks are rejected before loading the GPU model. Invalid inputs fail the
+Runpod job rather than producing decisions.
+
+## Response
+
+On success, Runpod's response has `status: "COMPLETED"` and an `output` object:
+
+```json
+{
+  "decisions": [
+    {
+      "question": {
+        "text": "What language is being spoken?",
+        "kind": "choice",
+        "options": ["English", "Portuguese"],
+        "task": "language",
+        "threshold": 0.5
+      },
+      "task": "language",
+      "kind": "choice",
+      "value": "English",
+      "probability": null,
+      "probabilities": {"English": 0.8, "Portuguese": 0.2},
+      "score": null,
+      "threshold": 0.5,
+      "window_start_s": 0.0,
+      "window_end_s": 1.0,
+      "latency_ms": 0.0,
+      "status": "ok",
+      "calibrated": false
+    }
+  ],
+  "gpu_compute_ms": 0.0
+}
+```
+
+The values above illustrate the schema, not a prediction for the synthetic test.
+Decisions are returned in question order using `Decision.to_dict()`.
+`gpu_compute_ms` times the synchronized `decide_snapshot` call, excluding model
+loading, payload decoding, and network time.
+
+## Client usage
+
+Install the repository package with its `torch` extra on the client. Set
+`RUNPOD_ENDPOINT_ID` and `RUNPOD_API_KEY` in the client's environment. The API key
+authenticates calls to Runpod; it is separate from the worker's `HF_TOKEN`.
+The following example creates synthetic silence, keeps voice activity on CPU,
+and sends only Language and Term questions to the decoder endpoint:
+
+```python
+import base64
+import json
+import os
+from dataclasses import asdict
+from urllib.request import Request, urlopen
+
+import numpy as np
+from marimba import Marimba, Question, WindowSnapshot
+
+local = Marimba.from_pretrained(device="cpu", backend="torch")
+snapshot = WindowSnapshot(
+    np.zeros(8 * 16000, dtype=np.float32),
+    np.ones(8 * 16000, dtype=np.bool_),
+    0.0,
+    8.0,
+)
+questions = [
+    Question.score("Is someone speaking?"),
+    Question.choice("What language is being spoken?", ["English", "Portuguese"]),
+    Question.noul('Did someone say "hello"?'),
+]
+encoder_questions = [q for q in questions if local.lane(q) == "encoder"]
+decoder_questions = [q for q in questions if local.lane(q) == "decoder"]
+if any(q.task not in ("language", "term") for q in decoder_questions):
+    raise ValueError("The remote worker supports Language and Term only")
+local_decisions = local.decide_encoded(local.encode(snapshot), encoder_questions)
+
+pcm16 = np.clip(np.rint(snapshot.audio.astype(np.float64) * 32768), -32768, 32767)
+payload = {
+    "input": {
+        "lane": "decoder",
+        "sample_rate": 16000,
+        "pcm16_b64": base64.b64encode(pcm16.astype("<i2").tobytes()).decode("ascii"),
+        "mask_b64": base64.b64encode(snapshot.mask.astype(np.uint8).tobytes()).decode("ascii"),
+        "window_start_s": snapshot.window_start_s,
+        "window_end_s": snapshot.window_end_s,
+        "questions": [asdict(q) for q in decoder_questions],
+    }
+}
+endpoint = os.environ["RUNPOD_ENDPOINT_ID"]
+request = Request(
+    f"https://api.runpod.ai/v2/{endpoint}/runsync",
+    data=json.dumps(payload).encode("utf-8"),
+    headers={
+        "Authorization": "Bearer " + os.environ["RUNPOD_API_KEY"],
+        "Content-Type": "application/json",
+        "User-Agent": "marimba-decoder-client/0.1",
+    },
+    method="POST",
+)
+with urlopen(request, timeout=300) as response:
+    result = json.load(response)
+if result.get("status") != "COMPLETED":
+    raise RuntimeError(f"Runpod job {result.get('id')} status: {result.get('status')}")
+output = result["output"]
+print([d.to_dict() for d in local_decisions])
+print(output["decisions"], output["gpu_compute_ms"])
+```
+
+For an existing stream, serialize its `WindowSnapshot` in the same way; keep
+encoder inference local. A synchronous request may return `IN_QUEUE` or
+`IN_PROGRESS`. In that case, retain the job ID and use the
+[Runpod status endpoint](https://docs.runpod.io/serverless/endpoints/send-requests)
+to retrieve that job instead of submitting duplicate work. Never print API keys
+or authorization headers.
+
+## Prior validation
+
+CPU and GPU parity matched for Language and Term in prior validation. On an
+RTX 4090, measured median round-trip latency was 663 ms for Language and 1639 ms
+for Term; worker GPU compute was 115 ms and 1108 ms, respectively. These are
+observations from that validation, not latency guarantees or results of the
+synthetic Hub smoke test.

marimba_audio-0.1.0/.runpod/handler.py

@@ -0,0 +1,108 @@
+"""Runpod Serverless worker for Language and Term decoder questions."""
+
+from __future__ import annotations
+
+import base64
+import logging
+import time
+from functools import cache
+from typing import Any
+
+import numpy as np
+
+from marimba import Marimba, Question, WindowSnapshot
+from marimba.windows import MAX_DECODER_SECONDS
+
+logger = logging.getLogger("marimba-runpod")
+
+
+@cache
+def _load_model() -> Marimba:
+    import torch
+
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is not available in the worker container")
+    torch.set_float32_matmul_precision("highest")
+    torch.backends.cuda.matmul.allow_tf32 = False
+    torch.backends.cudnn.allow_tf32 = False
+    logger.info("Loading Marimba decoder model on CUDA")
+    model = Marimba.from_pretrained(device="cuda", backend="torch")
+    logger.info("Marimba decoder model is ready")
+    return model
+
+
+def _snapshot(data: dict[str, Any]) -> WindowSnapshot:
+    if data.get("sample_rate") != 16000:
+        raise ValueError("Expected 16000 Hz PCM")
+    audio_bytes = base64.b64decode(data["pcm16_b64"], validate=True)
+    mask_bytes = base64.b64decode(data["mask_b64"], validate=True)
+    if len(audio_bytes) % 2:
+        raise ValueError("PCM16 payload has an odd byte count")
+
+    pcm = np.frombuffer(audio_bytes, dtype="<i2")
+    mask = np.frombuffer(mask_bytes, dtype=np.uint8)
+    if len(pcm) != len(mask):
+        raise ValueError("PCM and mask lengths differ")
+    if not 0 < len(pcm) <= 16000 * MAX_DECODER_SECONDS or not mask.any():
+        raise ValueError("Decoder snapshots require valid audio and at most 30 seconds")
+    if not np.isin(mask, [0, 1]).all():
+        raise ValueError("Mask bytes must be zero or one")
+
+    return WindowSnapshot(
+        pcm.astype(np.float32) / 32768.0,
+        mask.astype(np.bool_),
+        float(data["window_start_s"]),
+        float(data["window_end_s"]),
+    )
+
+
+def _questions(values: list[dict[str, Any]]) -> list[Question]:
+    result = []
+    for value in values:
+        question = dict(value)
+        if question.get("options") is not None:
+            question["options"] = tuple(question["options"])
+        parsed = Question(**question)
+        if parsed.task not in ("language", "term"):
+            raise ValueError("The remote worker accepts Language and Term questions only")
+        result.append(parsed)
+    if not result:
+        raise ValueError("At least one decoder question is required")
+    return result
+
+
+def handler(job: dict[str, Any]) -> dict[str, Any]:
+    data = job["input"]
+    if data.get("lane") != "decoder":
+        raise ValueError("The remote worker accepts decoder-lane requests only")
+
+    snapshot = _snapshot(data)
+    questions = _questions(data["questions"])
+    model = _load_model()
+    if any(model.lane(question) != "decoder" for question in questions):
+        raise ValueError("The remote worker accepts decoder questions only")
+
+    import torch
+
+    torch.cuda.synchronize()
+    started = time.perf_counter()
+    decisions = model.decide_snapshot(snapshot, questions)
+    torch.cuda.synchronize()
+    compute_ms = (time.perf_counter() - started) * 1000
+
+    return {
+        "decisions": [decision.to_dict() for decision in decisions],
+        "gpu_compute_ms": compute_ms,
+    }
+
+
+def main() -> None:
+    import runpod
+
+    logging.basicConfig(level=logging.INFO)
+    _load_model()
+    runpod.serverless.start({"handler": handler})
+
+
+if __name__ == "__main__":
+    main()

marimba_audio-0.1.0/.runpod/hub.json

@@ -0,0 +1,26 @@
+{
+  "title": "Marimba Decoder",
+  "description": "Language identification and term detection from audio with Marimba.",
+  "type": "serverless",
+  "category": "audio",
+  "config": {
+    "runsOn": "GPU",
+    "gpuCount": 1,
+    "gpuIds": "ADA_24,AMPERE_48",
+    "containerDiskInGb": 30,
+    "allowedCudaVersions": ["12.8"],
+    "env": [
+      {
+        "key": "HF_TOKEN",
+        "input": {
+          "name": "Hugging Face token",
+          "type": "string",
+          "description": "Optional read token, needed only when model access requires authentication.",
+          "default": "",
+          "required": false,
+          "advanced": true
+        }
+      }
+    ]
+  }
+}