feat(examples): add Song Meaning Analyzer agent

examples/song-meaning-agent/.env.example

@@ -0,0 +1 @@
+OPENROUTER_API_KEY=your_openrouter_api_key_here

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` |

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)

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)