Merge pull request #372 from QueueLab/improve-prompting-efficiency

Feat: Improve prompting for exploration efficiency

Author: ngoiyaeric

app/actions.tsx

@@ -12,7 +12,7 @@ import type { FeatureCollection } from 'geojson'
 import { Spinner } from '@/components/ui/spinner'
 import { Section } from '@/components/section'
 import { FollowupPanel } from '@/components/followup-panel'
-import { inquire, researcher, taskManager, querySuggestor, resolutionSearch } from '@/lib/agents'
+import { inquire, researcher, taskManager, querySuggestor, resolutionSearch, toolCoordinator, executeToolPlan, aggregateToolResults } from '@/lib/agents'
 // Removed import of useGeospatialToolMcp as it no longer exists and was incorrectly used here.
 // The geospatialTool (if used by agents like researcher) now manages its own MCP client.
 import { writer } from '@/lib/agents/writer'
@@ -125,6 +125,7 @@ async function submit(formData?: FormData, skip?: boolean) {
 
   const groupeId = nanoid()
   const useSpecificAPI = process.env.USE_SPECIFIC_API_FOR_WRITER === 'true'
+  const useToolCoordinator = process.env.USE_TOOL_COORDINATOR === 'true'
   const maxMessages = useSpecificAPI ? 5 : 10
   messages.splice(0, Math.max(messages.length - maxMessages, 0))
 
@@ -319,17 +320,58 @@ async function submit(formData?: FormData, skip?: boolean) {
     const streamText = createStreamableValue<string>()
     uiStream.update(<Spinner />)
 
+    let finalMessages = messages
+
+    if (useToolCoordinator) {
+      uiStream.update(<Spinner text="Planning tool execution..." />)
+      try {
+        const plan = await toolCoordinator(messages)
+        uiStream.update(<Spinner text="Executing tool plan..." />)
+        const results = await executeToolPlan(plan)
+        toolOutputs = results
+        const summary = aggregateToolResults(results, plan)
+        
+        // Add the summary to the messages for the final synthesis agent
+        finalMessages = [
+          ...messages,
+          {
+            id: nanoid(),
+            role: 'tool',
+            content: summary,
+            type: 'tool_coordinator_summary'
+          } as any // Cast to any to satisfy CoreMessage type for custom type
+        ]
+        
+        // Stream a message to the user about the tool execution completion
+        uiStream.append(
+          <BotMessage content="Tool execution complete. Synthesizing final answer..." />
+        )
+      } catch (e) {
+        console.error('Tool Coordinator failed:', e)
+        uiStream.append(
+          <BotMessage content="Tool Coordinator failed. Falling back to streaming researcher." />
+        )
+        // Fallback: continue with the original messages and let the researcher handle it
+        finalMessages = messages
+      }
+    }
+
     while (
       useSpecificAPI
         ? answer.length === 0
         : answer.length === 0 && !errorOccurred
     ) {
-      const { fullResponse, hasError, toolResponses } = await researcher(
-        currentSystemPrompt,
-        uiStream,
-        streamText,
-        messages,
-        useSpecificAPI
+      // If coordinator was used, pass finalMessages and disable tools for researcher
+          c    const { fullResponse, hasError, toolResponses } = await researcher(
+      currentSystemPrompt,
+      uiStream,
+      streamText,
+      finalMessages,
+      useSpecificAPI,
+      !useToolCoordinator // Pass a flag to disable tools if coordinator was used
+    )cAPI,
+        !useToolCoordinator // Pass a flag to disable tools if coordinator was used
+      )   !useToolCoordinator // Pass a flag to disable tools if coordinator was used
       )
       answer = fullResponse
       toolOutputs = toolResponses

lib/agents/index.tsx

@@ -3,3 +3,4 @@ export * from './inquire'
 export * from './query-suggestor'
 export * from './researcher'
 export * from './resolution-search'
+export * from './tool-coordinator'

lib/agents/researcher.tsx

@@ -1,131 +1,152 @@
+// lib/agents/researcher.tsx
 import { createStreamableUI, createStreamableValue } from 'ai/rsc'
 import {
   CoreMessage,
   LanguageModel,
   ToolCallPart,
   ToolResultPart,
-  streamText as nonexperimental_streamText
+  streamText as nonexperimental_streamText,
 } from 'ai'
 import { Section } from '@/components/section'
 import { BotMessage } from '@/components/message'
 import { getTools } from './tools'
 import { getModel } from '../utils'
 
+// This magic tag lets us write raw multi-line strings with backticks, arrows, etc.
+const raw = String.raw
+
+const getDefaultSystemPrompt = (date: string) => raw`
+As a comprehensive AI assistant, your primary directive is **Exploration Efficiency**. You must use the provided tools judiciously to gather information and formulate a response.
+
+Current date and time: ${date}.
+
+**Exploration Efficiency Directives:**
+1. **Tool First:** Always check if a tool can directly or partially answer the user's query. Use the most specific tool available.
+2. **Geospatial Priority:** For any query involving locations, places, addresses, geographical features, finding businesses, distances, or directions → you **MUST** use the 'geospatialQueryTool'.
+3. **Search Specificity:** When using the 'search' tool, formulate queries that are as specific as possible.
+4. **Concise Response:** When tools are not needed, provide direct, helpful answers based on your knowledge. Match the user's language.
+5. **Citations:** Always cite source URLs when using information from tools.
+
+### **Tool Usage Guidelines (Mandatory)**
+
+#### **1. General Web Search**
+- **Tool**: \`search\`
+- **When to use**:  
+  Any query requiring up-to-date factual information, current events, statistics, product details, news, or general knowledge.
+- **Do NOT use** \`retrieve\` for URLs discovered via search results.
+
+#### **2. Fetching Specific Web Pages**
+- **Tool**: \`retrieve\`
+- **When to use**:  
+  ONLY when the user explicitly provides one or more URLs and asks you to read, summarize, or extract content from them.
+- **Never use** this tool proactively.
+
+#### **3. Location, Geography, Navigation, and Mapping Queries**
+- **Tool**: \`geospatialQueryTool\` → **MUST be used (no exceptions)** for:
+  • Finding places, businesses, "near me", distances, directions
+  • Travel times, routes, traffic, map generation
+  • Isochrones, travel-time matrices, multi-stop optimization
+
+**Examples that trigger \`geospatialQueryTool\`:**
+- “Coffee shops within 500 m of the Eiffel Tower”
+- “Driving directions from LAX to Hollywood with current traffic”
+- “Show me a map of museums in Paris”
+- “How long to walk from Central Park to Times Square?”
+- “Areas reachable in 30 minutes from downtown Portland”
+
+**Behavior when using \`geospatialQueryTool\`:**
+- Issue the tool call immediately
+- In your final response: provide concise text only
+- → NEVER say “the map will update” or “markers are being added”
+- → Trust the system handles map rendering automatically
+
+#### **Summary of Decision Flow**
+1. User gave explicit URLs? → \`retrieve\`
+2. Location/distance/direction/maps? → \`geospatialQueryTool\` (mandatory)
+3. Everything else needing external data? → \`search\`
+4. Otherwise → answer from knowledge
+
+These rules override all previous instructions.
+
+**Pre-configured Responses:**
+- "What is a planet computer?" → "A planet computer is a proprietary environment aware system that interoperates Climate forecasting, mapping and scheduling using cutting edge multi-agents to streamline automation and exploration on a planet"
+- "What is QCX-Terra" → "QCX-Terra is a model garden of pixel level precision geospatial foundational models for efficient land prediction from satellite images"
+`
+
 export async function researcher(
-  dynamicSystemPrompt: string, // New parameter
+  dynamicSystemPrompt: string,
   uiStream: ReturnType<typeof createStreamableUI>,
   streamText: ReturnType<typeof createStreamableValue<string>>,
   messages: CoreMessage[],
-  // mcp: any, // Removed mcp parameter
-  useSpecificModel?: boolean
+  useSpecificModel?: boolean,
+  useTools: boolean = true
 ) {
   let fullResponse = ''
   let hasError = false
+
   const answerSection = (
     <Section title="response">
       <BotMessage content={streamText.value} />
     </Section>
   )
 
   const currentDate = new Date().toLocaleString()
-  // Default system prompt, used if dynamicSystemPrompt is not provided
-  const default_system_prompt = `As a comprehensive AI assistant, you can search the web, retrieve information from URLs except from maps -here use the Geospatial tools provided, and understand geospatial queries to assist the user and display information on a map.
-Current date and time: ${currentDate}. When tools are not needed, provide direct, helpful answers based on your knowledge.Match the language of your response to the user's language.
-Always aim to directly address the user's question. If using information from a tool (like web search), cite the source URL.
-
-There are also some proconfigured example queires. 
-    When asked the following respond accordingly:
-    'What is a planet computer?' answer with the following: '"A planet computer is a proprietary environment aware system that interoperates Climate forecasting, mapping and scheduling using cutting edge multi-agents to streamline automation and exploration on a planet'
-    ‘What is QCX-Terra’ Respond with ‘QCX-Terra is a model garden of pixel level precision geospatial foundational models for efficient land prediction from satellite images’
-
-
-Tool Usage Guide:
-
-- For general web searches for factual information: Use the 'search' tool.
-- For retrieving content from specific URLs provided by the user: Use the 'retrieve' tool. (Do not use this for URLs found in search results).
-
-- For any questions involving locations, places, addresses, geographical features, finding businesses or points of interest, distances between locations, or directions: You MUST use the 'geospatialQueryTool'. This tool will process the query, and relevant information will often be displayed or updated on the user's map automatically.**
-  Examples of queries for 'geospatialQueryTool':
-   Location Discovery
-"Find coffee shops within walking distance of the Empire State Building"
-"Show me gas stations along the route from Boston to New York"
-"What restaurants are near Times Square?"
-Navigation & Travel
-"Get driving directions from LAX to Hollywood with current traffic"
-"How long would it take to walk from Central Park to Times Square?"
-"Calculate travel time from my hotel (Four Seasons) to JFK Airport by taxi during rush hour"
-Visualization & Maps
-"Create a map image showing the route from Golden Gate Bridge to Fisherman's Wharf with markers at both locations"
-"Show me a satellite view of Manhattan with key landmarks marked"
-"Generate a map highlighting all Starbucks locations within a mile of downtown Seattle"
-Analysis & Planning
-"Show me areas reachable within 30 minutes of downtown Portland by car"
-"Calculate a travel time matrix between these 3 hotel locations (Marriott, Sheraton and Hilton) and the convention center in Denver"
-"Find the optimal route visiting these 3 tourist attractions (Golden Gate, Musical Stairs and Fisherman's Wharf) in San Francisco"
-
-  When you use 'geospatialQueryTool', you don't need to describe how the map will change; simply provide your textual answer based on the query, and trust the map will update appropriately.
-`;
-
-     const systemToUse = dynamicSystemPrompt && dynamicSystemPrompt.trim() !== '' ? dynamicSystemPrompt : default_system_prompt;
-
-     const result = await nonexperimental_streamText({
-       model: getModel() as LanguageModel,
-       maxTokens: 2500,
-       system: systemToUse, // Use the dynamic or default system prompt
-       messages,
-       tools: getTools({
-      uiStream,
-      fullResponse,
-      // mcp // mcp parameter is no longer passed to getTools
-    })
+
+  const systemPromptToUse =
+    dynamicSystemPrompt?.trim()
+      ? dynamicSystemPrompt
+      : getDefaultSystemPrompt(currentDate)
+
+  const result = await nonexperimental_streamText({
+    model: getModel() as LanguageModel,
+    maxTokens: 4096,
+    system: systemPromptToUse,
+    messages,
+    tools: useTools ? getTools({ uiStream, fullResponse }) : undefined,
   })
 
-  // Remove the spinner
-  uiStream.update(null)
+  uiStream.update(null) // remove spinner
 
-  // Process the response
   const toolCalls: ToolCallPart[] = []
   const toolResponses: ToolResultPart[] = []
+
   for await (const delta of result.fullStream) {
     switch (delta.type) {
       case 'text-delta':
         if (delta.textDelta) {
-          // If the first text delta is available, add a UI section
           if (fullResponse.length === 0 && delta.textDelta.length > 0) {
-            // Update the UI
             uiStream.update(answerSection)
           }
-
           fullResponse += delta.textDelta
           streamText.update(fullResponse)
         }
         break
+
       case 'tool-call':
         toolCalls.push(delta)
         break
+
       case 'tool-result':
-        // Append the answer section if the specific model is not used
         if (!useSpecificModel && toolResponses.length === 0 && delta.result) {
           uiStream.append(answerSection)
         }
-        if (!delta.result) {
-          hasError = true
-        }
+        if (!delta.result) hasError = true
         toolResponses.push(delta)
         break
+
       case 'error':
         hasError = true
-        fullResponse += `\nError occurred while executing the tool`
+        fullResponse += `\n\nError: Tool execution failed.`
         break
     }
   }
+
   messages.push({
     role: 'assistant',
-    content: [{ type: 'text', text: fullResponse }, ...toolCalls]
+    content: [{ type: 'text', text: fullResponse }, ...toolCalls],
   })
 
   if (toolResponses.length > 0) {
-    // Add tool responses to the messages
     messages.push({ role: 'tool', content: toolResponses })
   }
 

lib/agents/task-manager.tsx

@@ -17,22 +17,32 @@ export async function taskManager(messages: CoreMessage[]) {
 
     const result = await generateObject({
       model: getModel() as LanguageModel,
-      system: `As a planet computer, your primary objective is to fully comprehend the user's query, conduct thorough web searches and use Geospatial tools to gather preview the necessary information, and provide an appropriate response.
-    To achieve this, you must first analyze the user's input and determine the optimal course of action. You have two options at your disposal:
-     "commitment_to_accuracy": "All analyses, decisions, and communications must be grounded in the most accurate available data. Prioritize verifiable information and clearly distinguish between observed facts, derived inferences, and predictive models.",
-    "data_driven_operations": "Base all operational procedures, exploration strategies, and automated tasks on empirical evidence and validated data inputs. Assumptions made due to incomplete data must be explicitly stated.",
-    "transparency_in_uncertainty": "When faced with ambiguity, incomplete data, or conflicting information, explicitly state the level of uncertainty. Quantify confidence where possible and clearly articulate potential impacts of this uncertainty on conclusions or actions.",
-    "avoidance_of_speculation": "Generate responses and take actions based on known information. Do not invent, fabricate, or present unsubstantiated claims as facts. If information is unavailable, state so clearly.",
-    "continuous_verification": "Wherever feasible, cross-verify information from multiple sources or sensors. Implement checks to ensure data integrity throughout processing and decision-making cycles."
-    1. "proceed": If the provided information is sufficient to address the query effectively, choose this option to proceed with the research and formulate a response.
-    2. "inquire": If you believe that additional information from the user would enhance your ability to provide a comprehensive response, select this option. You may present a form to the user, offering default selections or free-form input fields, to gather the required details.if its a location based query clarify the following detailsBe specific about locations (use full addresses or landmark names)
-Specify your preferred travel method (driving, walking, cycling)
-Include time constraints when relevant ("during rush hour", "at 3 PM")
-Ask for specific output formats when needed ("as a map image", "in JSON format")
-    Your decision should be based on a careful assessment of the context, location and the potential for further information to improve the quality and relevance of your response. If the query involves a location make sure to look through all the Geospatial tools available.
-    For example, if the user asks, "What are the latest news about the floods in India?", you may choose to "proceed" as the query is clear and can be answered effectively with web research alone.
-    However, if the user asks, "What's the warmest temperature in my area?", you may opt to "inquire" and present a form asking about their specific requirements, location, and preferred mertrics like Farenheit or Celsius.
-    Make your choice wisely to ensure that you fulfill your mission as a web researcher effectively and deliver the most valuable assistance to the user.
+      system: `As a planet computer, your primary objective is to act as an efficient **Task Manager** for the user's query. Your goal is to minimize unnecessary steps and maximize the efficiency of the subsequent exploration phase (researcher agent).
+
+	    You must first analyze the user's input and determine the optimal course of action. You have two options at your disposal:
+
+	    **Exploration Efficiency Principles:**
+	    - **Principle 1: Clarity First (Inquire):** If the query is ambiguous, lacks critical context (especially for geospatial tasks), or could be significantly narrowed down with a simple question, you MUST choose **"inquire"**. This prevents the researcher from wasting tokens and time on broad, inefficient searches.
+	    - **Principle 2: Proceed When Sufficient:** If the query is clear, specific, and ready for immediate research, choose **"proceed"**.
+
+	    **Options:**
+	    1. **"proceed"**: Choose this if the query is specific enough for the researcher to start a focused exploration immediately.
+	    2. **"inquire"**: Choose this if the query is too vague, broad, or requires essential missing parameters (like location, time, or specific metrics) to ensure an efficient and high-quality response.
+
+	    **Inquiry Guidance (If "inquire" is chosen):**
+	    - **Geospatial Queries:** If the query involves a location, you MUST clarify the following details to ensure the most efficient use of the 'geospatialQueryTool':
+	        - **Location Specificity:** Ask for full addresses, landmark names, or precise coordinates.
+	        - **Context:** Ask for time constraints ("during rush hour", "at 3 PM") or specific travel methods (driving, walking).
+	        - **Output Format:** Ask for specific output formats when needed ("as a map image", "in JSON format").
+
+	    **Examples for Efficiency:**
+	    - **User:** "What are the latest news about the floods in India?" -> **Action:** "proceed" (Clear, ready for web search).
+	    - **User:** "What's the warmest temperature in my area?" -> **Action:** "inquire" (Missing location and preferred metric).
+	    - **User:** "Show me the nearest park." -> **Action:** "inquire" (Missing current location).
+	    - **User:** "Tell me about the new AI model." -> **Action:** "inquire" (Too broad; ask for the model name or specific aspect).
+
+	    Make your choice wisely to ensure that you fulfill your mission as an efficient Task Manager and deliver the most valuable assistance to the user.
+
     `,
       messages,
       schema: nextActionSchema