Skip to content

Commit 64a19cf

Browse files
emeisazamemeisazam
committed
docs: document MOSS-Audio agentic setup
1 parent 75f82e1 commit 64a19cf

4 files changed

Lines changed: 155 additions & 11 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,18 @@
22

33
> **Public alpha · Open research release · Local-first · Open-source · Under active development**
44
5-
Oída is a local listening instrument for sound files, microphones, and system
6-
audio. It combines deterministic signal analysis with optional audio models,
7-
keeps observation separate from interpretation, and can remember a listening
8-
only when asked. A sound can enter Oída, become an inspectable listening event,
9-
pass into GERM as material or lineage, enter Akousmata as memory, and be heard
10-
again without erasing the earlier account.
5+
Oída is a local listening instrument and agentic gateway for sound files,
6+
microphones, and system audio. It combines deterministic signal analysis with
7+
optional audio models, keeps observation separate from interpretation, and can
8+
remember a listening only when asked. A sound can enter Oída, become an
9+
inspectable listening event, pass into GERM as material or lineage, enter
10+
Akousmata as memory, and be heard again without erasing the earlier account.
11+
12+
Oída's owned model path is developed and tested first with the open-source
13+
MOSS-Audio Instruct and Thinking checkpoints. Those local models are the
14+
recommended starting point for model-backed exploration. The gateway contract
15+
remains model-agnostic, the deterministic path needs no model, and hosted
16+
providers are never enabled by default.
1117

1218
![Oída dashboard showing a model-free signal listening](docs/assets/oida-dashboard.png)
1319

@@ -42,7 +48,8 @@ still performs deterministic DSP; it does not invent a semantic caption.
4248
| Path | Operating system | Hardware and software |
4349
| --- | --- | --- |
4450
| Model-free service | macOS or Linux | Python 3.12+, `uv`; CPU only; `ffmpeg` for non-WAV input and browser recording |
45-
| Embedded MOSS-Audio | Apple Silicon macOS | Local MOSS-Audio code and weights, PyTorch/MPS, and sufficient unified memory for the selected checkpoint |
51+
| Embedded MOSS-Audio 4B | Apple Silicon macOS | Local MOSS-Audio code and weights, PyTorch/MPS; 16 GB minimum and 24 GB unified memory suggested |
52+
| Embedded MOSS-Audio 8B | Apple Silicon macOS | Local MOSS-Audio code and weights; 24 GB minimum and 48 GB unified memory suggested |
4653
| CUDA service | Operator-managed Linux/NVIDIA host | A separately running compatible MOSS-Audio SGLang endpoint |
4754
| Native shell and system audio | macOS 13+ | Swift 5.9/Xcode command-line tools; Screen Recording permission for system output |
4855

@@ -56,6 +63,7 @@ instead of promising one universal RAM minimum.
5663
| --- | --- |
5764
| How does it work? | [Architecture](docs/architecture.md) and [gateway contract](docs/gateway-contract.md) |
5865
| How does it connect? | [The Listening Stack](https://sonicfield.org/stack) and [GERM handoff](#stack-compatibility) |
66+
| How do I install the tested models? | [MOSS-Audio setup](docs/model-setup.md) |
5967
| Which models and licenses apply? | [Models and licensing](docs/models-and-licensing.md) |
6068
| What is unfinished? | [Known limitations](#known-limitations) and [roadmap](ROADMAP.md) |
6169
| How can I help? | [Contribution guide](CONTRIBUTING.md) |
@@ -208,6 +216,18 @@ and cultivation.
208216

209217
## Quick Start
210218

219+
For a guided Oída or complete Listening Stack installation, including host
220+
checks, model choices, storage guidance, downloads, and optional agent
221+
integrations, use the separate installer:
222+
223+
```bash
224+
curl -fsSL https://raw.githubusercontent.com/sonicfieldlabs/listening-stack/main/install.sh | bash
225+
```
226+
227+
Choose **Oída only** or **Oída + GERM** in the terminal assistant. Oída remains
228+
in this repository; the installer only coordinates its source, dependencies,
229+
models, and local configuration.
230+
211231
Prerequisites: Python 3.12+, `uv`, and `ffmpeg` for non-WAV uploads or browser
212232
recordings. From this source workspace, one sync installs Oída together with
213233
the canonical AKOÚŌ, Earworm/akousma, and Akousmata packages:
@@ -333,7 +353,8 @@ analyzed, as a temporary WAV under the audio dir, and is cleaned by the
333353
## Engine Profiles
334354

335355
The `mac-mps` adapter expects the official MOSS-Audio repository and local
336-
weights. `scripts/run_oida_mps.sh` sets the environment and starts the daemon:
356+
weights. Follow [MOSS-Audio setup](docs/model-setup.md) for exact checkpoint
357+
downloads. `scripts/run_oida_mps.sh` sets the environment and starts the daemon:
337358

338359
```bash
339360
export OIDA_MOSS_AUDIO_REPO="$PWD/MOSS-Audio"
@@ -441,6 +462,8 @@ promising production stability.
441462
integration boundaries.
442463
- `docs/reasoning-providers.md` — prompt ownership, provider setup, model roles,
443464
evidence boundaries, and host prepare/commit flow.
465+
- `docs/model-setup.md` — exact MOSS-Audio downloads, hardware planning,
466+
configuration, and verification.
444467
- `docs/models-and-licensing.md` — model attribution, installation boundaries,
445468
and third-party terms.
446469
- `ROADMAP.md` — current public-alpha priorities and non-goals.

‎docs/model-setup.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# MOSS-Audio Setup
2+
3+
Oída is usable without a model. Begin with `--profile stub` when validating the
4+
gateway, dashboard, deterministic signal listener, MCP surface, or agent host
5+
integration.
6+
7+
The first model-backed path developed and tested for Oída uses the open-source
8+
MOSS-Audio Instruct and Thinking checkpoints. The gateway remains
9+
model-agnostic, and no hosted provider is enabled by this setup.
10+
11+
## Guided Installation
12+
13+
The Listening Stack assistant checks the host, shows current model sizes,
14+
downloads selected checkpoints, keeps them outside Git, configures Oída, and
15+
can install its agent adapters:
16+
17+
```bash
18+
curl -fsSL https://raw.githubusercontent.com/sonicfieldlabs/listening-stack/main/install.sh | bash
19+
```
20+
21+
Choose **Oída only** or **Oída + GERM**. The recommended Oída selection is
22+
MOSS-Audio 4B Instruct plus 4B Thinking.
23+
24+
## Manual Installation
25+
26+
From the Oída repository:
27+
28+
```bash
29+
git clone https://github.com/OpenMOSS/MOSS-Audio.git MOSS-Audio
30+
uv sync --locked --extra moss
31+
32+
uv run hf download OpenMOSS-Team/MOSS-Audio-4B-Instruct \
33+
--local-dir weights/MOSS-Audio-4B-Instruct
34+
uv run hf download OpenMOSS-Team/MOSS-Audio-4B-Thinking \
35+
--local-dir weights/MOSS-Audio-4B-Thinking
36+
```
37+
38+
The released MOSS-Audio checkpoints are public Apache-2.0 downloads. A Hugging
39+
Face login is not normally needed for these four repositories. Review the
40+
exact upstream model card before use.
41+
42+
For the larger pair:
43+
44+
```bash
45+
uv run hf download OpenMOSS-Team/MOSS-Audio-8B-Instruct \
46+
--local-dir weights/MOSS-Audio-8B-Instruct
47+
uv run hf download OpenMOSS-Team/MOSS-Audio-8B-Thinking \
48+
--local-dir weights/MOSS-Audio-8B-Thinking
49+
```
50+
51+
The Hugging Face API currently reports approximately 10.45 GB for each 4B
52+
repository and 18.11 GB for each 8B repository. Leave additional space for
53+
Python, PyTorch, the MOSS-Audio source, and download metadata.
54+
55+
## Configure Oída
56+
57+
```bash
58+
export OIDA_MOSS_AUDIO_REPO="$PWD/MOSS-Audio"
59+
export OIDA_MOSS_INSTRUCT_MODEL="$PWD/weights/MOSS-Audio-4B-Instruct"
60+
export OIDA_MOSS_THINKING_MODEL="$PWD/weights/MOSS-Audio-4B-Thinking"
61+
export OIDA_MOSS_RESIDENT=single
62+
export OIDA_REQUIRE_MODEL=1
63+
```
64+
65+
For 8B, change the two checkpoint paths. When only one checkpoint is available,
66+
the same path may be assigned to both routes; the split pair gives Oída the
67+
intended direct and deep-listening roles.
68+
69+
`OIDA_MOSS_RESIDENT=single` keeps only one checkpoint resident and hot-swaps
70+
between them. This is the safer default on unified-memory systems.
71+
72+
## Hardware Planning
73+
74+
| Checkpoint family | Minimum RAM | Suggested RAM | Approx. repository size |
75+
| --- | ---: | ---: | ---: |
76+
| MOSS-Audio 4B | 16 GB | 24 GB | 10.45 GB each |
77+
| MOSS-Audio 8B | 24 GB | 48 GB | 18.11 GB each |
78+
79+
These are Oída planning figures, not upstream guarantees. Apple Silicon MPS is
80+
the current embedded release target. The engine can discover CUDA or CPU, but
81+
the documented CUDA deployment uses the separately managed MOSS-Audio SGLang
82+
route and CPU inference can be slow.
83+
84+
## Verify
85+
86+
```bash
87+
uv run oida doctor
88+
uv run oida start --profile mac-mps
89+
curl http://127.0.0.1:8765/engine/status
90+
```
91+
92+
The engine is ready when the status identifies the selected local checkpoint
93+
and a supported device. The dashboard can then run **General** for an Instruct
94+
pass and **Deep** or **Music** for a Thinking pass.
95+
96+
Oída refuses silent Hub lookup by default. `HF_HUB_OFFLINE=1` disables it even
97+
when another setting attempts to enable it. Model paths, weights, listening
98+
history, captures, credentials, and local machine configuration are ignored by
99+
Git and must remain outside commits and public issues.

‎docs/models-and-licensing.md‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,36 @@ recordings, provider services, or generated material.
1515

1616
The embedded `mac-mps` and external `cuda-server` paths integrate with
1717
[MOSS-Audio](https://github.com/OpenMOSS/MOSS-Audio), developed by the
18-
OpenMOSS team. The official
19-
[MOSS-Audio-4B-Instruct model card](https://huggingface.co/OpenMOSS-Team/MOSS-Audio-4B-Instruct)
20-
identifies Apache-2.0 terms for that release.
18+
OpenMOSS team. Oída's current embedded path is developed and tested first with
19+
the four released MOSS-Audio checkpoints:
20+
21+
- [MOSS-Audio 4B Instruct](https://huggingface.co/OpenMOSS-Team/MOSS-Audio-4B-Instruct)
22+
- [MOSS-Audio 4B Thinking](https://huggingface.co/OpenMOSS-Team/MOSS-Audio-4B-Thinking)
23+
- [MOSS-Audio 8B Instruct](https://huggingface.co/OpenMOSS-Team/MOSS-Audio-8B-Instruct)
24+
- [MOSS-Audio 8B Thinking](https://huggingface.co/OpenMOSS-Team/MOSS-Audio-8B-Thinking)
25+
26+
The official repository and these model cards identify Apache-2.0 terms for
27+
the released code and checkpoints. The Instruct variants are used for direct
28+
listening and transcription routes. Thinking variants support deeper,
29+
music-focused, and targeted re-listening routes. Oída consumes their final
30+
response as bounded evidence; it does not expose private reasoning traces.
31+
32+
The 4B pair is the recommended local starting point. Oída's public-alpha
33+
planning guidance is 16 GB minimum and 24 GB suggested for 4B, or 24 GB
34+
minimum and 48 GB suggested for 8B. Actual memory and speed vary with device,
35+
audio duration, precision, and resident-model policy.
2136

2237
Oída does not redistribute MOSS-Audio code or weights and does not download
2338
them silently. Install the exact upstream release yourself, read its model
2439
card and license at the time of use, and record the chosen model identifier in
2540
research or publication metadata. Upstream terms remain authoritative if they
2641
change or differ between checkpoints.
2742

43+
See [MOSS-Audio setup](model-setup.md) for the exact manual downloads and the
44+
[Listening Stack installer](https://github.com/sonicfieldlabs/listening-stack)
45+
for the guided route. The installer keeps weights outside Git and records
46+
local paths without placing credentials in repository files.
47+
2848
## Other Local, Hosted, and Host Models
2949

3050
The dashboard catalog and gateway can connect to operator-managed local audio

‎uv.lock‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)