Metadata-Version: 2.4
Name: langchain-tunova
Version: 0.1.0
Summary: LangChain integration for the Tunova music generation API (Suno-powered songs for AI agents)
Project-URL: Homepage, https://tunova.ai/integrations
Project-URL: Repository, https://github.com/erliona/langchain-tunova
Project-URL: Documentation, https://tunova.ai/integrations
Project-URL: Issues, https://github.com/erliona/langchain-tunova/issues
Author: Tunova
License: MIT
License-File: LICENSE
Keywords: ai,audio,langchain,music,music-generation,suno,tunova
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: langchain-core<2.0.0,>=0.3.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: requests<3.0.0,>=2.31.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Description-Content-Type: text/markdown

# langchain-tunova

LangChain integration for [Tunova](https://tunova.ai) — an API that turns a text prompt into a complete, ready-to-listen song. This package gives your LangChain agents a music generation tool.

**Agent-friendly billing:** songs are billed only on successful renders — failed generations auto-refund, so autonomous retries are safe. 10 tokens per song, and every account starts with 50 free tokens (no card required).

## Installation

```bash
pip install langchain-tunova
```

## Setup

Get an API key at [tunova.ai](https://tunova.ai) and export it:

```bash
export TUNOVA_API_KEY="your-api-key"
```

(Or pass `api_key="..."` to the tool constructor.)

## Usage

Direct invocation:

```python
from langchain_tunova import TunovaMusicGenerationTool

tool = TunovaMusicGenerationTool()
print(tool.invoke({"prompt": "an upbeat synthwave track about road trips"}))
# Generated "Neon Highway" (192s): https://cdn.tunova.ai/...mp3
```

With an agent:

```python
from langchain.agents import create_agent
from langchain_tunova import TunovaMusicGenerationTool

agent = create_agent(
    model="claude-sonnet-4-5",
    tools=[TunovaMusicGenerationTool()],
)

result = agent.invoke(
    {"messages": [("user", "Make me a chill instrumental lofi track for studying.")]}
)
print(result["messages"][-1].content)
```

Generation takes a few minutes; the tool polls the job and returns the song title, duration, and audio URL. If a render fails, the tool tells the agent that the tokens were auto-refunded — so the agent can simply retry, at no cost.

## Tool reference

| | |
|---|---|
| Tool name | `tunova_generate_song` |
| Arguments | `prompt: str`, `make_instrumental: bool = False` |
| Returns | `Generated "<title>" (<duration>s): <audio_url>` or an error string |
| Auth | `TUNOVA_API_KEY` env var or `api_key=` constructor arg |
| Async | Supported (`await tool.ainvoke(...)`) |

## License

MIT © 2026 Tunova
