audatron 0.1.0__tar.gz

audatron-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: audatron
+Version: 0.1.0
+Summary: audatron — LLM-driven realtime Audacity: natural language drives track editing, noise removal, and mastering, with a headless DSP engine plus auto-generated Audacity TCL scripts, an agent chat REPL, and an MCP stdio server.
+Author: DREAM PIXELS FORGE
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: soundfile>=0.12
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydub>=0.25
+Provides-Extra: noisereduce
+Requires-Dist: noisereduce>=3.0; extra == "noisereduce"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# audatron
+
+**Natural-language audio production, mirrored live into Audacity.**
+
+audatron is a realtime, LLM-driven toolchain: you prompt an agent (or any
+coding tool — Claude Code, Codex, opencode, kimi, pi, qwen code —) in plain
+English, and it drives a real Audacity workflow in your browser: inspect the
+waveform, trim tracks, strip noise, master to a target loudness, and export —
+while the matching Audacity project + TCL/Lua scripts are written so you can
+watch the edits land on the open project.
+
+```
+   you (natural language)
+        │
+        ▼
+   ┌──────────────────────────────┐
+   │  audatron agent (LLM loop)   │   ← Anthropic / OpenAI-compatible / Ollama
+   └──────────────────────────────┘
+        │  tool calls
+        ▼
+   ┌──────────────────────────────┐
+   │  DSP engine (headless)       │   ← trim / gain / normalize / noise / master / export
+   └──────────────────────────────┘
+        │  every step
+        ▼
+   ┌──────────────────────────────┐
+   │  Audacity bridge             │   ← .aup3 project + generated TCL + Lua scripts
+   └──────────────────────────────┘
+```
+
+## Install
+
+```bash
+pip install -e .
+audatron doctor        # verify numpy, ffmpeg, Audacity, LLM backends
+```
+
+## Quickstart
+
+```bash
+# 1. generate a test clip
+audatron demo demo.wav --freq 440 --seconds 3
+
+# 2. one-shot: natural language in, mastered wav out
+audatron run "trim to 2s, remove hiss, master to -14 LUFS, export wav" demo.wav --backend anthropic
+
+# 3. interactive REPL
+audatron chat demo.wav --backend anthropic
+#    you › make it sound like a radio
+#    you › sync          ← pushes the deck into a live Audacity project
+```
+
+### The LLM agent is optional
+
+Every operation the agent can perform is also available without an LLM:
+
+```bash
+audatron inspect demo.wav              # stats + spectral analysis
+audatron sync demo.wav                 # Audacity project + TCL/Lua, no LLM
+```
+
+## Audacity integration
+
+`audatron sync` writes:
+
+| File                        | Purpose                                            |
+|---------------------------|----------------------------------------------------|
+| `deck.wav`                 | clean copy of the current deck                     |
+| `<name>.aup3`             | Audacity 3.x XML project (fallback)               |
+| `<name>.native.aup3`     | **native Audacity 4 SQLite project** (primary)    |
+| `audatron.tcl`            | generated TCL script (run via Tools → Macros)     |
+| `audatron.lua`            | generated Lua script (Audacity 2.x scripting)      |
+| `audatron.json`           | machine-readable manifest of the ops               |
+
+The `.native.aup3` is a real SQLite database matching Audacity 4's
+on-disk format: four tables (`project`, `sampleblocks`, `autosave`,
+`project_history`), float32 sample blocks sized the way the app writes
+them (up to 262144 samples / 1 MiB), and the app's `dict`/`doc`
+record streams. It opens natively with the waveform + track layout
+intact, no external WAV side-file needed. The XML `.aup3` is kept as
+a fallback for older Audacity builds.
+
+Open it in your running Audacity 4:
+
+```
+"C:\Program Files\Audacity 4\bin\Audacity4.exe" <project>\river_master-proj.native.aup3
+```
+
+or let audatron launch it for you:
+
+```
+audatron sync river_master.wav --open-audacity    # opens the native project
+audatron sync river_master.wav --run-tcl          # + auto-runs the TCL macro
+```
+
+## MCP server
+
+audatron ships an MCP stdio server so **any** MCP-capable coding agent can
+drive it. The tools are the same DSP surface the CLI agent uses.
+
+```bash
+audatron-mcp        # newline-delimited JSON-RPC 2.0 over stdio
+```
+
+Wiring it into a coding agent — see **[dev-notes/MCP-SETUP.md](dev-notes/MCP-SETUP.md)** for
+Claude Code, Codex, opencode, kimi, qwen-code, and generic MCP clients.
+
+## Tool surface
+
+| Tool           | What it does |
+|----------------|--------------|
+| `inspect`      | sr, duration, peak, loudness dB, silence ratio |
+| `analyze`      | spectral centroid, onsets, silence ranges |
+| `trim`         | keep a `[start, end]` window |
+| `gain`         | apply ± dB |
+| `normalize`     | peak-normalize to a target dBFS |
+| `noise_reduce` | spectral-subtraction denoise (profile from head) |
+| `master`       | loudness-normalize to target LUFS + peak ceiling |
+| `export`       | write wav / flac / mp3 / ogg |
+| `sync`         | generate the Audacity project + scripts |
+| `history` / `undo` | deck state |
+| `load`         | replace the deck with a new file |
+
+## Development
+
+```bash
+pip install -e ".[test]"
+python -m pytest -q          # 102 tests, ~45s
+```
+
+Layout:
+
+```
+src/audatron/
+  dsp.py          # headless DSP engine (numpy + soundfile)
+  session.py      # stateful deck + op history
+  tools.py        # tool surface shared by CLI agent + MCP
+  agent.py        # LLM agent loop (Anthropic/OpenAI/Ollama)
+  backends.py     # LLM provider clients (+ streaming)
+  live.py         # realtime foreground view (token stream + waveform)
+  audacity.py     # .aup3 + TCL/Lua generation + Audacity lookup
+  aup3.py        # native Audacity-4 SQLite .aup3 writer
+  mcp_server.py   # MCP stdio JSON-RPC server
+  cli.py          # typer CLI
+tests/            # pytest: DSP, tools, agent (mocked), MCP, e2e, CLI, aup3, live
+```

audatron-0.1.0/README.md

@@ -0,0 +1,146 @@
+# audatron
+
+**Natural-language audio production, mirrored live into Audacity.**
+
+audatron is a realtime, LLM-driven toolchain: you prompt an agent (or any
+coding tool — Claude Code, Codex, opencode, kimi, pi, qwen code —) in plain
+English, and it drives a real Audacity workflow in your browser: inspect the
+waveform, trim tracks, strip noise, master to a target loudness, and export —
+while the matching Audacity project + TCL/Lua scripts are written so you can
+watch the edits land on the open project.
+
+```
+   you (natural language)
+        │
+        ▼
+   ┌──────────────────────────────┐
+   │  audatron agent (LLM loop)   │   ← Anthropic / OpenAI-compatible / Ollama
+   └──────────────────────────────┘
+        │  tool calls
+        ▼
+   ┌──────────────────────────────┐
+   │  DSP engine (headless)       │   ← trim / gain / normalize / noise / master / export
+   └──────────────────────────────┘
+        │  every step
+        ▼
+   ┌──────────────────────────────┐
+   │  Audacity bridge             │   ← .aup3 project + generated TCL + Lua scripts
+   └──────────────────────────────┘
+```
+
+## Install
+
+```bash
+pip install -e .
+audatron doctor        # verify numpy, ffmpeg, Audacity, LLM backends
+```
+
+## Quickstart
+
+```bash
+# 1. generate a test clip
+audatron demo demo.wav --freq 440 --seconds 3
+
+# 2. one-shot: natural language in, mastered wav out
+audatron run "trim to 2s, remove hiss, master to -14 LUFS, export wav" demo.wav --backend anthropic
+
+# 3. interactive REPL
+audatron chat demo.wav --backend anthropic
+#    you › make it sound like a radio
+#    you › sync          ← pushes the deck into a live Audacity project
+```
+
+### The LLM agent is optional
+
+Every operation the agent can perform is also available without an LLM:
+
+```bash
+audatron inspect demo.wav              # stats + spectral analysis
+audatron sync demo.wav                 # Audacity project + TCL/Lua, no LLM
+```
+
+## Audacity integration
+
+`audatron sync` writes:
+
+| File                        | Purpose                                            |
+|---------------------------|----------------------------------------------------|
+| `deck.wav`                 | clean copy of the current deck                     |
+| `<name>.aup3`             | Audacity 3.x XML project (fallback)               |
+| `<name>.native.aup3`     | **native Audacity 4 SQLite project** (primary)    |
+| `audatron.tcl`            | generated TCL script (run via Tools → Macros)     |
+| `audatron.lua`            | generated Lua script (Audacity 2.x scripting)      |
+| `audatron.json`           | machine-readable manifest of the ops               |
+
+The `.native.aup3` is a real SQLite database matching Audacity 4's
+on-disk format: four tables (`project`, `sampleblocks`, `autosave`,
+`project_history`), float32 sample blocks sized the way the app writes
+them (up to 262144 samples / 1 MiB), and the app's `dict`/`doc`
+record streams. It opens natively with the waveform + track layout
+intact, no external WAV side-file needed. The XML `.aup3` is kept as
+a fallback for older Audacity builds.
+
+Open it in your running Audacity 4:
+
+```
+"C:\Program Files\Audacity 4\bin\Audacity4.exe" <project>\river_master-proj.native.aup3
+```
+
+or let audatron launch it for you:
+
+```
+audatron sync river_master.wav --open-audacity    # opens the native project
+audatron sync river_master.wav --run-tcl          # + auto-runs the TCL macro
+```
+
+## MCP server
+
+audatron ships an MCP stdio server so **any** MCP-capable coding agent can
+drive it. The tools are the same DSP surface the CLI agent uses.
+
+```bash
+audatron-mcp        # newline-delimited JSON-RPC 2.0 over stdio
+```
+
+Wiring it into a coding agent — see **[dev-notes/MCP-SETUP.md](dev-notes/MCP-SETUP.md)** for
+Claude Code, Codex, opencode, kimi, qwen-code, and generic MCP clients.
+
+## Tool surface
+
+| Tool           | What it does |
+|----------------|--------------|
+| `inspect`      | sr, duration, peak, loudness dB, silence ratio |
+| `analyze`      | spectral centroid, onsets, silence ranges |
+| `trim`         | keep a `[start, end]` window |
+| `gain`         | apply ± dB |
+| `normalize`     | peak-normalize to a target dBFS |
+| `noise_reduce` | spectral-subtraction denoise (profile from head) |
+| `master`       | loudness-normalize to target LUFS + peak ceiling |
+| `export`       | write wav / flac / mp3 / ogg |
+| `sync`         | generate the Audacity project + scripts |
+| `history` / `undo` | deck state |
+| `load`         | replace the deck with a new file |
+
+## Development
+
+```bash
+pip install -e ".[test]"
+python -m pytest -q          # 102 tests, ~45s
+```
+
+Layout:
+
+```
+src/audatron/
+  dsp.py          # headless DSP engine (numpy + soundfile)
+  session.py      # stateful deck + op history
+  tools.py        # tool surface shared by CLI agent + MCP
+  agent.py        # LLM agent loop (Anthropic/OpenAI/Ollama)
+  backends.py     # LLM provider clients (+ streaming)
+  live.py         # realtime foreground view (token stream + waveform)
+  audacity.py     # .aup3 + TCL/Lua generation + Audacity lookup
+  aup3.py        # native Audacity-4 SQLite .aup3 writer
+  mcp_server.py   # MCP stdio JSON-RPC server
+  cli.py          # typer CLI
+tests/            # pytest: DSP, tools, agent (mocked), MCP, e2e, CLI, aup3, live
+```

audatron-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "audatron"
+version = "0.1.0"
+description = "audatron — LLM-driven realtime Audacity: natural language drives track editing, noise removal, and mastering, with a headless DSP engine plus auto-generated Audacity TCL scripts, an agent chat REPL, and an MCP stdio server."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "DREAM PIXELS FORGE" }]
+dependencies = [
+    "numpy>=1.26",
+    "soundfile>=0.12",
+    "typer>=0.12",
+    "rich>=13",
+    "httpx>=0.27",
+    "pydub>=0.25",
+]
+
+[project.optional-dependencies]
+noisereduce = ["noisereduce>=3.0"]
+test = ["pytest>=8"]
+
+[project.scripts]
+audatron = "audatron.cli:app"
+audatron-mcp = "audatron.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

audatron-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

audatron-0.1.0/src/audatron/agent.py

@@ -0,0 +1,142 @@
+"""audatron.agent — the natural-language agent loop.
+
+One `Agent` owns:
+  * a LLM backend (Anthropic / OpenAI / Ollama)
+  * a Session (the audio deck)
+  * a conversation history
+  * a trace log (every user turn, assistant turn, tool call, and tool result)
+
+`Agent.run(prompt)` executes one user turn to completion: it may call
+tools, observe results, and keep calling until the model stops.
+The trace is returned alongside the final assistant text so the CLI
+and MCP surfaces can render / inspect it.
+
+The conversation is kept in one provider-native `messages` list that grows
+as the loop runs — each backend's tool-call / tool-result wire format is
+handled by per-branch appends, so the same Agent works across all three.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from .backends import AnthropicBackend, OllamaBackend, OpenAIBackend
+from .session import Session
+from .tools import TOOL_SCHEMAS, dispatch
+
+
+SYSTEM_PROMPT = """You are audatron, a realtime audio-production agent.
+
+You control a headless DSP deck (the "deck") that mirrors a live Audacity
+project. The deck is ALREADY LOADED with the audio the user pointed you at —
+do NOT call `load` unless the user explicitly names a different file. Work
+directly on the current deck.
+
+Use the tools to inspect, edit, clean, master, and export audio. After each
+tool call, reason from the result. Keep tool calls minimal: one op per step,
+verify with `inspect` when in doubt. When the user asks for a sync, call
+`sync` to generate the matching Audacity TCL/Lua scripts.
+
+Tool results are JSON. Do not invent audio properties — read them from
+`inspect`/`analyze`.
+"""
+
+
+@dataclass
+class TraceEntry:
+    role: str          # "user" | "assistant" | "tool"
+    name: str = ""     # tool name when role == "tool"
+    text: str = ""     # assistant/user text or tool-result JSON
+    calls: list[dict] = field(default_factory=list)  # tool_calls when role == "assistant"
+
+    def to_dict(self) -> dict:
+        return {"role": self.role, "name": self.name, "text": self.text, "calls": self.calls}
+
+
+class Agent:
+    def __init__(
+        self,
+        session: Session,
+        backend: AnthropicBackend | OpenAIBackend | OllamaBackend,
+        max_steps: int = 8,
+    ):
+        self.session = session
+        self.backend = backend
+        self.max_steps = max_steps
+        self.trace: list[TraceEntry] = []
+
+    # ------------------------------------------------------------------
+    # public API
+    # ------------------------------------------------------------------
+
+    def run(self, prompt: str) -> dict:
+        """Execute one user turn. Returns {"text": ..., "trace": [...], "tool_calls": N}."""
+        self.trace.append(TraceEntry(role="user", text=prompt))
+        messages: list[dict] = [{"role": "user", "content": SYSTEM_PROMPT}, {"role": "user", "content": prompt}]
+        tool_calls_total = 0
+
+        for _step in range(self.max_steps):
+            text, calls = self.backend.complete(messages, TOOL_SCHEMAS)
+            if not calls:
+                self.trace.append(TraceEntry(role="assistant", text=text))
+                return {"text": text, "trace": self.trace, "tool_calls": tool_calls_total}
+
+            self.trace.append(TraceEntry(role="assistant", text=text, calls=calls))
+            tool_calls_total += len(calls)
+
+            if self.backend.name == "anthropic":
+                results = []
+                for c in calls:
+                    out = dispatch(self.session, c["name"], c.get("arguments") or {})
+                    results.append({"type": "tool_result", "tool_use_id": c["id"], "content": json.dumps(out)})
+                    self.trace.append(TraceEntry(role="tool", name=c["name"], text=json.dumps(out)))
+                messages.append({"role": "assistant", "content": _anthropic_blocks(text, calls)})
+                messages.append({"role": "user", "content": results})
+            elif self.backend.name == "ollama":
+                # Ollama chat format: assistant message carries tool_calls (OpenAI-ish,
+                # args as dict), tool results use role "tool" with the tool name.
+                messages.append({
+                    "role": "assistant",
+                    "content": text,
+                    "tool_calls": [
+                        {"id": c["id"], "function": {"name": c["name"], "arguments": c.get("arguments") or {}}}
+                        for c in calls
+                    ],
+                })
+                for c in calls:
+                    out = dispatch(self.session, c["name"], c.get("arguments") or {})
+                    self.trace.append(TraceEntry(role="tool", name=c["name"], text=json.dumps(out)))
+                    messages.append({"role": "tool", "name": c["name"], "content": json.dumps(out)})
+            else:  # openai-compatible
+                messages.append({
+                    "role": "assistant",
+                    "content": text,
+                    "tool_calls": [
+                        {"id": c["id"], "type": "function", "function": {"name": c["name"], "arguments": json.dumps(c.get("arguments") or {})}}
+                        for c in calls
+                    ],
+                })
+                for c in calls:
+                    out = dispatch(self.session, c["name"], c.get("arguments") or {})
+                    self.trace.append(TraceEntry(role="tool", name=c["name"], text=json.dumps(out)))
+                    messages.append({"role": "tool", "tool_call_id": c["id"], "content": json.dumps(out)})
+
+        # ran out of steps
+        return {"text": "stopped at max_steps", "trace": self.trace, "tool_calls": tool_calls_total}
+
+
+# ---------------------------------------------------------------------------
+# Wire-format helpers
+# ---------------------------------------------------------------------------
+
+def _anthropic_blocks(text: str, calls: list[dict]) -> list[dict]:
+    blocks: list[dict] = []
+    if text:
+        blocks.append({"type": "text", "text": text})
+    for c in calls:
+        blocks.append({"type": "tool_use", "id": c["id"], "name": c["name"], "input": c.get("arguments") or {}})
+    return blocks
+
+
+__all__ = ["Agent", "SYSTEM_PROMPT", "TraceEntry"]