Metadata-Version: 2.4
Name: mamonia
Version: 0.1.17
Summary: Local-first music discovery CLI inspired by Prawo Mamonia.
Author-email: Kajetan Jagiełka <heartless-jeden@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://heartless.one/
Project-URL: Repository, https://github.com/heartless-jeden/mamonia
Project-URL: Issues, https://github.com/heartless-jeden/mamonia/issues
Keywords: music,discovery,spotify,cli,musicbrainz,lastfm
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: pydantic>=2.7
Requires-Dist: httpx>=0.27
Requires-Dist: spotipy>=2.23
Requires-Dist: tidalapi>=0.8.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: questionary>=2.0
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Provides-Extra: csvtool
Requires-Dist: questionary>=2.0; extra == "csvtool"
Dynamic: license-file

![](https://www.heartless.one/images/jotting/en/2026-05-mamonia/mamonia_showoff_copy.png)

A music discovery tool built on the idea that your taste matters more than an algorithm.
Inspired by Engineer Mamoń's Principle / Prawo inżyniera Mamonia.

**mamonia** learns what you enjoy from the music you already listen to. It starts from playlists and libraries you already like, builds a reusable profile of your taste, then explores artist networks and music databases to find fresh releases you might dig. 

It runs through a clean, guided menu - no terminal flags to memorize, no `.env` or `.json` wrangling. 

Your data stays on your machine. No tracking. No mystery. 

Open it up, point it at a playlist, and discover something new. Simple as that.



## How it works:

Give mamonia a Spotify or Tidal playlist (or even a `.txt` or `.csv` file).

Based on this, the tool will:

- **Learn your taste** — examine the artists you listen to, look them up across multiple music databases
- **Explore connections** — find collaborators, similar artists, and shared fan communities
- **Discover candidates** — find releases from everyone connected to the artists you love
- **Handle variants intelligently** — mamonia knows how to pick up the difference between deluxe editions, remasters, and regional versions
- **Create a playlist** on Spotify or Tidal, or save it as `.csv`, `.txt`, or `.json`
- **Respect your time frame** — focusing on the last 6 months, last year, or any era you choose
- **Remember what it has already found** — won't recommend the same thing twice

Everything is stored locally in SQLite: your taste profile, what's already been recommended, cached data, everything. Nothing goes to the cloud.



## Where your data lives:

- **Windows:** `%LOCALAPPDATA%\Mamonia`
- **macOS:** `~/Library/Application Support/Mamonia`
- **Linux:** `${XDG_STATE_HOME}/mamonia` (or `~/.local/state/mamonia`)

This is where your taste profile, recommendation history, cache, and API credentials are kept — safely, locally, just for you.



## Install

```bash
pip install mamonia
```

Then run:

```bash
mamonia
```

A guided menu will walk you through the rest.



## Setup

You'll need API keys from Spotify, Last.fm, Tidal, and ListenBrainz. 

When mamonia runs for the first time, you can enter them - they're saved securely in your user directory.

For all CLI commands and options, see the [CLI Reference](docs/CLI_REFERENCE.md). For full documentation, see [docs/README.md](docs/README.md).



## License

MIT

---

**Something not working as expected?** 
Open an issue and let us know what happened and what you tried.
