audatron 0.1.0__py3-none-any.whl

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"]

audatron/audacity.py

@@ -0,0 +1,454 @@
+"""audatron.audacity — bridge between the DSP engine and a real Audacity project.
+
+`audatron sync` writes:
+  1. a .aup3 / .aup project (XML header + per-track references)
+  2. an audatron.json manifest describing the ops (machine-readable)
+  3. an auto-generated TCL script (legacy Audacity) and/or Lua script (Audacity 2+)
+
+The generated TCL is the user's "realtime" surface: running `Audacity.exe`
+with `--execute` executes the script in the open project and the user watches
+the waveforms change live.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Sequence
+
+from . import aup3 as _aup3
+
+# ---------------------------------------------------------------------------
+# Op model
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AudacityOp:
+    """One step of an Audacity-side workflow."""
+    kind: str
+    args: dict
+    track: int = 0
+
+
+# ---------------------------------------------------------------------------
+# TCL generation (legacy Audacity + most common)
+# ---------------------------------------------------------------------------
+
+def _fmt(v: float) -> str:
+    """TCL float: never emit '1.0' for ints so TCL parses it as a number."""
+    return f"{v:.4f}".rstrip("0").rstrip(".") if float(v) == int(float(v)) else f"{v:.4f}"
+
+
+def gen_tcl(ops: Sequence[AudacityOp]) -> str:
+    """Generate a runnable TCL script (Audacity legacy console)."""
+    lines = [
+        "#!auda_tcl",
+        "setProjectName",
+        "update",
+    ]
+    for op in ops:
+        if op.kind == "trim":
+            s = op.args.get("start_s", 0.0)
+            e = op.args.get("end_s")
+            e_str = f"{e}" if e is not None else "end"
+            lines.append(f"SetSelection {s} {e_str}")
+            lines.append("CutSelection")
+        elif op.kind == "cut":
+            s, e = op.args.get("start_s", 0.0), op.args.get("end_s", 0.0)
+            lines.append(f"SetSelection {s} {e}")
+            lines.append("CutSelection")
+        elif op.kind == "gain":
+            db = op.args.get("db", 0.0)
+            lines.append(f"SetGain {db}")
+        elif op.kind == "normalize":
+            target = op.args.get("target_db", -3.0)
+            lines.append(f"Normalize {target}")
+        elif op.kind == "noise_reduce":
+            profile = op.args.get("profile_seconds", 0.5)
+            strength = op.args.get("strength", 1.0)
+            lines.append("Sqm noise-removal-3 0 2 2 {profileTime=%s strength=%s}" % (profile, strength))
+        elif op.kind == "master":
+            target_lufs = op.args.get("target_lufs", -14.0)
+            ceiling = op.args.get("true_peak_db", -1.0)
+            lines.append(f"LimitandNormalize {ceiling} {target_lufs}")
+        elif op.kind == "export":
+            fmt = op.args.get("format", "wav")
+            path = op.args.get("path", "export.wav")
+            lines.append(f"exportAll {path} {fmt}")
+        elif op.kind == "play":
+            lines.append("play")
+        elif op.kind == "save":
+            lines.append("save")
+    lines.append("update")
+    return "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Lua generation (Audacity 2.x — new scripting engine)
+# ---------------------------------------------------------------------------
+
+def gen_lua(ops: Sequence[AudacityOp]) -> str:
+    """Generate a runnable Lua script for the new Audacity Lua engine."""
+    lines = ["--!lua", "-- audatron generated script"]
+    for op in ops:
+        if op.kind == "gain":
+            db = op.args.get("db", 0.0)
+            lines.append(f"Amplify({db})")
+        elif op.kind == "normalize":
+            target = op.args.get("target_db", -3.0)
+            lines.append(f"Normalize({target})")
+        elif op.kind == "noise_reduce":
+            profile = op.args.get("profile_seconds", 0.5)
+            strength = op.args.get("strength", 1.0)
+            lines.append(
+                f"NoiseReduction({profile}, {strength})"
+            )
+        elif op.kind == "master":
+            target_lufs = op.args.get("target_lufs", -14.0)
+            ceiling = op.args.get("true_peak_db", -1.0)
+            lines.append(f"LimitAndNormalize({ceiling}, {target_lufs})")
+        elif op.kind == "export":
+            fmt = op.args.get("format", "wav")
+            path = op.args.get("path", "export.wav")
+            lines.append(f"ExportFile({path!r}, {fmt!r})")
+        elif op.kind == "play":
+            lines.append("Play()")
+        elif op.kind == "save":
+            lines.append("Save()")
+        elif op.kind in ("trim", "cut"):
+            s = op.args.get("start_s", 0.0)
+            e = op.args.get("end_s", 0.0)
+            lines.append(f"SetSelection({s}, {e})")
+            lines.append("CutSelection()")
+    return "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Sync planning
+# ---------------------------------------------------------------------------
+
+def sync_plan(ops: Sequence[AudacityOp]) -> list[AudacityOp]:
+    """Reorder ops so export/save are last (idempotent)."""
+    non_export = [o for o in ops if o.kind not in ("export", "save")]
+    tail = [o for o in ops if o.kind in ("export", "save")]
+    return non_export + tail
+
+
+# ---------------------------------------------------------------------------
+# Project file generation
+# ---------------------------------------------------------------------------
+
+def build_project(
+    project_dir: Path,
+    src_wav: str,
+    ops: Sequence[AudacityOp],
+    sr: int = 44100,
+    duration_s: float = 1.0,
+    native: bool = True,
+) -> Path:
+    """Write a minimal .aup3 project + manifest + script files.
+
+    Returns the project directory path.
+    """
+    project_dir.mkdir(parents=True, exist_ok=True)
+    name = project_dir.name
+    project = project_dir / f"{name}.aup3"
+
+    # A real Audacity 3.x project references a WAV track. We emit the minimum
+    # XML Audacity accepts: one WaveTrack wrapping the source WAV, at the
+    # deck's sample rate and duration.
+    track_uuid = "audatron-" + "".join(c for c in name if c.isalnum())[:8]
+    project.write_text(
+        f'''<?xml version="1.0" encoding="UTF-8"?>
+<AudacityProject xmlns="http://www.audacity.de/project" version="3.0.0">
+  <PlugInSettings>
+    <UseFixedPoint>0</UseFixedPoint>
+  </PlugInSettings>
+  <ProjectSettings>
+    <AudioStart>0</AudioStart>
+    <Len>{duration_s}</Len>
+    <Rate>{sr}</Rate>
+    <ChannelNumTracks>0</ChannelNumTracks>
+  </ProjectSettings>
+  <WaveTrack>
+    <IndexOrder>0</IndexOrder>
+    <Channels>1</Channels>
+    <SampleFormat>0</SampleFormat>
+    <SampleRate>{sr}</SampleRate>
+    <Len>{int(duration_s * sr)}</Len>
+    <MinSample>0</MinSample>
+    <MaxSample>0</MaxSample>
+    <Name>deck</Name>
+    <WaveClip>
+      <UUID>{track_uuid}</UUID>
+      <Start>0</Start>
+      <Stop>{int(duration_s * sr)}</Stop>
+      <FileName>{Path(src_wav).name}</FileName>
+      <FileOffset>0</FileOffset>
+      <ClipStart>0</ClipStart>
+      <ClipStop>{int(duration_s * sr)}</ClipStop>
+      <Gain>1</Gain>
+      <FadeIn>0</FadeIn>
+      <FadeOut>0</FadeOut>
+      <EnvelopeName></EnvelopeName>
+    </WaveClip>
+    <Envelope>
+      <EnvelopePoint>
+        <Time>0</Time>
+        <Magnitude>0</Magnitude>
+        <Selected>0</Selected>
+        <Razor>0</Razor>
+      </EnvelopePoint>
+    </Envelope>
+  </WaveTrack>
+</AudacityProject>
+'''
+    )
+
+    manifest = {
+        "project": str(project),
+        "source_wav": str(Path(src_wav).name),
+        "sample_rate": sr,
+        "duration": duration_s,
+        "ops": [{"kind": o.kind, "args": o.args, "track": o.track} for o in ops],
+        "tcl": str(project_dir / "audatron.tcl"),
+        "lua": str(project_dir / "audatron.lua"),
+    }
+    (project_dir / "audatron.json").write_text(json.dumps(manifest, indent=2))
+
+    plan = sync_plan(ops)
+    (project_dir / "audatron.tcl").write_text(gen_tcl(plan))
+    (project_dir / "audatron.lua").write_text(gen_lua(plan))
+
+    if native:
+        _write_native(project_dir, src_wav)
+
+    return project_dir
+
+
+def _write_native(project_dir: Path, src_wav: str) -> Optional[Path]:
+    """Write a native Audacity-4 SQLite .aup3 next to the XML one.
+
+    Reads the source WAV, converts to float32, and calls aup3.write_aup3.
+    The native file is `<name>.native.aup3` so it never collides with the
+    XML project. Returns the native path, or None (XML-only) when the WAV
+    can't be read - e.g. a manifest build with no source on disk.
+    """
+    from .dsp import load_audio
+
+    try:
+        audio = load_audio(src_wav)
+    except Exception:
+        # missing / unreadable WAV: fall back to XML-only project
+        return None
+    native_path = project_dir / f"{project_dir.name}.native.aup3"
+    _aup3.write_aup3(native_path, audio.samples, audio.sr, track_name=project_dir.name)
+    return native_path
+
+
+def write_native_aup3(project_dir: Path, src_wav: str) -> Optional[Path]:
+    """Public helper: write just the native SQLite .aup3 for a WAV."""
+    return _write_native(project_dir, src_wav)
+
+
+# ---------------------------------------------------------------------------
+# Executing the script in a running Audacity
+# ---------------------------------------------------------------------------
+
+def find_audacity() -> Optional[str]:
+    """Locate the Audacity executable. Returns None when not installed."""
+    p = shutil.which("audacity")
+    if p:
+        return p
+    # Common Windows install paths, newest builds first (Audacity 4/3/2).
+    for candidate in (
+        r"C:\Program Files\Audacity 4\bin\Audacity4.exe",
+        r"C:\Program Files\Audacity 3\bin\Audacity3.exe",
+        r"C:\Program Files\Audacity\Audacity.exe",
+        r"C:\Program Files\Audacity 2\Audacity.exe",
+        r"C:\Program Files (x86)\Audacity\Audacity.exe",
+        r"C:\Program Files (x86)\Audacity 2\Audacity.exe",
+    ):
+        if Path(candidate).exists():
+            return candidate
+    # Fallback: probe a live Audacity process (its bin dir is often not on PATH).
+    live = running_audacity()
+    if live and live.get("path"):
+        return live["path"]
+    return None
+
+
+def running_audacity() -> Optional[dict]:
+    """Detect a live Audacity process and report its window title.
+
+    Returns {"pid", "name", "path", "title"} when one is running, else None.
+    The title (e.g. "River+of+grace * - Audacity 4.0") tells the caller which
+    project is open - the `*` marks unsaved changes.
+    """
+    if os.name != "nt":
+        return None
+    import subprocess as _sp
+
+    try:
+        out = _sp.check_output(
+            ["powershell", "-NoProfile", "-Command",
+             "Get-Process | Where-Object { $_.ProcessName -match 'audacity' } | "
+             "Select-Object Id, ProcessName, Path, MainWindowTitle | "
+             "ConvertTo-Json -Compress"],
+            text=True,
+        )
+    except Exception:
+        return None
+    import json as _json
+
+    data = _json.loads(out) if out.strip() else []
+    if isinstance(data, dict):
+        data = [data]
+    for proc in data:
+        if proc.get("Path"):
+            return {
+                "pid": proc.get("Id"),
+                "name": proc.get("ProcessName"),
+                "path": proc.get("Path"),
+                "title": proc.get("MainWindowTitle") or "",
+            }
+    return None
+
+
+def _aup3_for(project_dir: Path) -> Path:
+    """Back-compat shim - now just returns the auto-preferring project file."""
+    return project_file(project_dir, "auto")
+
+
+def project_file(project_dir: Path, prefer: str = "auto") -> Path:
+    """Return which .aup3 to open.
+
+    prefer:
+      "auto"  - native SQLite .aup3 if present, else XML .aup3
+      "native"- native SQLite .aup3 (Audacity 4); falls back to XML if missing
+      "xml"   - the legacy Audacity 3 XML .aup3 (older builds)
+    """
+    name = project_dir.name
+    native = project_dir / f"{name}.native.aup3"
+    xml = project_dir / f"{name}.aup3"
+    if prefer == "xml":
+        return xml
+    if native.exists():
+        return native
+    if xml.exists():
+        return xml
+    # fall back to any .aup3 in the dir
+    matches = list(project_dir.glob("*.aup3"))
+    return matches[0] if matches else xml
+
+
+def open_audacity_with(project_dir: Path, prefer: str = "auto") -> Optional[list[str]]:
+
+    """Return the argv to launch Audacity with this project open.
+
+    Audacity takes the .aup3 as its first positional arg. Returns None when
+    Audacity is not found (the caller decides whether to fall back to a hint).
+    """
+    exe = find_audacity()
+    if not exe:
+        return None
+    return [exe, str(project_file(project_dir, prefer))]
+
+
+def build_tcl_argv(project_dir: Path, prefer: str = "auto") -> Optional[list[str]]:
+    """Return the argv that launches Audacity *and* auto-runs the TCL script.
+
+    Audacity 3.x supports ``--execute <script>``: it opens the project and,
+    once the UI is up, runs the generated macro so the noise-removal /
+    mastering / export edits apply with zero manual steps. Returns None when
+    Audacity is not installed.
+    """
+    exe = find_audacity()
+    if not exe:
+        return None
+    tcl = project_dir / "audatron.tcl"
+    return [exe, str(project_file(project_dir, prefer)), "--execute", str(tcl)]
+
+
+def coding_agent_snippet(project_dir: Path) -> str:
+    """A ready-to-paste snippet for driving audatron from a coding agent.
+
+    Three parts:
+      1. a shell one-liner that opens the project in a live Audacity,
+      2. a zero-steps one-liner that opens it AND auto-runs the TCL macro,
+      3. the MCP server config (JSON) so Claude Code / Codex / opencode /
+         kimi / qwen can call the same tools over stdio.
+    Pure-ASCII so it copies cleanly into any terminal / config file.
+    """
+    tcl = project_dir / "audatron.tcl"
+    lua = project_dir / "audatron.lua"
+    exe = find_audacity()
+    launch = f'"{exe}"' if exe else "<find-audacity>"
+    lines = [
+        "# audatron -> coding agent handoff",
+        "",
+        "## 1) Watch the edits land in a live Audacity",
+        f'   {launch} "{_aup3_for(project_dir)}"   # opens the project',
+        f"   # then Tools -> Macros -> Run a macro... -> {tcl.name}",
+        "",
+        "## 1b) Zero-steps: open + auto-run the macro in one command",
+        f'   {launch} "{_aup3_for(project_dir)}" --execute "{tcl}"',
+        "",
+        "## 2) Drive the same tools from any MCP-capable agent",
+        "   # stdio server (start it, keep it open for the session):",
+        "   audatron-mcp",
+        "",
+        "   # .mcp.json / .claude/settings.json / .kimi/mcp.json ...",
+        "   {",
+        '     "mcpServers": {',
+        '       "audatron": {',
+        '         "command": "audatron-mcp",',
+        '         "args": []',
+        "       }",
+        "     }",
+        "   }",
+        "",
+        f"# generated scripts on disk: {tcl.as_posix()} / {lua.as_posix()}",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def run_script(exe: str, script_path: str, timeout_s: int = 60) -> subprocess.CompletedProcess:
+    """Execute a TCL script in a running Audacity (or headless with `--execute`)."""
+    # Legacy Audacity: launch and run script through tclsh if not already open.
+    # For headless execution we launch Audacity with the --execute flag.
+    cmd = [exe, "--execute", script_path]
+    return subprocess.run(cmd, capture_output=True, timeout=timeout_s)
+
+
+def run_script_in_running_audacity(tcl_path: str) -> None:
+    """If Audacity is already open, execute the TCL file against it.
+
+    Uses Windows COM automation to avoid needing `pywinauto`.
+    """
+    import win32com.client  # type: ignore
+
+    app = win32com.client.Dispatch("Audacity.Application")
+    app.RunMacro(tcl_path)
+
+
+__all__ = [
+    "AudacityOp",
+    "build_project",
+    "build_tcl_argv",
+    "coding_agent_snippet",
+    "find_audacity",
+    "gen_lua",
+    "gen_tcl",
+    "open_audacity_with",
+    "project_file",
+    "run_script",
+    "run_script_in_running_audacity",
+    "running_audacity",
+    "sync_plan",
+    "write_native_aup3",
+]