sonagram

Ask your AI assistant for a playlist from your own music collection — and get a file any music app can play.

sonagram listens to every track you own (tempo, energy, mood, key, how songs feel), organizes what it learns into a fast, searchable map of your library, and lets an AI agent translate your sentence into a typed request. Sonagram's deterministic library engine—not the agent—then selects, orders, audits, and explains the playlist:

"Make me a deep-focus work playlist." "A party mix for Saturday that builds." "Songs like Teardrop, but calmer."

Your music files are never modified, moved, or uploaded — everything happens on your machine.

For AI agents

You are an AI agent and a user asked you to work with their music library — start here:

  1. Install — pip install sonagram. Prebuilt wheels cover macOS (Apple Silicon + Intel), Linux x86_64, and Windows x86_64 on Python ≥ 3.9 — no toolchain needed. Only on other platforms does pip fall back to the sdist, which compiles the native core and needs a Rust toolchain (rustup).
  2. Install the skill — sonagram skill install. This writes the sonagram-playlist skill to ~/.claude/skills/ (pass --dir <skills_root> for a non-default skills location).
  3. Read the installed SKILL.md and follow it now. It covers library detection, scanning, the optional Last.fm walkthrough, and playlist delivery. A skill only auto-loads at the next session start, so act on it immediately in this one.

Use it through your agent (no code)

This is the main way to use sonagram. One-time setup:

  1. Install it — pip install sonagram. That's it on Mac, Windows, and regular Linux — prebuilt packages, nothing to compile. (On unusual platforms pip builds from source, which needs the free Rust toolchain — your agent can sort that out.)
  2. Point it at your music — sonagram sources add ~/Music (repeat for other folders).
  3. Give your agent the skill — sonagram skill install.

That's it. From now on, just ask:

  • "make me a deep-focus work playlist"
  • "a party mix for Saturday that builds"
  • "songs like Teardrop but calmer"
  • "which songs do I have multiple versions of? pair them"
  • "what's even in my library?"

The first request analyzes your whole collection (about an hour for ~10,000 songs — your agent will tell you and can let it run in the background). Every request after that takes seconds: sonagram notices what changed, re-reads only that, and keeps the map current — including songs you've added or deleted.

Each playlist is saved with its name, your original request, and the full track list, so you can always ask for it again later (sonagram playlists). The .m3u8 files point straight at your own music files and open in any player.

Optional: better picks with Last.fm. A free Last.fm API key adds richer genre info, song popularity, and "fans also like" connections. Your agent can walk you through getting one — just ask.

CLI (scriptable)

pip install sonagram also gives you the standalone sonagram command (the same shared code path the agent uses, so the two can't drift). Once a source is registered, commands need no path arguments:

sonagram sources add ~/Music     # register a library folder (repeatable)
sonagram status                  # is everything up to date? (exit 0/1/2)
sonagram scan                    # analyze new/changed files → local cache
sonagram enrich                  # optional: fold in Last.fm metadata (needs a key)
sonagram build                   # merge all sources → the central graph
sonagram profile --format json   # curation-relevant coverage/distributions
sonagram curate --preset focus --tracks 25 \
    --name "Deep Focus" --description "a calm work playlist" --format json
sonagram playlists               # list stored playlists (newest first)
sonagram mcp install             # native kglite manifest + revealed music skills

sonagram config shows where everything lives (defaults under ~/.sonagram/) and whether a Last.fm key is set up. Explicit-path forms (sonagram scan ~/Music, sonagram status ~/Music --format json, …) still work for scripting a single library without touching the config, and sonagram playlist ... --copy-to <dir> produces a portable folder — the tracks copied next to the playlist file, ready for a USB stick or another device.

Everything is incremental: a rescan of an unchanged library analyzes nothing and finishes in well under a second.

For building your own agents / integrations

Install Sonagram's safe kglite manifest/revealed skills, then use the absolute launch command it prints—or drive the same library contract from Python:

sonagram mcp install
# RUN: '/absolute/path/sonagram-mcp-server' --graph '/.../music.kgl'

The thin Sonagram frontend embeds KGLite 0.16.18's server and registers typed profile/policy/curate/audit/explain/store tools against its live graph. KGLite still owns MCP, Cypher, graph lifecycle, and generic tools; Sonagram owns only the music-domain handlers.

import sonagram
sonagram.scan("~/Music")
g = sonagram.build("~/Music", out_path="music.kgl")   # a live kglite graph
brief = {"preset": "focus", "target_tracks": 25,
         "target_duration_sec": None, "seed_ids": [],
         "seed_role": "pinned", "unsupported_intents": []}
result = sonagram.curate_playlist("music.kgl", brief)
assert result["exportable"] and result["audit"]["passed"]

Agents get a full manual (AGENT-GUIDE.md: the schema, a query cookbook, and a typed curation contract) plus live-gated kglite skills. Both route final selection/order/audit through the library rather than agent-authored heuristics.

How it works (the short version)

  • sonara does the listening: tempo, key, energy, mood, loudness, structure, and an audio "fingerprint of feel" for every track.
  • kglite stores the map: a graph database with search, similarity, and an agent-friendly query interface.
  • sonagram is the part in between: it decides what the map contains — every song with all its signals, connected to artists, genres, decades, moods, detected styles, and its 10 most similar tracks — and keeps the map exactly reproducible, byte for byte, no matter how often you rescan.

Full documentation (CLI reference, Python API, the graph's schema, and the engineering details) lives on Read the Docs — see docs/.

License: MIT

Project links

Data verified by PyPI on Aug 31, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.16)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for kkollsg from gravatar.com kkollsg

GitHub Statistics

Data verified by PyPI on Aug 31, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License

Requires

Python >=3.9

Tags

music knowledge-graph graph audio playlist cypher mir rust

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sonagram-0.2.13.tar.gz (933.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

sonagram-0.2.13-cp39-abi3-win_amd64.whl (11.1 MB view details)

Uploaded CPython 3.9+Windows x86-64

sonagram-0.2.13-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (11.5 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

sonagram-0.2.13-cp39-abi3-macosx_11_0_arm64.whl (10.2 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

sonagram-0.2.13-cp39-abi3-macosx_10_12_x86_64.whl (11.1 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file sonagram-0.2.13.tar.gz.

File metadata

  • Download URL: sonagram-0.2.13.tar.gz
  • Upload date:
  • Size: 933.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sonagram-0.2.13.tar.gz
Algorithm Hash digest
SHA256 c4386cb04ea8cac61bc39ed6158ac2ab3e7924ca67c09c1e0dce1430d90a5cab
MD5 ea061def15c252422fd9f79f20485e4f
BLAKE2b-256 c77e31bf7627274f452f197b2bf7b3784009cc86c868d02600c387cf709608d2

See more details on using hashes here.

Provenance

The following attestation bundles were made for sonagram-0.2.13.tar.gz:

Publisher: release.yml on kkollsga/sonagram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sonagram-0.2.13-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: sonagram-0.2.13-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 11.1 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sonagram-0.2.13-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e8ebb21d03508242ddb2389935aceed82327976caf42dd9d694e77b14b3f81c1
MD5 ecec3697fbbed0c7e55e126879c84610
BLAKE2b-256 33c6b02b13cf61a9f2fff0354abed709a77a9358f0968a40ca63a7a439cfb29a

See more details on using hashes here.

Provenance

The following attestation bundles were made for sonagram-0.2.13-cp39-abi3-win_amd64.whl:

Publisher: release.yml on kkollsga/sonagram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sonagram-0.2.13-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for sonagram-0.2.13-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 10627a2b2ec3ad3e4f788f80722eeee826cd972f44e7aeb2425e4794d6099b48
MD5 e38a7aad12721fc1b6a6a63b9a59bf68
BLAKE2b-256 3e5198f853c8b667254fd38ecbc7d4d6ab422cace7583b53a1d8415320fafe47

See more details on using hashes here.

Provenance

The following attestation bundles were made for sonagram-0.2.13-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on kkollsga/sonagram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sonagram-0.2.13-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for sonagram-0.2.13-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c78ca7639b087a1962b13e715d83750c2787b93ee8a7e49a9d6dba64b06ac1d9
MD5 fe4d6021609d60a74e8bc4e2a87a6d1b
BLAKE2b-256 19437443b1c173b725de9d0484bb1e251b65e05eb614464d310f960ab664a4b3

See more details on using hashes here.

Provenance

The following attestation bundles were made for sonagram-0.2.13-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on kkollsga/sonagram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sonagram-0.2.13-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sonagram-0.2.13-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 dbb5781be7b27aeb089122b40f3a123ed11e9aa1401a8c6c45c3f6b2f73ceeae
MD5 3aadf9b12c5319b29f64071afb0211a6
BLAKE2b-256 8f8826ec104771d2a85cce4682e6e384787f05590b4032fad89c81ffc5e26200

See more details on using hashes here.

Provenance

The following attestation bundles were made for sonagram-0.2.13-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on kkollsga/sonagram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.16

5 files

0.2.15

5 files

0.2.14

5 files

This release

0.2.13 This release

5 files

0.2.12

5 files

0.2.11

5 files

0.2.10

5 files

0.2.9

5 files

0.2.8

5 files

0.2.7

5 files

0.2.6

5 files

0.2.5

5 files

0.2.4

5 files

0.2.3

5 files

0.2.2

5 files

0.2.1

5 files

0.2.0

5 files

0.1.0

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page