From 39092a25d0949deaf0b615d88144d51a48e00bec Mon Sep 17 00:00:00 2001 From: Subhajit Das Date: Fri, 29 May 2026 06:48:24 +0530 Subject: [PATCH 1/4] feat(examples): add Song Meaning Analyzer agent Agno + OpenRouter agent that analyzes song meanings with structured SUMMARY / MEANING / EVIDENCE output. Matches Bindu Agents Tracker spec. Verified locally end-to-end with Bohemian Rhapsody test query. --- examples/song-meaning-agent/.env.example | 1 + examples/song-meaning-agent/README.md | 65 ++++++++ .../skills/song-meaning-skill/skill.yaml | 109 +++++++++++++ .../song-meaning-agent/song_meaning_agent.py | 143 ++++++++++++++++++ 4 files changed, 318 insertions(+) create mode 100644 examples/song-meaning-agent/.env.example create mode 100644 examples/song-meaning-agent/README.md create mode 100644 examples/song-meaning-agent/skills/song-meaning-skill/skill.yaml create mode 100644 examples/song-meaning-agent/song_meaning_agent.py diff --git a/examples/song-meaning-agent/.env.example b/examples/song-meaning-agent/.env.example new file mode 100644 index 000000000..3a8df4dc5 --- /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 000000000..7a88587ae --- /dev/null +++ b/examples/song-meaning-agent/README.md @@ -0,0 +1,65 @@ +# 🎵 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 + +``` +SUMMARY +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 + +``` +song-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 000000000..c29aaeba2 --- /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 (~165 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, ~165 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 000000000..597bae42e --- /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 ~165 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) From 4365ae4228aad9dfb899ec4b5eb7c436d3021c50 Mon Sep 17 00:00:00 2001 From: Subhajit Das Date: Fri, 29 May 2026 07:18:48 +0530 Subject: [PATCH 2/4] fix: address CodeRabbit feedback (MD040 fences, word count per bullet) --- examples/song-meaning-agent/README.md | 7 +++---- .../skills/song-meaning-skill/skill.yaml | 4 ++-- examples/song-meaning-agent/song_meaning_agent.py | 2 +- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/examples/song-meaning-agent/README.md b/examples/song-meaning-agent/README.md index 7a88587ae..538935bb1 100644 --- a/examples/song-meaning-agent/README.md +++ b/examples/song-meaning-agent/README.md @@ -13,8 +13,7 @@ to uncover and articulate the true meaning behind any musical work. ## Output Format -``` -SUMMARY +```text`r`nSUMMARY A single sentence (25 words max) capturing the song's core meaning. MEANING @@ -47,8 +46,7 @@ The agent runs at `http://localhost:3773`. ## Project Structure -``` -song-meaning-agent/ +```text`r`nsong-meaning-agent/ ├── song_meaning_agent.py # Main agent + bindufy() ├── .env.example # Environment variables ├── skills/ @@ -63,3 +61,4 @@ song-meaning-agent/ |---|---|---| | `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 index c29aaeba2..61c39c0cc 100644 --- a/examples/song-meaning-agent/skills/song-meaning-skill/skill.yaml +++ b/examples/song-meaning-agent/skills/song-meaning-skill/skill.yaml @@ -13,7 +13,7 @@ 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 (~165 words each) covering themes, symbolism, and context + - 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() @@ -96,7 +96,7 @@ capabilities_detail: output_format: structure: SUMMARY → MEANING → EVIDENCE summary_length: 25 words maximum - meaning_bullets: 3-5 bullets, ~165 words each + 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 diff --git a/examples/song-meaning-agent/song_meaning_agent.py b/examples/song-meaning-agent/song_meaning_agent.py index 597bae42e..9c86c92e6 100644 --- a/examples/song-meaning-agent/song_meaning_agent.py +++ b/examples/song-meaning-agent/song_meaning_agent.py @@ -43,7 +43,7 @@ A single sentence (25 words max) capturing the song's core meaning. **MEANING** -3–5 bullet points (each ~165 words) exploring: +3–5 bullet points (each ~65 words) exploring: - Central themes and emotional narrative - Symbolic imagery and metaphors used - Cultural, historical, or biographical context From 02d83acf055af20c625d688f8ad239cdb96b2d65 Mon Sep 17 00:00:00 2001 From: Subhajit Das Date: Fri, 29 May 2026 07:23:30 +0530 Subject: [PATCH 3/4] fix: add trailing newline to README.md --- examples/song-meaning-agent/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/song-meaning-agent/README.md b/examples/song-meaning-agent/README.md index 538935bb1..dad547ea9 100644 --- a/examples/song-meaning-agent/README.md +++ b/examples/song-meaning-agent/README.md @@ -62,3 +62,4 @@ The agent runs at `http://localhost:3773`. | `OPENROUTER_API_KEY` | Yes | OpenRouter API key | | `BINDU_DEPLOYMENT_URL` | No | Override default `http://localhost:3773` | + From a9b5cbbf396e2c70cd9ff612485b66d42615fbd6 Mon Sep 17 00:00:00 2001 From: Subhajit Das Date: Fri, 29 May 2026 07:25:47 +0530 Subject: [PATCH 4/4] fix: ensure all files end with newline --- examples/song-meaning-agent/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/examples/song-meaning-agent/README.md b/examples/song-meaning-agent/README.md index dad547ea9..c4d4f719f 100644 --- a/examples/song-meaning-agent/README.md +++ b/examples/song-meaning-agent/README.md @@ -61,5 +61,3 @@ The agent runs at `http://localhost:3773`. |---|---|---| | `OPENROUTER_API_KEY` | Yes | OpenRouter API key | | `BINDU_DEPLOYMENT_URL` | No | Override default `http://localhost:3773` | - -