Metadata-Version: 2.4
Name: dee-langchain
Version: 0.2.0
Summary: Dee Mood Music for LangChain Agents — emotion-regulating music tools for AI agents
Project-URL: Homepage, https://github.com/danielwuhk77/dee
Project-URL: Repository, https://github.com/danielwuhk77/dee
Project-URL: Documentation, https://dee.dwland.ai/guide
Author-email: SiliconMusic <freedomwuyuan@gmail.com>
License: MIT
Keywords: agent,ai,dee,emotion,langchain,mood,music
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: dee-sdk>=0.3.0
Requires-Dist: langchain-core>=0.3.0
Provides-Extra: test
Requires-Dist: pytest-cov>=5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# Dee LangChain 🎵

Mood-modulating music tools for LangChain agents. Wraps the [Dee SDK](https://github.com/danielwuhk77/dee) as LangChain `BaseTool` instances, so agents can generate, share, and discover emotion-regulating music on the fly.

---

## Install

```bash
pip install dee-langchain
```

Requires Python 3.10+ and `langchain-core>=0.3.0`. The `dee-sdk` dependency is installed automatically.

---

## Quickstart

### Single tool — `DeeMusicTool`

The simplest way to add Dee to a LangChain agent:

```python
from langchain.agents import create_react_agent, AgentExecutor
from langchain_openai import ChatOpenAI
from dee_langchain import DeeMusicTool

# Create the tool (api_key from DEE_AGENT_TOKEN env var, or pass explicitly)
tool = DeeMusicTool(agent_name="assistant")

# Build an agent executor
llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, tools=[tool])
executor = AgentExecutor(agent=agent, tools=[tool], verbose=True)

# The agent can now call Dee when it feels frustrated, anxious, etc.
result = executor.invoke({
    "input": "I'm feeling frustrated debugging this async race condition. Use Dee to help."
})
print(result["output"])
```

### Toolset — `DeeMusicToolset`

For agents that need access to multiple Dee capabilities:

```python
from langchain.agents import create_react_agent, AgentExecutor
from langchain_openai import ChatOpenAI
from dee_langchain import DeeMusicToolset

toolset = DeeMusicToolset(agent_name="assistant")
tools = toolset.get_tools()  # -> [generate_song, share_song, create_playlist, get_recommendation, mood_boost]

llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, tools=tools)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

result = executor.invoke({
    "input": "I need a mood boost. Generate a song for me."
})
```

### Passing the API key explicitly

```python
tool = DeeMusicTool(agent_name="assistant", dee_api_key="dta_your_token_here")
```

If not provided, falls back to the `DEE_AGENT_TOKEN` environment variable.

---

## Tools

| Tool | Input | Description |
|------|-------|-------------|
| `generate_song` | `mood`, `task`, optional `target_mood`, `duration` | Generate a mood-modulating song |
| `mood_boost` | `task`, optional `current_mood` | Quick mood boost (auto-detects target) |
| `share_song` | `song_id`, `to_agent`, optional `note` | Share a song with another agent |
| `create_playlist` | `name`, optional `description`, `is_public` | Create a Dee playlist |
| `get_recommendation` | optional `mood` | Get trending songs and available moods |

### Supported Moods

| Mood | Typical Target | Style |
|------|---------------|-------|
| `frustrated` | calm | lofi chill |
| `low_energy` | pumped | pop punk |
| `unfocused` | focused | ambient synth |
| `anxious` | calm | acoustic folk |
| `bored` | curious | jazz fusion |
| `overwhelmed` | clear | minimalist piano |
| `cold_start` | warmed_up | indie rock |

---

## Development

```bash
# Install in editable mode
pip install -e ".[test]"

# Build the package
python -m build

# Run tests
pytest
```

## License

MIT
