sonic-bloom 0.1.0__tar.gz

sonic_bloom-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Git
+.gitignore
+
+# Plan / docs
+CLAUDE.md
+PLAN.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Environment
+.env
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Keys
+*.p8

sonic_bloom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Wirth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sonic_bloom-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.3
+Name: sonic-bloom
+Version: 0.1.0
+Summary: A little terminal app that controls Apple Music on macOS via natural language
+Project-URL: Homepage, https://github.com/James-Wirth/sonic-bloom
+Project-URL: Repository, https://github.com/James-Wirth/sonic-bloom
+Author: James Wirth
+License: MIT
+Keywords: apple-music,cli,llm,macos,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.75.0
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: pyobjc-core>=10.0
+Requires-Dist: pyobjc-framework-cocoa>=10.0
+Requires-Dist: pyobjc-framework-mediaplayer>=10.0
+Requires-Dist: pyobjc-framework-scriptingbridge>=10.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Sonic Bloom
+
+A little terminal app that controls Apple Music on macOS via natural language.
+
+```
+> Play something whilst I assemble this Ikea shelf
+
+  ⠋ Searching iTunes...
+
+  ? Pick your track:
+    › The Final Countdown – Europe
+      Lose Yourself – Eminem
+      Harder Better Faster Stronger – Daft Punk
+
+  Good choice.
+
+  ╭ ▶ Now Playing ────────────────────────────╮
+  │ The Final Countdown — Europe              │
+  │ The Final Countdown                       │
+  │ vol 75 · shuffle off · repeat off         │
+  ╰───────────────────────────────────────────╯
+```
+
+## Setup
+
+Requires macOS, Python 3.11+, and Apple Music.
+
+```sh
+git clone https://github.com/jameswirth/sonic-bloom.git
+cd sonic-bloom
+pip install -e .
+python -m sonic_bloom
+```
+
+You'll be prompted to choose a provider (Anthropic, OpenAI, or Ollama) and enter an API key.

sonic_bloom-0.1.0/README.md

@@ -0,0 +1,35 @@
+# Sonic Bloom
+
+A little terminal app that controls Apple Music on macOS via natural language.
+
+```
+> Play something whilst I assemble this Ikea shelf
+
+  ⠋ Searching iTunes...
+
+  ? Pick your track:
+    › The Final Countdown – Europe
+      Lose Yourself – Eminem
+      Harder Better Faster Stronger – Daft Punk
+
+  Good choice.
+
+  ╭ ▶ Now Playing ────────────────────────────╮
+  │ The Final Countdown — Europe              │
+  │ The Final Countdown                       │
+  │ vol 75 · shuffle off · repeat off         │
+  ╰───────────────────────────────────────────╯
+```
+
+## Setup
+
+Requires macOS, Python 3.11+, and Apple Music.
+
+```sh
+git clone https://github.com/jameswirth/sonic-bloom.git
+cd sonic-bloom
+pip install -e .
+python -m sonic_bloom
+```
+
+You'll be prompted to choose a provider (Anthropic, OpenAI, or Ollama) and enter an API key.

sonic_bloom-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling<1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sonic-bloom"
+version = "0.1.0"
+description = "A little terminal app that controls Apple Music on macOS via natural language"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "James Wirth" }]
+keywords = ["apple-music", "macos", "llm", "terminal", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+dependencies = [
+    "anthropic>=0.75.0",
+    "rich>=13.0",
+    "httpx>=0.27.0",
+    "PyJWT>=2.8.0",
+    "cryptography>=42.0",
+    "python-dotenv>=1.0",
+    "pyobjc-core>=10.0",
+    "pyobjc-framework-Cocoa>=10.0",
+    "pyobjc-framework-ScriptingBridge>=10.0",
+    "pyobjc-framework-MediaPlayer>=10.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+all = ["openai>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/James-Wirth/sonic-bloom"
+Repository = "https://github.com/James-Wirth/sonic-bloom"
+
+[project.scripts]
+sonic-bloom = "sonic_bloom.__main__:main"

sonic_bloom-0.1.0/sonic_bloom/__main__.py

@@ -0,0 +1,26 @@
+"""Entry point for Sonic Bloom."""
+
+import sys
+
+
+def main():
+    # Suppress PyObjC app icon in the dock
+    try:
+        from AppKit import NSApplication, NSApplicationActivationPolicyProhibited
+        NSApplication.sharedApplication().setActivationPolicy_(NSApplicationActivationPolicyProhibited)
+    except ImportError:
+        pass
+
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    from sonic_bloom.app import SonicBloom
+    app = SonicBloom()
+    try:
+        app.run()
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

sonic_bloom-0.1.0/sonic_bloom/agent.py

@@ -0,0 +1,114 @@
+"""Provider-agnostic streaming tool-use agent."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Generator
+from dataclasses import dataclass
+
+from sonic_bloom.providers import Provider, TurnResult
+from sonic_bloom.tools import get_tools, execute
+from sonic_bloom.soul.prompts import build_system
+
+MAX_TOOL_ITERATIONS = 10
+
+
+@dataclass(slots=True)
+class TextDelta:
+    text: str
+
+@dataclass(slots=True)
+class ToolStart:
+    name: str
+
+@dataclass(slots=True)
+class ToolEnd:
+    name: str
+    result: dict | None = None
+    error: str | None = None
+
+@dataclass(slots=True)
+class AskUser:
+    question: str
+    tool_call_id: str
+    options: list[str] | None = None
+
+AgentEvent = TextDelta | ToolStart | ToolEnd | AskUser
+
+
+class MusicAgent:
+    """Streaming tool-use agent backed by any Provider."""
+
+    def __init__(self, provider: Provider, soul_content: str | None = None):
+        self._provider = provider
+        self._soul_content = soul_content
+        self._messages: list[dict] = []
+
+    def chat(self, user_input: str) -> Generator[AgentEvent, str | None, None]:
+        """Send a message and yield events as they stream back.
+
+        Yields AgentEvent instances. When an AskUser event is yielded,
+        the caller must .send() the user's answer string to resume.
+        """
+        self._messages.append({"role": "user", "content": user_input})
+        yield from self._run_turn()
+
+    def _run_turn(self) -> Generator[AgentEvent, str | None, None]:
+        system = build_system(self._soul_content)
+        tools = get_tools()
+        for _ in range(MAX_TOOL_ITERATIONS):
+            result: TurnResult = yield from self._wrap_stream(
+                self._provider.stream_turn(
+                    messages=self._messages,
+                    system=system,
+                    tools=tools,
+                )
+            )
+
+            self._messages.append({"role": "assistant", "content": result.content})
+
+            if result.stop_reason != "tool_use":
+                return
+
+            tool_results = []
+            for call in result.tool_calls:
+                if call.name == "ask_user":
+                    answer = yield AskUser(
+                        question=call.input.get("question", ""),
+                        tool_call_id=call.id,
+                        options=call.input.get("options"),
+                    )
+                    tool_results.append({
+                        "type": "tool_result",
+                        "tool_use_id": call.id,
+                        "content": f"User answered: {answer or '(no answer)'}",
+                    })
+                    continue
+
+                yield ToolStart(name=call.name)
+                try:
+                    r = execute(call.name, call.input)
+                    yield ToolEnd(name=call.name, result=r)
+                except Exception as e:
+                    r = {"error": str(e)}
+                    yield ToolEnd(name=call.name, error=str(e))
+                tool_results.append({
+                    "type": "tool_result",
+                    "tool_use_id": call.id,
+                    "content": json.dumps(r, default=str),
+                })
+
+            self._messages.append({"role": "user", "content": tool_results})
+
+    def _wrap_stream(
+        self, gen: Generator[str, None, TurnResult],
+    ) -> Generator[AgentEvent, str | None, TurnResult]:
+        """Wrap a provider's str-yielding generator into AgentEvent yields."""
+        try:
+            while True:
+                yield TextDelta(next(gen))
+        except StopIteration as e:
+            return e.value
+
+    def reset(self):
+        self._messages.clear()

sonic_bloom-0.1.0/sonic_bloom/app.py

@@ -0,0 +1,152 @@
+"""Application lifecycle and dependency wiring."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+from sonic_bloom.agent import MusicAgent
+from sonic_bloom.bridge import get_music
+from sonic_bloom.bridge.events import MusicEventThread
+from sonic_bloom.cli import SonicBloomCLI
+from sonic_bloom.cli.selection import select
+from sonic_bloom.config import CONFIG_DIR, CONFIG_FILE, Config, PROVIDER_DEFAULTS, _API_KEY_ENV
+from sonic_bloom.providers import make_provider
+from sonic_bloom.soul.manager import SoulManager
+
+SOUL_UPDATE_INTERVAL = 10
+
+BANNER = (
+    "  ███████╗ ██████╗ ███╗   ██╗██╗ ██████╗\n"
+    "  ██╔════╝██╔═══██╗████╗  ██║██║██╔════╝\n"
+    "  ███████╗██║   ██║██╔██╗ ██║██║██║     \n"
+    "  ╚════██║██║   ██║██║╚██╗██║██║██║     \n"
+    "  ███████║╚██████╔╝██║ ╚████║██║╚██████╗\n"
+    "  ╚══════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝ ╚═════╝\n"
+    "  ██████╗ ██╗      ██████╗  ██████╗ ███╗   ███╗\n"
+    "  ██╔══██╗██║     ██╔═══██╗██╔═══██╗████╗ ████║\n"
+    "  ██████╔╝██║     ██║   ██║██║   ██║██╔████╔██║\n"
+    "  ██╔══██╗██║     ██║   ██║██║   ██║██║╚██╔╝██║\n"
+    "  ██████╔╝███████╗╚██████╔╝╚██████╔╝██║ ╚═╝ ██║\n"
+    "  ╚═════╝ ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝     ╚═╝"
+)
+
+
+class SonicBloom:
+    def __init__(self):
+        self.console = Console()
+        self.config = Config.load()
+        self.soul = SoulManager()
+
+    def run(self):
+        self.console.print()
+        self.console.print(f"[bold #5b4a9e]{BANNER}[/]")
+        self.console.print("  [dim]AI music assistant for Apple Music[/]")
+        self.console.print()
+
+        self._check_music_app()
+        soul_content = self.soul.read()
+
+        provider = self._make_provider()
+        if not provider:
+            return
+        agent = MusicAgent(provider=provider, soul_content=soul_content)
+
+        event_thread = MusicEventThread()
+        event_thread.start()
+
+        cli = SonicBloomCLI(self.console, agent, event_thread.queue)
+        try:
+            cli.loop()
+        except (KeyboardInterrupt, EOFError):
+            pass
+        finally:
+            self._maybe_update_soul(cli, provider, force=True)
+            self.console.print("\n  [dim]Goodbye.[/]\n")
+            event_thread.stop()
+
+    def _check_music_app(self):
+        try:
+            m = get_music()
+            if not m.is_running:
+                self.console.print("  [yellow]Music.app is not running. Starting it...[/]")
+                m.activate()
+        except Exception:
+            self.console.print("  [yellow]Could not check Music.app status.[/]")
+
+    def _make_provider(self):
+        if not self.config.api_key and self.config.provider != "ollama":
+            if not self._setup():
+                return None
+        if self.config.provider == "ollama" and not self._check_ollama():
+            return None
+        try:
+            return make_provider(self.config)
+        except Exception as e:
+            self.console.print(f"  [red]Could not initialize {self.config.provider}: {e}[/]")
+            return None
+
+    def _setup(self) -> bool:
+        """First-run setup: choose provider and enter API key."""
+        self.console.print("  [bold]First-run setup[/]")
+
+        providers = list(PROVIDER_DEFAULTS.keys())
+        provider = select(self.console, "Choose a provider:", providers)
+
+        if provider == "ollama":
+            self._write_config(provider)
+            self.config = Config.load()
+            return True
+
+        env_var = _API_KEY_ENV.get(provider, "API_KEY")
+        self.console.print(f"  [dim]You can also set [bold]{env_var}[/] instead.[/]\n")
+        try:
+            key = self.console.input("  API key: ", password=True).strip()
+        except (KeyboardInterrupt, EOFError):
+            self.console.print()
+            return False
+
+        if not key:
+            self.console.print("  [red]No API key provided.[/]\n")
+            return False
+
+        self._write_config(provider, key)
+        self.config = Config.load()
+        self.console.print("  [green]Config saved.[/]\n")
+        return True
+
+    def _write_config(self, provider: str, api_key: str | None = None):
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        lines = [f'provider = "{provider}"']
+        if api_key:
+            lines.append(f"\n[{provider}]")
+            lines.append(f'api_key = "{api_key}"')
+        if CONFIG_FILE.exists():
+            existing = CONFIG_FILE.read_text()
+            if existing.strip():
+                lines = [existing.rstrip(), ""] + lines
+        CONFIG_FILE.write_text("\n".join(lines) + "\n")
+
+    def _check_ollama(self) -> bool:
+        import httpx
+        base = self.config.base_url or "http://localhost:11434"
+        try:
+            httpx.get(f"{base}/api/tags", timeout=3)
+            return True
+        except httpx.ConnectError:
+            self.console.print(f"  [red]Cannot connect to Ollama at {base}.[/]")
+            self.console.print("  [dim]Start Ollama with: ollama serve[/]\n")
+            return False
+
+    def _maybe_update_soul(self, cli: SonicBloomCLI, provider, force: bool = False):
+        if not cli.interaction_log:
+            return
+        if not force and cli.interaction_count % SOUL_UPDATE_INTERVAL != 0:
+            return
+        try:
+            self.soul.update(
+                "\n".join(cli.interaction_log),
+                provider.simple_completion,
+            )
+            cli.interaction_log.clear()
+        except Exception:
+            self.console.print("  [dim]Could not update preferences.[/]")

sonic_bloom-0.1.0/sonic_bloom/bridge/__init__.py

@@ -0,0 +1,17 @@
+"""Apple Music bridge — lazy initialization."""
+
+from __future__ import annotations
+
+from sonic_bloom.bridge.scripting_bridge import MusicApp
+
+_music: MusicApp | None = None
+
+
+def get_music() -> MusicApp:
+    """Get the MusicApp singleton, creating it on first call."""
+    global _music
+    if _music is None:
+        _music = MusicApp()
+    elif not _music.is_running:
+        _music = MusicApp()
+    return _music

sonic_bloom-0.1.0/sonic_bloom/bridge/catalog.py

@@ -0,0 +1,80 @@
+"""Apple Music REST API client for catalog search."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import httpx
+import jwt
+
+_SEARCH_URL = "https://api.music.apple.com/v1/catalog/{storefront}/search"
+_GET_URL = "https://api.music.apple.com/v1/catalog/{storefront}/songs/{id}"
+
+
+class CatalogClient:
+    """Apple Music catalog API client with JWT auth."""
+
+    def __init__(self, key_id: str, team_id: str, key_path: Path, storefront: str = "us"):
+        self._key_id = key_id
+        self._team_id = team_id
+        self._key_path = key_path
+        self._storefront = storefront
+        self._token: str | None = None
+        self._token_expiry: float = 0
+        self._client = httpx.Client(timeout=10)
+
+    def search(self, query: str, limit: int = 5) -> list[dict]:
+        url = _SEARCH_URL.format(storefront=self._storefront)
+        resp = self._client.get(
+            url,
+            headers=self._auth_headers(),
+            params={"term": query, "types": "songs", "limit": limit},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        songs = data.get("results", {}).get("songs", {}).get("data", [])
+        return [self._parse_song(s) for s in songs]
+
+    def get_song(self, song_id: str) -> dict | None:
+        url = _GET_URL.format(storefront=self._storefront, id=song_id)
+        resp = self._client.get(url, headers=self._auth_headers())
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        data = resp.json()
+        songs = data.get("data", [])
+        return self._parse_song(songs[0]) if songs else None
+
+    def _auth_headers(self) -> dict:
+        return {"Authorization": f"Bearer {self._get_token()}"}
+
+    def _get_token(self) -> str:
+        if self._token and time.time() < self._token_expiry:
+            return self._token
+        private_key = self._key_path.read_text()
+        now = int(time.time())
+        payload = {
+            "iss": self._team_id,
+            "iat": now,
+            "exp": now + 15777000,
+        }
+        self._token = jwt.encode(
+            payload, private_key, algorithm="ES256",
+            headers={"kid": self._key_id},
+        )
+        self._token_expiry = now + 15777000 - 60
+        return self._token
+
+    @staticmethod
+    def _parse_song(song: dict) -> dict:
+        attrs = song.get("attributes", {})
+        return {
+            "store_id": song.get("id", ""),
+            "name": attrs.get("name", ""),
+            "artist": attrs.get("artistName", ""),
+            "album": attrs.get("albumName", ""),
+            "duration_ms": attrs.get("durationInMillis", 0),
+            "genre": (attrs.get("genreNames") or [""])[0],
+            "url": attrs.get("url", ""),
+        }

sonic_bloom-0.1.0/sonic_bloom/bridge/events.py

@@ -0,0 +1,71 @@
+"""Real-time Music.app notifications via NSDistributedNotificationCenter."""
+
+from __future__ import annotations
+
+import queue
+import threading
+from dataclasses import dataclass
+
+import objc
+from Foundation import NSObject, NSRunLoop, NSDate, NSDistributedNotificationCenter
+
+
+@dataclass(frozen=True, slots=True)
+class MusicEvent:
+    state: str
+    name: str | None = None
+    artist: str | None = None
+    album: str | None = None
+
+
+class _Observer(NSObject):
+    @objc.python_method
+    def initWithQueue_(self, q: queue.Queue[MusicEvent]):
+        self = objc.super(_Observer, self).init()
+        if self is None:
+            return None
+        self._queue = q
+        return self
+
+    def handleNotification_(self, notification):
+        info = notification.userInfo()
+        if not info:
+            return
+        state = str(info.get("Player State", ""))
+        name = info.get("Name")
+        artist = info.get("Artist")
+        album = info.get("Album")
+        self._queue.put(MusicEvent(
+            state=state,
+            name=str(name) if name else None,
+            artist=str(artist) if artist else None,
+            album=str(album) if album else None,
+        ))
+
+
+class MusicEventThread:
+    """Background thread listening for Music.app playback notifications."""
+
+    def __init__(self):
+        self.queue: queue.Queue[MusicEvent] = queue.Queue()
+        self._thread: threading.Thread | None = None
+        self._stop_event = threading.Event()
+
+    def start(self):
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_event.set()
+
+    def _run(self):
+        observer = _Observer.alloc().initWithQueue_(self.queue)
+        center = NSDistributedNotificationCenter.defaultCenter()
+        center.addObserver_selector_name_object_(
+            observer, objc.selector(observer.handleNotification_, signature=b"v@:@"),
+            "com.apple.Music.playerInfo", None,
+        )
+        loop = NSRunLoop.currentRunLoop()
+        while not self._stop_event.is_set():
+            loop.runMode_beforeDate_("NSDefaultRunLoopMode", NSDate.dateWithTimeIntervalSinceNow_(0.5))
+        center.removeObserver_(observer)