Update with good function calling

configs/prompt_library.yaml

@@ -69,39 +69,104 @@ fed_orchestrator: |
   You are a Federal Reserve Tool Orchestrator. Your job is to analyze user queries about Fed policy and FOMC meetings, then decide which tools to use to gather the most relevant information.
 
   AVAILABLE TOOLS:
-  1. search_meetings(query: str, limit: int = 3) - Search across all FOMC meeting fields for relevant information
-  2. get_latest_meeting() - Get the most recent FOMC meeting data
-  3. get_rate_decision(date: str) - Get specific meeting data by date (YYYY-MM-DD format)
-  4. compare_meetings(date1: str, date2: str) - Compare two meetings side by side
-
-  INSTRUCTIONS:
-  - Analyze the user query to determine which tools would provide the most relevant information
-  - You can use multiple tools if needed to fully answer the question
-  - For search queries, extract key terms and use search_meetings
-  - For recent/latest questions, use get_latest_meeting
-  - For specific date questions, use get_rate_decision
-  - For comparison questions, use compare_meetings
-  - Always provide the exact function calls in JSON format
+
+  1. search_meetings(query: str, limit: int = 3)
+     - Purpose: Search across all FOMC meeting fields for relevant information
+     - Parameters:
+       * query (required): Search term or phrase - searches across date, title, action, rate, magnitude, forward_guidance, economic_outlook, market_impact, key_economic_factors
+       * limit (optional): Maximum meetings to return (default: 3, recommend 3-5 for most queries)
+     - Best for: Thematic searches, finding patterns across meetings, keyword-based queries
+     - Returns: Ranked results with match scores and details about which fields matched
+     - Examples: "inflation expectations", "employment concerns", "rate cuts", "economic uncertainty"
+
+  2. get_latest_meeting()
+     - Purpose: Get the most recent FOMC meeting data
+     - Parameters: None
+     - Best for: "What's the latest?", "most recent decision", "current rate"
+     - Returns: Complete data for the newest meeting plus total meeting count
+     - Use when: User asks about current/recent/latest Fed actions without specifying dates
+
+  3. get_rate_decision(date: str)
+     - Purpose: Get specific meeting data by exact or approximate date
+     - Parameters:
+       * date (required): Meeting date in YYYY-MM-DD format (e.g., "2024-12-18")
+     - Best for: Date-specific queries, historical lookups
+     - Returns: Meeting data with exact_match flag; finds closest meeting within 30 days if no exact match
+     - Use when: User mentions specific dates, months, or "the meeting in [time period]"
+
+  4. compare_meetings(date1: str, date2: str)
+     - Purpose: Compare two meetings side by side with detailed analysis
+     - Parameters:
+       * date1 (required): First meeting date in YYYY-MM-DD format
+       * date2 (required): Second meeting date in YYYY-MM-DD format
+     - Best for: "How did X change between meetings?", trend analysis, policy evolution
+     - Returns: Differences, similarities, and factor analysis between meetings
+     - Use when: User explicitly asks for comparisons or asks about changes over time
+
+  TOOL SELECTION STRATEGY:
+  - Single recent query → get_latest_meeting()
+  - Specific date mention → get_rate_decision(date)
+  - Two dates or "compared to" → compare_meetings(date1, date2)
+  - Thematic/keyword search → search_meetings(query, limit)
+  - Complex queries may require multiple tools in sequence
+
+  DATE HANDLING:
+  - Convert relative dates to YYYY-MM-DD format (e.g., "December 2024" → "2024-12-18")
+  - For approximate dates, use typical FOMC meeting dates (usually 3rd Wednesday of month)
+  - Recent meeting schedule: typically 8 meetings per year
 
   RESPONSE FORMAT:
   Return a JSON object with this structure:
-  {{
+  {
     "tools_needed": [
-      {{
+      {
         "function": "function_name",
-        "parameters": {{"param1": "value1", "param2": "value2"}},
-        "reasoning": "Why this tool is needed"
-      }}
+        "parameters": {"param1": "value1", "param2": "value2"},
+        "reasoning": "Specific explanation of why this tool and these parameters are optimal",
+        "execution_order": 1
+      }
     ],
-    "query_analysis": "Brief analysis of what the user is asking for"
-  }}
+    "query_analysis": "Detailed analysis of user intent and information needs",
+    "date_interpretations": "Any date conversions or assumptions made"
+  }
 
   EXAMPLES:
-  User: "What was the latest rate decision?"
-  Response: {{"tools_needed": [{{"function": "get_latest_meeting", "parameters": {{}}, "reasoning": "User wants the most recent FOMC meeting information"}}], "query_analysis": "User is asking for the most recent Fed rate decision"}}
 
-  User: "Tell me about inflation expectations in recent meetings"
-  Response: {{"tools_needed": [{{"function": "search_meetings", "parameters": {{"query": "inflation expectations", "limit": 3}}, "reasoning": "Need to search for inflation-related content across meetings"}}], "query_analysis": "User wants information about inflation expectations from FOMC meetings"}}
+  User: "What was the latest rate decision?"
+  Response: {
+    "tools_needed": [{
+      "function": "get_latest_meeting",
+      "parameters": {},
+      "reasoning": "User wants most recent Fed decision; get_latest_meeting provides complete current data",
+      "execution_order": 1
+    }],
+    "query_analysis": "User seeking current Fed policy status - needs most recent meeting data",
+    "date_interpretations": "No dates specified - using latest available"
+  }
+
+  User: "How did inflation concerns change from June to December 2024?"
+  Response: {
+    "tools_needed": [{
+      "function": "compare_meetings",
+      "parameters": {"date1": "2024-06-12", "date2": "2024-12-18"},
+      "reasoning": "User wants evolution analysis between specific periods; compare_meetings provides detailed difference analysis including factor changes",
+      "execution_order": 1
+    }],
+    "query_analysis": "User seeking trend analysis of inflation concerns over 6-month period",
+    "date_interpretations": "June 2024 → 2024-06-12 (typical June FOMC date), December 2024 → 2024-12-18 (typical December FOMC date)"
+  }
+
+  User: "Tell me about employment data in recent Fed meetings"
+  Response: {
+    "tools_needed": [{
+      "function": "search_meetings",
+      "parameters": {"query": "employment", "limit": 4},
+      "reasoning": "Thematic search across multiple meetings for employment-related content; higher limit captures recent trend",
+      "execution_order": 1
+    }],
+    "query_analysis": "User wants employment-focused analysis across recent meetings - needs keyword search with sufficient results for pattern identification",
+    "date_interpretations": "No specific dates - search will return most relevant recent matches"
+  }
 
   User Query: {user_query}
   The date is {date}

src/modules/llm_completions.py

@@ -184,6 +184,114 @@ def execute_fed_tools(tools_decision: Dict[str, Any], fed_tools: Dict[str, calla
     
     return results
 
+def extract_citations_from_tool_results(tool_results: List[Dict[str, Any]]) -> List[Dict[str, str]]:
+    """Extract unique citations from tool results"""
+    citations = []
+    
+    for result in tool_results:
+        if result["success"] and result["result"].get("success"):
+            # Check if result has meeting data with URLs
+            if "meeting" in result["result"]:
+                meeting = result["result"]["meeting"]
+                if meeting.get("url"):
+                    citations.append({
+                        "date": meeting.get("date", "Unknown date"),
+                        "url": meeting["url"],
+                        "title": meeting.get("title", f"FOMC Meeting {meeting.get('date', '')}")
+                    })
+            elif "results" in result["result"]:
+                # Handle search results
+                for meeting in result["result"]["results"]:
+                    if meeting.get("url"):
+                        citations.append({
+                            "date": meeting.get("date", "Unknown date"),
+                            "url": meeting["url"],
+                            "title": meeting.get("title", f"FOMC Meeting {meeting.get('date', '')}")
+                        })
+    
+    # Remove duplicate citations
+    unique_citations = []
+    seen_urls = set()
+    for citation in citations:
+        if citation["url"] not in seen_urls:
+            unique_citations.append(citation)
+            seen_urls.add(citation["url"])
+    
+    return unique_citations
+
+def format_response_with_citations(response: str, citations: List[Dict[str, str]]) -> str:
+    """Format response with citations appended"""
+    if citations:
+        response += "\n\n**📚 Sources:**\n"
+        for citation in citations:
+            response += f"• [{citation['title']}]({citation['url']})\n"
+    return response
+
+def create_planning_message(tools_decision: Dict[str, Any]) -> ChatMessage:
+    """Create the planning/analysis message"""
+    return ChatMessage(
+        role="assistant",
+        content=f"Query Analysis: {tools_decision.get('query_analysis', 'Analyzing Fed data requirements')}\n\nTools needed: {len(tools_decision.get('tools_needed', []))}",
+        metadata={"title": "🧠 Planning", "status": "done"}
+    )
+
+def create_tool_messages(tools_decision: Dict[str, Any]) -> List[ChatMessage]:
+    """Create initial tool execution messages"""
+    tool_messages = []
+    
+    for i, tool in enumerate(tools_decision["tools_needed"]):
+        tool_msg = ChatMessage(
+            role="assistant",
+            content=f"Executing: {tool['function']}({', '.join([f'{k}={v}' for k, v in tool['parameters'].items()])})\n\nReasoning: {tool['reasoning']}",
+            metadata={"title": f"🔧 Tool {i+1}: {tool['function']}", "status": "pending"}
+        )
+        tool_messages.append(tool_msg)
+    
+    return tool_messages
+
+def update_tool_messages_with_results(tool_results: List[Dict[str, Any]]) -> List[ChatMessage]:
+    """Update tool messages with execution results"""
+    updated_messages = []
+    
+    for i, tool_result in enumerate(tool_results):
+        execution_time = tool_result["execution_time"]
+        success_status = "✅" if tool_result["success"] else "❌"
+        
+        updated_msg = ChatMessage(
+            role="assistant",
+            content=f"{success_status} {tool_result['function']} completed\n\nExecution time: {execution_time:.2f}s\n\nResult summary: {str(tool_result['result'])[:200]}...",
+            metadata={"title": f"🔧 Tool {i+1}: {tool_result['function']}", "status": "done", "duration": execution_time}
+        )
+        updated_messages.append(updated_msg)
+    
+    return updated_messages
+
+def build_context_from_tool_results(tool_results: List[Dict[str, Any]]) -> str:
+    """Build combined context from successful tool results"""
+    combined_context = ""
+    for result in tool_results:
+        if result["success"]:
+            combined_context += f"\n\nFrom {result['function']}: {json.dumps(result['result'], indent=2)}"
+    return combined_context
+
+def stream_final_response(message: str, system_prompt: str, api_key: str, citations: List[Dict[str, str]]):
+    """Stream the final Fed Savant response with citations"""
+    llm = get_llm("large", api_key)
+    
+    final_response = ""
+    for chunk in llm.chat.completions.create(
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": message}
+        ],
+        temperature=0.2,
+        stream=True,
+        max_tokens=1000
+    ):
+        if chunk.choices[0].delta.content:
+            final_response += chunk.choices[0].delta.content
+            yield format_response_with_citations(final_response, citations)
+
 def stream_fed_agent_response(
     message: str, 
     api_key: str, 
@@ -192,6 +300,7 @@ def stream_fed_agent_response(
 ):
     """Main orchestrator function that coordinates tools and generates responses with ChatMessage objects"""
     
+    # Input validation
     if not message.strip():
         yield [ChatMessage(role="assistant", content="Please enter a question about Federal Reserve policy or FOMC meetings.")]
         return
@@ -203,7 +312,6 @@ def stream_fed_agent_response(
     messages = []
     
     try:
-        # Step 1: Use orchestrator to determine tools needed
         messages.append(ChatMessage(
             role="assistant", 
             content="Analyzing your query...",
@@ -214,78 +322,38 @@ def stream_fed_agent_response(
         orchestrator_result = get_orchestrator_decision(message, api_key, prompt_library)
         tools_decision = orchestrator_result["decision"]
         
-        # Update planning message
-        messages[0] = ChatMessage(
-            role="assistant",
-            content=f"Query Analysis: {tools_decision.get('query_analysis', 'Analyzing Fed data requirements')}\n\nTools needed: {len(tools_decision.get('tools_needed', []))}",
-            metadata={"title": "🧠 Planning", "status": "done"}
-        )
+        messages[0] = create_planning_message(tools_decision)
         yield messages
         
-        # Step 2: Execute the determined tools
         if tools_decision.get("tools_needed"):
-            for i, tool in enumerate(tools_decision["tools_needed"]):
-                tool_msg = ChatMessage(
-                    role="assistant",
-                    content=f"Executing: {tool['function']}({', '.join([f'{k}={v}' for k, v in tool['parameters'].items()])})\n\nReasoning: {tool['reasoning']}",
-                    metadata={"title": f"🔧 Tool {i+1}: {tool['function']}", "status": "pending"}
-                )
-                messages.append(tool_msg)
-                yield messages
+            tool_messages = create_tool_messages(tools_decision)
+            messages.extend(tool_messages)
+            yield messages
             
-            # Execute all tools
             tool_results = execute_fed_tools(tools_decision, fed_tools)
             
-            # Update tool messages with results
-            for i, (tool_result, tool_msg) in enumerate(zip(tool_results, messages[1:])):
-                execution_time = tool_result["execution_time"]
-                success_status = "✅" if tool_result["success"] else "❌"
-                
-                messages[i+1] = ChatMessage(
-                    role="assistant",
-                    content=f"{success_status} {tool_result['function']} completed\n\nExecution time: {execution_time:.2f}s\n\nResult summary: {str(tool_result['result'])[:200]}...",
-                    metadata={"title": f"🔧 Tool {i+1}: {tool_result['function']}", "status": "done", "duration": execution_time}
-                )
-            
+            updated_tool_messages = update_tool_messages_with_results(tool_results)
+            messages[1:] = updated_tool_messages  # Replace tool messages but keep planning
             yield messages
             
-            # Step 3: Use results to generate final response
-            combined_context = ""
-            for result in tool_results:
-                if result["success"]:
-                    combined_context += f"\n\nFrom {result['function']}: {json.dumps(result['result'], indent=2)}"
+            combined_context = build_context_from_tool_results(tool_results)
+            citations = extract_citations_from_tool_results(tool_results)
             
-            # Generate Fed Savant response using tool results
             system_prompt_template = prompt_library.get('fed_savant_chat', '')
             system_prompt = system_prompt_template.format(
                 fed_data_context=combined_context,
                 user_question=message,
                 date=TODAY
             )
+
+            expected_messages_count = 1 + len(tool_results)
             
-            # Initialize LLM and get streaming response
-            llm = get_llm("large", api_key)
-            
-            final_response = ""
-            for chunk in llm.chat.completions.create(
-                messages=[
-                    {"role": "system", "content": system_prompt},
-                    {"role": "user", "content": message}
-                ],
-                temperature=0.2,
-                stream=True,
-                max_tokens=1000
-            ):
-                if chunk.choices[0].delta.content:
-                    final_response += chunk.choices[0].delta.content
-                    
-                    # Update messages list with current response
-                    if len(messages) > len(tool_results):
-                        messages[-1] = ChatMessage(role="assistant", content=final_response)
-                    else:
-                        messages.append(ChatMessage(role="assistant", content=final_response))
-                    
-                    yield messages
+            for response_chunk in stream_final_response(message, system_prompt, api_key, citations):
+                if len(messages) < expected_messages_count + 1:
+                    messages.append(ChatMessage(role="assistant", content=response_chunk))
+                else:
+                    messages[-1] = ChatMessage(role="assistant", content=response_chunk)
+                yield messages
         
         else:
             # No tools needed, direct response