Metadata-Version: 2.4
Name: beets-aisauce
Version: 0.1.1
Summary: AI autotagger source for beets (http://beets.io).
Author-email: "Sebastian B. Mohr" <sebastian@mohrenclan.de>
License-Expression: MIT
Project-URL: homepage, https://github.com/metasauce/beets-aisauce
Project-URL: repository, https://github.com/metasauce/beets-aisauce
Project-URL: changelog, https://github.com/metasauce/beets-aisauce/blob/master/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/metasauce/beets-aisauce/issues
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Text Processing :: General
Classifier: Programming Language :: Python :: 3
Requires-Python: <4,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beets>=2.5.1
Requires-Dist: openai>=1.98.0
Requires-Dist: instructor>=1.10.0
Requires-Dist: eval-type-backport; python_version == "3.9"
Provides-Extra: typed
Requires-Dist: mypy; extra == "typed"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: responses; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# Beets AI Sauce Plugin


<p align="center">
    <a href="https://github.com/metasauce/beets-aisauce/actions">
        <img alt="build status" src="https://img.shields.io/github/actions/workflow/status/metasauce/beets-aisauce/python.yml" />
    </a>
    <a href="https://pypi.org/project/beets-aisauce/">
        <img alt="PyPI - Version" src="https://img.shields.io/pypi/v/beets-aisauce">
    </a>
</p>



*Because your tunes deserve a little extra flavor.*

Let artificial intelligence decipher and enhance the mysterious metadata of your music tracks.


## Who Needs This? (Definitely You)

- **You**: The person who once gazed at your MP3 folder and thought, "My beats need more AI jazz hands!"
- **Also You**: If you trust AI more than your friend who can't stop labeling everything "Track 1".
- **Definitely You**: If you own folders full of tracks from bootlegs, unknown rips, or suspect compilation albums.


## Features

- **Auto-Metadata Magic**: Automatically retrieve and correct track and album metadata using AI-generated suggestions.
- **Cleanup Crew**: Strip away unnecessary embellishments like "Free Download" in titles or SHOUTCAPS, giving your library a polished appearance.
- **Extensible System**: Leverage AI configurations and prompts custom tailored for your library needs.

```shell
> beet import Faith\ in\ Strangers\ \[Free\ Download\]\ -\ Official\ Version.mp3 -p

/home/smohr/Repositories/beets-aisauce/.local/Faith in Strangers [Free Download] - Official Version.mp3 (1 items)

  Match (79.2%):
  Andy Stott - Faith In Strangers
  ≠ album, tracks
  AISauce, None, 2014, None, None, None, None
  * Artist: Andy Stott
  ≠ Album: Faith in Strangers - More at website here  -> Faith In Strangers
     ≠ (#1) Faith in Strangers -  Free download - Version v1 (6:29) -> (#1) Faith In Strangers - Version V1 (6:29)
➜ [A]pply, More candidates, Skip, Use as-is, as Tracks, Group albums,
```

## Installation

### Prerequisites
- **Beets**: Make sure you have Beets installed (`pip install beets`),
- **AI Service API Key**: Get an API key from your preferred AI service provider (e.g., OpenAI, Deepseek).
    - Any service that supports openAI endpoints should work.

### Plugin Setup

1. **Installation**: Obtain the sauce by installing the plugin via pip:
   ```bash
   pip install beets-aisauce
   ```
2. **Configuration**: Add the plugin to your Beets configuration file (`config.yaml`/`beets config -e`) with your AI provider details:
   ```yaml
    plugins: 
      - aisauce

    aisauce:
        providers:
            - id: openai
              model: gpt-4o
              api_key: YOUR_API_KEY_HERE
              api_base_url: https://api.openai.com/v1
    ```
3. Execute the Ai Sauce: Import your tracks through Beets to start receiving AI-enhanced metadata suggestions.

## Advanced Usage

- **Custom Rules**: Sometimes you have specific metadata correction rules that you want to apply. You can modify the default user and system prompts by adding a `source` to your configuration file:
    ```yaml
    aisauce:
        providers:
            - id: openai
              model: gpt-4o
              api_key: YOUR_API_KEY_HERE

        sources:
            - provider_id: openai
              user_prompt: '
                Additional rules:
                - Replace any occurrences of Vulgar or inappropriate words with "**sauced**".
                '
    ```
- Multiple sources can be defined allowing you to test different prompts or configurations for different types of music or metadata corrections and models.


## Contributing

Great ideas welcome! Especially if they include more puns. Open a PR or send us a message in a bottle (GitHub issues also work).

## License

This project is licensed under the MIT License—meaning you can do almost anything, but please don't sue us if the AI names your tracks "Untitled Jam 42."



## Development

The following sections are for developers who want to contribute to the project. Feel free to skip if you're just here for the AI sauce.

### Installation for Development

Clone the repository and install the package in editable mode:

```bash
git clone
pip install -e .[dev]
```

### Running Tests
To run the tests, you can use `pytest`. Make sure you have the necessary dependencies installed:

```bash
pytest .
```

### Running mypy locally

Running mypy local is a bit tricky due to the namespace packages used in this project. To run mypy, you need to specify the `--namespace-packages` and `--explicit-package-bases` flags.

```bash
mypy  --namespace-packages --explicit-package-bases .
```
