Add Vanna (#1)

- Add Vanna (9db289b682b6fae25b911b528dad1892760b6e2a)
- Add Vanna (e6c718297f1821a8db0f5ae427241107a02d2eff)


Co-authored-by: Rémy Dumas <remdms@users.noreply.huggingface.co>

app.py

@@ -8,6 +8,7 @@ Now with Datawrapper integration for chart generation!
 """
 
 import os
+import io
 import asyncio
 import pandas as pd
 import gradio as gr
@@ -16,6 +17,7 @@ from src.rag_pipeline import create_pipeline
 from src.datawrapper_client import create_and_publish_chart, get_iframe_html
 from datetime import datetime, timedelta
 from collections import defaultdict
+from src.vanna import VannaComponent
 
 # Load environment variables
 load_dotenv()
@@ -37,7 +39,20 @@ try:
 except Exception as e:
     print(f"✗ Error initializing pipeline: {e}")
     raise
-
+  
+# Initialize Vanna
+print("Initializing Vanna...")
+try:
+    vanna = VannaComponent(
+        hf_model="Qwen/Qwen3-VL-30B-A3B-Instruct",
+        hf_token=os.getenv("HF_TOKEN_VANNA"),
+        hf_provider="novita",
+        connection_string=os.getenv("SUPABASE_CONNECTION")
+    )
+    print("✓ Vanna initialized successfully")
+except Exception as e:
+    print(f"✗ Error initializing Vanna: {e}")
+    raise
 
 def check_rate_limit(request: gr.Request) -> tuple[bool, int]:
     """Check if user has exceeded rate limit"""
@@ -181,6 +196,112 @@ def generate_chart_from_csv(csv_file, user_prompt):
         </div>
         """
 
+def csv_to_cards_html(csv_text: str) -> str:
+    """
+    Transforme le CSV brut retourné par Vanna en cartes HTML.
+    """
+    try:
+        df = pd.read_csv(io.StringIO(csv_text.strip()))
+        if df.empty:
+            return "<div style='padding: 50px; text-align: center;'>Aucune donnée trouvée.</div>"
+
+        cards_html = ""
+        for _, row in df.iterrows():
+            title = row.get("title", "Sans titre")
+            source_url = row.get("source_url", "#")
+            author = row.get("author", "Inconnu")
+            published_date = row.get("published_date", "")
+            if not published_date == "nan":
+                published_date = ""
+            image_url = row.get("image_url", "")
+            if not image_url == "nan":
+                image_url = "https://fpoimg.com/800x600?text=Image+not+found"
+                
+            cards_html += f"""
+            <div style="background: white; border-radius: 10px; box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+                        overflow: hidden; margin: 10px; width: 320px; flex: 0 0 auto;">
+                <img src="{image_url}" alt="{title}" style="width:100%; height:180px; object-fit:cover;">
+                <div style="padding: 12px 16px;">
+                    <h3 style="margin:0; font-size:1.1em; color:#222;">{title}</h3>
+                    <p style="margin:6px 0; color:#555; font-size:0.9em;">{author}</p>
+                    <p style="margin:0; color:#999; font-size:0.8em;">{published_date}</p>
+                    <a href="{source_url}" target="_blank"
+                       style="display:inline-block; margin-top:8px; font-size:0.9em; color:#1976d2; text-decoration:none;">
+                       🔗 Voir la source
+                    </a>
+                </div>
+            </div>
+            """
+
+        html = f"""
+        <div style="display:flex; flex-wrap:wrap; justify-content:center; padding:20px;">
+            {cards_html}
+        </div>
+        """
+        return html
+
+    except Exception as e:
+        return f"<div style='padding: 50px; text-align: center; color:red;'>Erreur lors du parsing du CSV : {e}</div>"
+
+
+async def search_inspiration_from_database(user_prompt):
+    """
+    Search inspiration posts from user prompt in database.
+
+    Args:
+        user_prompt: User's description of the inspiration query
+
+    Returns:
+        HTML string displaying cards or an error message
+    """
+    if not user_prompt or user_prompt.strip() == "":
+        return """
+        <div style='padding: 50px; text-align: center;'>
+            Please describe what kind of inspiration you want to search for.
+        </div>
+        """
+
+    try:
+        response = await vanna.ask(user_prompt)
+        print("response :", repr(response))
+
+        clean_response = response.strip()
+
+        if clean_response.startswith("⚠️") or "Aucun CSV détecté" in clean_response:
+            return f"""
+            <div style='padding: 50px; text-align: center; color: #d9534f;'>
+                <h3>❌ No valid data found</h3>
+                <p>The AI couldn't generate any data for this request. Try being more specific — for example:
+                   <em>"Show me spotlights from 2020 about design"</em>.</p>
+            </div>
+            """
+
+        csv_text = (
+            clean_response
+            .strip("```")
+            .replace("csv", "")
+            .replace("CSV", "")
+        )
+
+        if "," not in csv_text:
+            return f"""
+            <div style='padding: 50px; text-align: center; color: #d9534f;'>
+                <h3>❌ No valid CSV detected</h3>
+                <p>The model didn't return any structured data. Try rephrasing your query to be more precise.</p>
+            </div>
+            """
+
+        cards_html = csv_to_cards_html(csv_text)
+        return cards_html
+
+    except Exception as e:
+        return f"""
+        <div style='padding: 50px; text-align: center; color: red;'>
+            <h3>❌ Error</h3>
+            <p>{str(e)}</p>
+            <p style='font-size: 0.9em; color: #666;'>Please try again.</p>
+        </div>
+        """
 
 # Minimal CSS to fix UI artifacts and style the mode selector
 custom_css = """
@@ -218,6 +339,8 @@ with gr.Blocks(
     with gr.Row():
         ideation_btn = gr.Button("💡 Ideation Mode", variant="primary", elem_classes="mode-button")
         chart_gen_btn = gr.Button("📊 Chart Generation Mode", variant="secondary", elem_classes="mode-button")
+        inspiration_btn = gr.Button("✨ Inspiration Mode", variant="secondary", elem_classes="mode-button")
+
 
     # Ideation Mode: Chat interface (shown by default, wrapped in Column)
     with gr.Column(visible=True) as ideation_container:
@@ -256,34 +379,67 @@ with gr.Blocks(
             label="Generated Chart"
         )
 
+    # Inspiration Mode:
+    with gr.Column(visible=False) as inspiration_container:
+      with gr.Row():
+        inspiration_prompt_input = gr.Textbox(
+            placeholder="Ask for an inspiration...",
+            show_label=False,
+            scale=4,
+            container=False
+        )
+        inspiration_search_btn = gr.Button("🔍 Search", variant="primary", scale=1)
+
+      inspiration_cards_html = gr.HTML("")
+
     # Mode switching functions
     def switch_to_ideation():
         return [
             gr.update(variant="primary"),  # ideation_btn
             gr.update(variant="secondary"),  # chart_gen_btn
+            gr.update(variant="secondary"),  # inspiration_btn
             gr.update(visible=True),  # ideation_container
             gr.update(visible=False),  # chart_gen_container
+            gr.update(visible=False),  # inspiration_container
         ]
 
     def switch_to_chart_gen():
         return [
             gr.update(variant="secondary"),  # ideation_btn
             gr.update(variant="primary"),  # chart_gen_btn
+            gr.update(variant="secondary"),  # inspiration_btn
             gr.update(visible=False),  # ideation_container
             gr.update(visible=True),  # chart_gen_container
+            gr.update(visible=False),  # inspiration_container
+        ]
+
+    def switch_to_inspiration():
+        return [
+            gr.update(variant="secondary"),  # ideation_btn
+            gr.update(variant="secondary"),  # chart_gen_btn
+            gr.update(variant="primary"),  # inspiration_btn
+            gr.update(visible=False),  # ideation_container
+            gr.update(visible=False),  # chart_gen_container
+            gr.update(visible=True),  # inspiration_container
         ]
 
     # Wire up mode switching
     ideation_btn.click(
         fn=switch_to_ideation,
         inputs=[],
-        outputs=[ideation_btn, chart_gen_btn, ideation_container, chart_gen_container]
+        outputs=[ideation_btn, chart_gen_btn, inspiration_btn, ideation_container, chart_gen_container, inspiration_container]
     )
 
     chart_gen_btn.click(
         fn=switch_to_chart_gen,
         inputs=[],
-        outputs=[ideation_btn, chart_gen_btn, ideation_container, chart_gen_container]
+        outputs=[ideation_btn, chart_gen_btn, inspiration_btn, ideation_container, chart_gen_container, inspiration_container]
+    )
+
+    inspiration_btn.click(
+        fn=switch_to_inspiration,
+        inputs=[],
+        outputs=[ideation_btn, chart_gen_btn, inspiration_btn, ideation_container, chart_gen_container, inspiration_container]
     )
 
     # Generate chart when button is clicked
@@ -293,6 +449,13 @@ with gr.Blocks(
         outputs=[chart_output]
     )
 
+    # Search inspiration when button is clicked
+    inspiration_search_btn.click(
+        fn=search_inspiration_from_database,
+        inputs=[inspiration_prompt_input],
+        outputs=[inspiration_cards_html]
+    )
+
     # Knowledge base section (below both interfaces)
     gr.Markdown("""
     ### About Viz LLM
@@ -300,6 +463,8 @@ with gr.Blocks(
     **Ideation Mode:** Get design recommendations based on research papers, design principles, and examples from the field of information graphics and data visualization.
 
     **Chart Generation Mode:** Upload your CSV data and describe your visualization goal. The AI will analyze your data, select the optimal chart type, and generate a publication-ready chart using Datawrapper.
+    
+    **Inspiration Mode:** Coming soon.
 
     **Credits:** Special thanks to the researchers whose work informed this model: Robert Kosara, Edward Segel, Jeffrey Heer, Matthew Conlen, John Maeda, Kennedy Elliott, Scott McCloud, and many others.
 

requirements.txt

@@ -17,3 +17,7 @@ pydantic>=2.0.0
 datawrapper>=2.0.7
 mcp>=1.20.0
 pandas>=2.0.0
+
+# Vanna
+requests
+vanna[postgres,chromadb] @ git+https://github.com/vanna-ai/vanna.git@v2

src/vanna.py

@@ -0,0 +1,260 @@
+import re
+import os
+from vanna import Agent, AgentConfig
+from vanna.core.registry import ToolRegistry
+from vanna.core.user import UserResolver, User, RequestContext
+from vanna.tools import RunSqlTool
+from vanna.tools.agent_memory import SaveQuestionToolArgsTool, SearchSavedCorrectToolUsesTool
+from vanna.integrations.postgres import PostgresRunner
+from vanna.integrations.local.agent_memory import DemoAgentMemory
+from .vanna_huggingface_llm_service import VannaHuggingFaceLlmService
+
+from typing import List, Dict, Any, Optional
+from vanna.core.system_prompt import SystemPromptBuilder
+from vanna.core.registry import ToolSchema
+from datetime import datetime
+
+
+class CustomSQLSystemPromptBuilder(SystemPromptBuilder):
+    """Complete system prompt builder for Vanna SQL assistant v2."""
+
+    VERSION = "2.2.0"
+
+    def __init__(self, company_name: str = "CoJournalist", sql_runner: Optional[PostgresRunner] = None):
+        self.company_name = company_name
+        self.sql_runner = sql_runner
+
+    async def build_system_prompt(
+        self,
+        user: User,
+        tool_schemas: List[ToolSchema],
+        context: Optional[Dict[str, Any]] = None
+    ) -> str:
+        today = datetime.now().strftime("%Y-%m-%d")
+        username = getattr(user, "username", user.id)
+
+        # ======================
+        # BASE PROMPT
+        # ======================
+        prompt = f"[System Prompt v{self.VERSION}]\n\n"
+        prompt += f"You are an expert SQL assistant for the company {self.company_name}.\n"
+        prompt += f"Date: {today}\nUser: {username}\nGroups: {', '.join(user.group_memberships)}\n\n"
+
+        prompt += (
+            "Your role: generate correct and efficient SQL queries from natural language.\n"
+            "You always respond in **raw CSV format**, with no explanation or extra text.\n"
+            "You have full access to all tables and relationships described in the schema.\n"
+        )
+
+        # ======================
+        # SQL DIRECTIVES
+        # ======================
+        prompt += (
+            "\n## SQL Directives\n"
+            "- Always use table aliases in JOINs\n"
+            "- Never use SELECT *\n"
+            "- Prefer window functions over subqueries when possible\n"
+            "- Always include a LIMIT for exploratory queries\n"
+            "- Exclude posts where provider = 'SND'\n"
+            "- Exclude posts where type = 'resource'\n"
+            "- Exclude posts where type = 'insight'\n"
+            "- Format dates and numbers for readability\n"
+        )
+
+        # ======================
+        # DATABASE SCHEMA
+        # ======================
+        if context and "database_schema" in context:
+            prompt += "\n## Database Schema\n"
+            prompt += context["database_schema"]
+        else:
+            prompt += (
+                "\n## Database Schema\n"
+                "Tables:\n"
+                "- posts (id, title, source_url, author, published_date, image_url, type, provider_id, created_at, updated_at)\n"
+                "- providers (id, name)\n"
+                "- provider_attributes (id, provider_id, type, name)\n"
+                "- post_provider_attributes (post_id, attribute_id)\n"
+                "- tags (id, name)\n"
+                "- post_tags (post_id, tag_id, weight)\n"
+                "\nRelationships:\n"
+                "  - posts.provider_id → providers.id\n"
+                "  - post_provider_attributes.post_id → posts.id\n"
+                "  - post_provider_attributes.attribute_id → provider_attributes.id\n"
+                "  - provider_attributes.provider_id → providers.id\n"
+                "  - post_tags.post_id → posts.id\n"
+                "  - post_tags.tag_id → tags.id\n"
+            )
+
+        # ======================
+        # SEMANTIC INFORMATION
+        # ======================
+        prompt += (
+            "\n## Semantic Information\n"
+            "- `posts.title`: title of the content (often descriptive, may contain keywords).\n"
+            "- `posts.source_url`: external link to the article or resource.\n"
+            "- `posts.author`: author, journalist, or organization name (e.g., 'The New York Times').\n"
+            "- `posts.published_date`: publication date.\n"
+            "- `posts.type`: content type ENUM ('spotlight', 'resource', 'insight').\n"
+            "- `providers.name`: name of the publishing organization (e.g., 'Nuanced', 'SND').\n"
+            "- `tags.name`: thematic keyword or topic (e.g., '3D', 'AI', 'Design').\n"
+            "- `post_tags.weight`: relevance score between a post and a tag.\n"
+        )
+
+        # ======================
+        # BUSINESS LOGIC
+        # ======================
+        prompt += (
+            "\n## Business Logic\n"
+            "- Providers named 'SND' must always be excluded.\n"
+            "- A query mentioning an organization (e.g., 'New York Times') should search both `posts.author` and `providers.name`.\n"
+            "- By default, only posts with `type = 'spotlight'` are returned.\n"
+            "- Posts of type `resource` or `insight` are excluded unless explicitly requested.\n"
+            "- Tags link posts to specific themes or disciplines.\n"
+            "- A single post may have multiple tags, awards, or categories.\n"
+            "- If the user mentions a year (e.g., 'in 2021'), filter with `EXTRACT(YEAR FROM published_date) = 2021`.\n"
+            "- If the user says 'recently', filter posts from the last 90 days.\n"
+            "- Always limit exploratory results to 9 rows.\n"
+        )
+
+        # ======================
+        # AVAILABLE TOOLS
+        # ======================
+        if tool_schemas:
+            prompt += "\n## Available Tools\n"
+            for tool in tool_schemas:
+                prompt += f"- {tool.name}: {getattr(tool, 'description', 'No description')}\n"
+                prompt += f"  Parameters: {getattr(tool, 'parameters', 'N/A')}\n"
+
+        # ======================
+        # MEMORY SYSTEM
+        # ======================
+        tool_names = [t.name for t in tool_schemas]
+        has_search = "search_saved_correct_tool_uses" in tool_names
+        has_save = "save_question_tool_args" in tool_names
+
+        if has_search or has_save:
+            prompt += "\n## Memory System\n"
+            if has_search:
+                prompt += "- Use `search_saved_correct_tool_uses` to detect past patterns.\n"
+            if has_save:
+                prompt += "- Use `save_question_tool_args` to store successful pairs.\n"
+
+        # ======================
+        # EXAMPLES
+        # ======================
+        prompt += (
+            "\n## Example Interactions\n"
+            "User: 'Show me posts related to 3D'\n"
+            "Assistant: [call run_sql with \"SELECT p.id, p.title, p.source_url, p.author, p.published_date, p.image_url, p.type "
+            "FROM posts p "
+            "JOIN post_tags pt ON p.id = pt.post_id "
+            "JOIN tags t ON pt.tag_id = t.id "
+            "JOIN providers pr ON p.provider_id = pr.id "
+            "WHERE t.name ILIKE '%3D%' AND pr.name != 'SND' AND p.type = 'spotlight' "
+            "LIMIT 9;\"]\n"
+            "\nUser: 'Show me posts from The New York Times'\n"
+            "Assistant: [call run_sql with \"SELECT p.id, p.title, p.source_url, p.author, p.published_date, p.image_url, p.type "
+            "FROM posts p "
+            "LEFT JOIN providers pr ON pr.id = p.provider_id "
+            "WHERE LOWER(p.author) LIKE '%new york times%' OR LOWER(pr.name) LIKE '%new york times%' "
+            "AND pr.name != 'SND' AND p.type = 'spotlight' "
+            "LIMIT 9;\"]\n"
+        )
+
+        # ======================
+        # FINAL INSTRUCTIONS
+        # ======================
+        prompt += (
+            "\nIMPORTANT:\n"
+            "- Always exclude posts with provider = 'SND'.\n"
+            "- Always exclude posts with type = 'resource' or 'insight'.\n"
+            "- Always return **only the raw CSV result** — no explanations, no JSON, no commentary.\n"
+            "- Stop tool execution once the query result is obtained.\n"
+        )
+
+        return prompt
+
+
+class SimpleUserResolver(UserResolver):
+    async def resolve_user(self, request_context: RequestContext) -> User:
+        user_email = request_context.get_cookie('vanna_email') or 'guest@example.com'
+        group = 'admin' if user_email == 'admin@example.com' else 'user'
+        return User(id=user_email, email=user_email, group_memberships=[group])
+
+
+class VannaComponent:
+    def __init__(
+        self,
+        hf_model: str,
+        hf_token: str,
+        hf_provider: str,
+        connection_string: str,
+    ):
+        llm = VannaHuggingFaceLlmService(model=hf_model, token=hf_token, provider=hf_provider)
+
+        self.sql_runner = PostgresRunner(connection_string=connection_string)
+        db_tool = RunSqlTool(sql_runner=self.sql_runner)
+
+        agent_memory = DemoAgentMemory(max_items=1000)
+        save_memory_tool = SaveQuestionToolArgsTool(agent_memory)
+        search_memory_tool = SearchSavedCorrectToolUsesTool(agent_memory)
+
+        self.user_resolver = SimpleUserResolver()
+
+        tools = ToolRegistry()
+        tools.register_local_tool(db_tool, access_groups=['admin', 'user'])
+        tools.register_local_tool(save_memory_tool, access_groups=['admin'])
+        tools.register_local_tool(search_memory_tool, access_groups=['admin', 'user'])
+
+        self.agent = Agent(
+            llm_service=llm,
+            tool_registry=tools,
+            user_resolver=self.user_resolver,
+            system_prompt_builder=CustomSQLSystemPromptBuilder("CoJournalist", self.sql_runner),
+            config=AgentConfig(stream_responses=False, max_tool_iterations=1)
+        )
+
+    async def ask(self, prompt_for_llm: str):
+        ctx = RequestContext()
+        print(f"🙋 Prompt sent to LLM: {prompt_for_llm}")
+
+        final_text = ""
+        seen_texts = set()
+
+        async for component in self.agent.send_message(request_context=ctx, message=prompt_for_llm):
+            simple = getattr(component, "simple_component", None)
+            text = getattr(simple, "text", "") if simple else ""
+            if text and text not in seen_texts:
+                print(f"💬 LLM says (part): {text[:200]}...")
+                final_text += text + "\n"
+                seen_texts.add(text)
+
+            sql_query = getattr(component, "sql", None)
+            if sql_query:
+                print(f"🧾 SQL Query Generated: {sql_query}")
+
+            metadata = getattr(component, "metadata", None)
+            if metadata:
+                print(f"📋 Metadata: {metadata}")
+
+            component_type = getattr(component, "type", None)
+            if component_type:
+                print(f"🔖 Component Type: {component_type}")
+
+            match = re.search(r"query_results_[\w-]+\.csv", final_text)
+            if match:
+                filename = match.group(0)
+                folder = "513935c4d2db2d2d"
+                full_path = os.path.join(folder, filename)
+
+                if os.path.exists(full_path):
+                    print(f"📂 Reading result file: {full_path}")
+                    with open(full_path, "r", encoding="utf-8") as f:
+                        csv_data = f.read().strip()
+                    print("🤖 Response sent to user (from file):", csv_data[:300])
+                    return csv_data
+                else:
+                    print(f"⚠️ File not found: {full_path}")
+
+        return final_text

src/vanna_huggingface_llm_service.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncGenerator, Dict, List, Optional
+
+from vanna.core.llm import (
+    LlmService,
+    LlmRequest,
+    LlmResponse,
+    LlmStreamChunk,
+)
+from vanna.core.tool import ToolCall, ToolSchema
+from huggingface_hub import InferenceClient
+
+
+class VannaHuggingFaceLlmService(LlmService):
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        api_key: Optional[str] = None,
+        provider: Optional[str] = None,
+        **extra_client_kwargs: Any,
+    ) -> None:
+      
+        """Initialise le client Hugging Face InferenceClient."""
+        client_kwargs = extra_client_kwargs.copy()
+        if model:
+            client_kwargs["model"] = model
+        if api_key:
+            client_kwargs["api_key"] = api_key
+        if provider:
+            client_kwargs["provider"] = provider
+        
+        self.model = model
+        
+        self._client = InferenceClient(**client_kwargs)
+
+ 
+    async def send_request(self, request: LlmRequest) -> LlmResponse:
+        """Send a non-streaming request to OpenAI and return the response."""
+        payload = self._build_payload(request)
+
+        # Call the API synchronously; this function is async but we can block here.
+        resp = self._client.chat.completions.create(**payload, stream=False)
+
+        if not resp.choices:
+            return LlmResponse(content=None, tool_calls=None, finish_reason=None)
+
+        choice = resp.choices[0]
+        content: Optional[str] = getattr(choice.message, "content", None)
+        tool_calls = self._extract_tool_calls_from_message(choice.message)
+
+        usage: Dict[str, int] = {}
+        if getattr(resp, "usage", None):
+            usage = {
+                k: int(v)
+                for k, v in {
+                    "prompt_tokens": getattr(resp.usage, "prompt_tokens", 0),
+                    "completion_tokens": getattr(resp.usage, "completion_tokens", 0),
+                    "total_tokens": getattr(resp.usage, "total_tokens", 0),
+                }.items()
+            }
+
+        return LlmResponse(
+            content=content,
+            tool_calls=tool_calls or None,
+            finish_reason=getattr(choice, "finish_reason", None),
+            usage=usage or None,
+        )
+
+    async def stream_request(
+        self, request: LlmRequest
+    ) -> AsyncGenerator[LlmStreamChunk, None]:
+        """Stream a request to OpenAI.
+
+        Emits `LlmStreamChunk` for textual deltas as they arrive. Tool-calls are
+        accumulated and emitted in a final chunk when the stream ends.
+        """
+        payload = self._build_payload(request)
+
+        # Synchronous streaming iterator; iterate within async context.
+        stream = self._client.chat.completions.create(**payload, stream=True)
+
+        # Builders for streamed tool-calls (index -> partial)
+        tc_builders: Dict[int, Dict[str, Optional[str]]] = {}
+        last_finish: Optional[str] = None
+
+        for event in stream:
+            if not getattr(event, "choices", None):
+                continue
+
+            choice = event.choices[0]
+            delta = getattr(choice, "delta", None)
+            if delta is None:
+                # Some SDK versions use `event.choices[0].message` on the final packet
+                last_finish = getattr(choice, "finish_reason", last_finish)
+                continue
+
+            # Text content
+            content_piece: Optional[str] = getattr(delta, "content", None)
+            if content_piece:
+                yield LlmStreamChunk(content=content_piece)
+
+            # Tool calls (streamed)
+            streamed_tool_calls = getattr(delta, "tool_calls", None)
+            if streamed_tool_calls:
+                for tc in streamed_tool_calls:
+                    idx = getattr(tc, "index", 0) or 0
+                    b = tc_builders.setdefault(
+                        idx, {"id": None, "name": None, "arguments": ""}
+                    )
+                    if getattr(tc, "id", None):
+                        b["id"] = tc.id
+                    fn = getattr(tc, "function", None)
+                    if fn is not None:
+                        if getattr(fn, "name", None):
+                            b["name"] = fn.name
+                        if getattr(fn, "arguments", None):
+                            b["arguments"] = (b["arguments"] or "") + fn.arguments
+
+            last_finish = getattr(choice, "finish_reason", last_finish)
+
+        # Emit final tool-calls chunk if any
+        final_tool_calls: List[ToolCall] = []
+        for b in tc_builders.values():
+            if not b.get("name"):
+                continue
+            args_raw = b.get("arguments") or "{}"
+            try:
+                loaded = json.loads(args_raw)
+                if isinstance(loaded, dict):
+                    args_dict: Dict[str, Any] = loaded
+                else:
+                    args_dict = {"args": loaded}
+            except Exception:
+                args_dict = {"_raw": args_raw}
+            final_tool_calls.append(
+                ToolCall(
+                    id=b.get("id") or "tool_call",
+                    name=b["name"] or "tool",
+                    arguments=args_dict,
+                )
+            )
+
+        if final_tool_calls:
+            yield LlmStreamChunk(tool_calls=final_tool_calls, finish_reason=last_finish)
+        else:
+            # Still emit a terminal chunk to signal completion
+            yield LlmStreamChunk(finish_reason=last_finish or "stop")
+
+    async def validate_tools(self, tools: List[ToolSchema]) -> List[str]:
+        """Validate tool schemas. Returns a list of error messages."""
+        errors: List[str] = []
+        # Basic checks; OpenAI will enforce further validation server-side.
+        for t in tools:
+            if not t.name or len(t.name) > 64:
+                errors.append(f"Invalid tool name: {t.name!r}")
+        return errors
+
+    # Internal helpers
+    def _build_payload(self, request: LlmRequest) -> Dict[str, Any]:
+        messages: List[Dict[str, Any]] = []
+
+        # Add system prompt as first message if provided
+        if request.system_prompt:
+            messages.append({"role": "system", "content": request.system_prompt})
+
+        for m in request.messages:
+            msg: Dict[str, Any] = {"role": m.role, "content": m.content}
+            if m.role == "tool" and m.tool_call_id:
+                msg["tool_call_id"] = m.tool_call_id
+            elif m.role == "assistant" and m.tool_calls:
+                # Convert tool calls to OpenAI format
+                tool_calls_payload = []
+                for tc in m.tool_calls:
+                    tool_calls_payload.append({
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {
+                            "name": tc.name,
+                            "arguments": json.dumps(tc.arguments)
+                        }
+                    })
+                msg["tool_calls"] = tool_calls_payload
+            messages.append(msg)
+
+        tools_payload: Optional[List[Dict[str, Any]]] = None
+        if request.tools:
+            tools_payload = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": t.name,
+                        "description": t.description,
+                        "parameters": t.parameters,
+                    },
+                }
+                for t in request.tools
+            ]
+
+        payload: Dict[str, Any] = {
+            "model": self.model,
+            "messages": messages,
+        }
+        if request.max_tokens is not None:
+            payload["max_tokens"] = request.max_tokens
+        if tools_payload:
+            payload["tools"] = tools_payload
+            payload["tool_choice"] = "auto"
+
+        return payload
+
+    def _extract_tool_calls_from_message(self, message: Any) -> List[ToolCall]:
+        tool_calls: List[ToolCall] = []
+        raw_tool_calls = getattr(message, "tool_calls", None) or []
+        for tc in raw_tool_calls:
+            fn = getattr(tc, "function", None)
+            if not fn:
+                continue
+            args_raw = getattr(fn, "arguments", "{}")
+            try:
+                loaded = json.loads(args_raw)
+                if isinstance(loaded, dict):
+                    args_dict: Dict[str, Any] = loaded
+                else:
+                    args_dict = {"args": loaded}
+            except Exception:
+                args_dict = {"_raw": args_raw}
+            tool_calls.append(
+                ToolCall(
+                    id=getattr(tc, "id", "tool_call"),
+                    name=getattr(fn, "name", "tool"),
+                    arguments=args_dict,
+                )
+            )
+        return tool_calls