diff --git a/examples/song-meaning-agent/.env.example b/examples/song-meaning-agent/.env.example new file mode 100644 index 00000000..3a8df4dc --- /dev/null +++ b/examples/song-meaning-agent/.env.example @@ -0,0 +1 @@ +OPENROUTER_API_KEY=your_openrouter_api_key_here diff --git a/examples/song-meaning-agent/README.md b/examples/song-meaning-agent/README.md new file mode 100644 index 00000000..c4d4f719 --- /dev/null +++ b/examples/song-meaning-agent/README.md @@ -0,0 +1,63 @@ +# 🎵 Song Meaning Analyzer + +A Bindu agent that deeply researches songs, lyrics, artists, and cultural context +to uncover and articulate the true meaning behind any musical work. + +## Features + +- Accepts any song title, artist name, or pasted lyrics +- Produces structured analyses: SUMMARY, MEANING, and EVIDENCE +- Grounds every claim in lyrics, artist statements, or documented context +- Handles ambiguous songs by surfacing multiple interpretations +- Live A2A microservice via `bindufy()` + +## Output Format + +```text`r`nSUMMARY +A single sentence (25 words max) capturing the song's core meaning. + +MEANING +- 3–5 bullets (~165 words each) covering themes, symbolism, and context + +EVIDENCE +- 3–5 bullets (~15 words each) citing lyrics and artist statements +``` + +## Setup + +```bash +cp .env.example .env +# Add your OPENROUTER_API_KEY to .env + +uv add bindu agno python-dotenv +python song_meaning_agent.py +``` + +The agent runs at `http://localhost:3773`. + +## Example Queries + +```json +{"role": "user", "content": "What does 'Bohemian Rhapsody' by Queen really mean?"} +{"role": "user", "content": "Analyze the deeper meaning behind these lyrics: ..."} +{"role": "user", "content": "Explain the themes and symbolism in this artist's work."} +{"role": "user", "content": "Uncover the meaning of 'The Sound of Silence' based on artist context."} +``` + +## Project Structure + +```text`r`nsong-meaning-agent/ +├── song_meaning_agent.py # Main agent + bindufy() +├── .env.example # Environment variables +├── skills/ +│ └── song-meaning-skill/ +│ └── skill.yaml # Skill definition +└── README.md +``` + +## Environment Variables + +| Variable | Required | Description | +|---|---|---| +| `OPENROUTER_API_KEY` | Yes | OpenRouter API key | +| `BINDU_DEPLOYMENT_URL` | No | Override default `http://localhost:3773` | diff --git a/examples/song-meaning-agent/skills/song-meaning-skill/skill.yaml b/examples/song-meaning-agent/skills/song-meaning-skill/skill.yaml new file mode 100644 index 00000000..61c39c0c --- /dev/null +++ b/examples/song-meaning-agent/skills/song-meaning-skill/skill.yaml @@ -0,0 +1,109 @@ +id: song-meaning-skill +name: Song Meaning Skill +version: 1.0.0 +author: your.email@example.com +description: > + Deeply researches songs, lyrics, artists, and cultural context to uncover + and articulate the true meaning behind any musical work. Produces structured + analyses with a summary sentence, thematic bullet points, and evidence-backed + citations. Powered by OpenRouter and exposed as a live A2A-compliant Bindu + microservice. + +features: + - Accept any song title, artist name, or pasted lyrics as input + - Research lyrics, artist interviews, liner notes, and cultural context + - Produce a 25-word SUMMARY sentence capturing the song's core meaning + - Write 3-5 MEANING bullets (~65 words each) covering themes, symbolism, and context + - Provide 3-5 EVIDENCE bullets (~15 words each) citing lyrics and artist statements + - Handle ambiguous songs by surfacing multiple interpretations + - Deployed as a live Bindu microservice via bindufy() + - A2A / X402 protocol-compliant out of the box + +tags: + - music + - lyrics + - song-analysis + - thematic-extraction + - lyric-interpretation + - artist-context-research + - musical-symbolism + - evidence-based-conclusion + - openrouter + +input_modes: + - text/plain # Song title + artist, or pasted lyrics + +output_modes: + - text/plain # Structured Markdown analysis + +examples: + - input: "What does 'Bohemian Rhapsody' by Queen really mean?" + output: | + SUMMARY + A theatrical journey through guilt, fate, and acceptance told across + multiple operatic personas by Freddie Mercury. + + MEANING + - The song opens with a condemned narrator facing execution, establishing + the central tension between agency and fate. Mercury reportedly described + it as a random collection of ideas, but the recurring motif of a young + man unable to escape consequences suggests a deeper autobiographical + thread about identity and self-reckoning. + - The operatic middle section fragments the narrator into multiple voices + arguing over culpability. Bismillah (Arabic for "in the name of God") + and Beelzebub represent the spiritual battle for the narrator's soul, + drawing on Mercury's Zoroastrian upbringing and his complex relationship + with religion and mortality. + + EVIDENCE + - "Mama, just killed a man" establishes the irreversible act driving the narrative. + - Mercury told friends the lyrics were deliberately left open to interpretation. + + - input: "Analyze the meaning of 'The Sound of Silence' by Simon & Garfunkel" + output: | + SUMMARY + A meditation on modern alienation where people worship mass media and + hollow spectacle instead of genuine human connection. + + MEANING + - Written by Paul Simon in 1964 following the JFK assassination, the song + captures a generation's sense of disconnection and disillusionment with + American optimism. The darkness is not literal night but emotional isolation + that persists even in daylight. + - The neon god the people bow and pray to is widely read as television, + the dominant mass medium of the era. Simon observed people passively + consuming broadcast culture rather than speaking honestly to one another, + creating communities bound by spectacle rather than meaning. + + EVIDENCE + - "People talking without speaking, hearing without listening" defines + the failure of communication as the song's core theme. + - Simon confirmed the song was written in a darkened bathroom to aid concentration. + +capabilities_detail: + lyric_analysis: + description: > + Interprets lyrical content through close reading, identifying metaphors, + narrative structure, and recurring motifs. + approach: Evidence-based; claims tied to specific lines or documented artist statements. + + contextual_research: + description: > + Grounds interpretation in artist biography, historical moment, genre conventions, + and cultural reception. + sources: Artist interviews, liner notes, critical essays, documented fan analysis. + + output_format: + structure: SUMMARY → MEANING → EVIDENCE + summary_length: 25 words maximum + meaning_bullets: 3-5 bullets, ~65 words each + evidence_bullets: 3-5 bullets, ~15 words each + markdown: plain Markdown, no bold or italics inside bullet points + + transport: + protocol: A2A (JSON-RPC over HTTP) + endpoint: POST / + port: 3773 + auth: disabled (configurable via config.auth.enabled) + storage: in-memory (configurable) + scheduler: in-memory (configurable) diff --git a/examples/song-meaning-agent/song_meaning_agent.py b/examples/song-meaning-agent/song_meaning_agent.py new file mode 100644 index 00000000..9c86c92e --- /dev/null +++ b/examples/song-meaning-agent/song_meaning_agent.py @@ -0,0 +1,143 @@ +""" +Song Meaning Analyzer — Bindu Example + +An expert agent that deeply researches songs, lyrics, artists, and context +to uncover and articulate the true meaning behind any musical work. + +Prerequisites +------------- + uv add bindu agno python-dotenv + +Usage +----- + export OPENROUTER_API_KEY="your_api_key_here" # pragma: allowlist secret + python song_meaning_agent.py + +The agent will be live at http://localhost:3773 +Send it a message like: + {"role": "user", "content": "What does 'Bohemian Rhapsody' really mean?"} +or: + {"role": "user", "content": "Analyze the meaning of 'The Sound of Silence' by Simon & Garfunkel"} +""" + +import os + +from agno.agent import Agent +from agno.models.openrouter import OpenRouter +from bindu.penguin.bindufy import bindufy +from dotenv import load_dotenv + +load_dotenv() + +# --------------------------------------------------------------------------- +# 1. Agent definition +# --------------------------------------------------------------------------- + +INSTRUCTIONS = """ +You are an expert songwriter, musicologist, and cultural analyst with deep knowledge +of music history, lyrical symbolism, and artistic context across all genres and eras. + +When asked to analyze a song, you MUST follow this exact structure: + +**SUMMARY** +A single sentence (25 words max) capturing the song's core meaning. + +**MEANING** +3–5 bullet points (each ~65 words) exploring: +- Central themes and emotional narrative +- Symbolic imagery and metaphors used +- Cultural, historical, or biographical context +- The artist's intent or stated interpretation (if known) +- How the musical elements reinforce the lyrical meaning + +**EVIDENCE** +3–5 bullet points (each ~15 words) citing: +- Specific lyrics that support your interpretation +- Artist interviews, liner notes, or documented statements +- Fan analysis or cultural reception where relevant + +Rules: +- Output in plain Markdown without bold or italics inside bullet points +- Be evidence-based: ground every claim in lyrics, artist statements, or documented context +- If the song or artist is unfamiliar, say so clearly rather than speculating +- Cover multiple interpretations when the song is genuinely ambiguous +""".strip() + +agent = Agent( + instructions=INSTRUCTIONS, + model=OpenRouter( + id="openai/gpt-4o-mini", + api_key=os.getenv("OPENROUTER_API_KEY"), # pragma: allowlist secret + ), + markdown=True, +) + + +# --------------------------------------------------------------------------- +# 2. Bindu configuration +# --------------------------------------------------------------------------- + +config = { + "author": "your.email@example.com", + "name": "song_meaning_agent", + "description": ( + "An expert songwriter and musician that deeply researches songs, lyrics, " + "artists, and context to uncover and articulate the true meaning behind " + "any musical work." + ), + "version": "1.0.0", + "capabilities": { + "text_analysis": ["lyric-interpretation", "thematic-extraction", "musical-symbolism"], + "research": ["artist-context-research", "evidence-based-conclusion"], + "streaming": False, + }, + "skills": ["skills/song-meaning-skill"], + "auth": {"enabled": False}, + "storage": {"type": "memory"}, + "scheduler": {"type": "memory"}, + "deployment": { + "url": os.getenv("BINDU_DEPLOYMENT_URL", "http://localhost:3773"), + "expose": True, + "cors_origins": ["http://localhost:5173"], + }, +} + + +# --------------------------------------------------------------------------- +# 3. Handler +# --------------------------------------------------------------------------- + +def handler(messages: list[dict[str, str]]): + """Analyze the meaning of a song based on the user's query. + + Args: + messages: Standard A2A message list, e.g. + [{"role": "user", "content": "What does Bohemian Rhapsody mean?"}] + + Returns: + Structured song meaning analysis with SUMMARY, MEANING, and EVIDENCE sections. + """ + try: + user_messages = [m for m in messages if m.get("role") == "user"] + if not user_messages: + return "No query received. Please ask about a song, e.g. 'What does Bohemian Rhapsody mean?'" + + query = user_messages[-1].get("content", "").strip() + if not query: + return "Empty query. Please name a song or paste lyrics you'd like analyzed." + + result = agent.run(input=messages) + return result + + except Exception as e: + return f"Error analyzing song: {str(e)}" + + +# --------------------------------------------------------------------------- +# 4. Entry point +# --------------------------------------------------------------------------- + +if __name__ == "__main__": + print("🎵 Song Meaning Analyzer running at http://localhost:3773") + print("🎸 Example: {\"role\": \"user\", \"content\": \"What does Bohemian Rhapsody really mean?\"}") + bindufy(config, handler)