Spaces:
Runtime error
Runtime error
Download research_agent.py from pythonpyro/deep-research-agent: direct link, hf CLI and curl.
- Browser
- Download file 20.7 kB
-
https://huggingface.co/spaces/pythonpyro/deep-research-agent/resolve/main/research_agent.py
- Command line
-
hf download hf://spaces/pythonpyro/deep-research-agent/research_agent.py
-
curl -L -o research_agent.py https://huggingface.co/spaces/pythonpyro/deep-research-agent/resolve/main/research_agent.py
20.7 kB
| # ============================================================================ | |
| # research_agent.py - BACKEND | |
| # ============================================================================ | |
| from typing import TypedDict, List, Literal, Annotated | |
| import os | |
| from dotenv import load_dotenv | |
| from langgraph.graph import StateGraph, START, END | |
| from langgraph.graph.message import add_messages | |
| from langgraph.prebuilt import ToolNode | |
| from langchain.tools import tool | |
| from langchain_openai import ChatOpenAI | |
| from langchain_core.messages import HumanMessage, SystemMessage | |
| from openai import OpenAI | |
| from tavily import TavilyClient | |
| # ============================================================================ | |
| # CONFIGURATION & INITIALIZATION | |
| # ============================================================================ | |
| # Load environment variables from .env file | |
| load_dotenv() | |
| # Initialize API clients with environment variables as fallback | |
| # These will be overridden by user-provided keys in process_message | |
| OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") | |
| TAVILY_API_KEY = os.getenv("TAVILY_API_KEY") | |
| # Initialize API clients with environment variables | |
| # These will be re-initialized with user-provided keys when needed | |
| openai_client = None | |
| llm = None | |
| light_llm = None | |
| def initialize_clients(openai_key: str, tavily_key: str): | |
| """ | |
| Initialize API clients with provided keys. | |
| This function is called from process_message with user-provided API keys. | |
| """ | |
| global openai_client, llm, light_llm, tool_node, llm_with_tools | |
| if not openai_key or not tavily_key: | |
| raise ValueError("Both OpenAI and Tavily API keys must be provided.") | |
| openai_client = OpenAI(api_key=openai_key) | |
| llm = ChatOpenAI(model="gpt-5.1", api_key=openai_key, temperature=0) # Main LLM for research and synthesis | |
| light_llm = ChatOpenAI(model="gpt-4o-mini", api_key=openai_key, temperature=0) # Lighter LLM for clarification | |
| # Initialize tool node and bind tools to LLM | |
| tool_node = ToolNode(tools) | |
| llm_with_tools = llm.bind_tools([rag_search, web_search], tool_choice="auto") | |
| # Create and compile the research graph now that tool_node is ready | |
| create_research_graph() | |
| # Set maximum number of research iterations to prevent infinite loops | |
| # This is a default value and will be overridden by user input | |
| DEFAULT_MAX_ITERATIONS = 3 | |
| # Global variable to store max iterations for research | |
| MAX_ITERATIONS = DEFAULT_MAX_ITERATIONS | |
| # Global variable to store tavily API key for use in web_search tool | |
| _tavily_api_key = None | |
| # ============================================================================ | |
| # VECTOR STORE SETUP | |
| # ============================================================================ | |
| # Connect to pre-existing vector store containing embedded PDF documents | |
| VECTOR_STORE_NAME = "yt-store" | |
| store_id = None | |
| def get_vector_store_id(): | |
| """ | |
| Retrieve the vector store ID. This needs to be called after clients are initialized. | |
| """ | |
| global store_id | |
| if not openai_client: | |
| raise ValueError("OpenAI client not initialized. Call initialize_clients first.") | |
| # Search for the vector store by name in the OpenAI account | |
| for s in openai_client.vector_stores.list().data: | |
| if s.name == VECTOR_STORE_NAME: | |
| store_id = s.id | |
| break | |
| # Raise error if vector store is not found | |
| if not store_id: | |
| raise ValueError("β Vector store not found!") | |
| print(f"β» Using vector store ID: {store_id}") | |
| return store_id | |
| # ============================================================================ | |
| # TOOL DEFINITIONS | |
| # ============================================================================ | |
| def rag_search(query: str) -> str: | |
| """ | |
| Search INTERNAL knowledge base containing curated documents, | |
| architecture guides, tutorials, and domain expertise. | |
| Use for conceptual understanding, internal best practices, | |
| and previously authored materials. | |
| """ | |
| print(f"π RAG Search called with query: {query}") | |
| # Query the vector store with semantic search | |
| res = openai_client.vector_stores.search( | |
| vector_store_id=store_id, | |
| query=query, | |
| max_num_results=3, # Return top 3 most relevant chunks | |
| ranking_options={"score_threshold": 0.5, "ranker": "auto"} # Filter by relevance score | |
| ) | |
| # Handle case where no results are found | |
| if not res.data: | |
| return "No relevant information found in internal documents." | |
| # Extract text content from search results | |
| out = [] | |
| for item in res.data: | |
| for block in item.content or []: | |
| if block.type == "text" and block.text: | |
| out.append(block.text) | |
| # Combine all text chunks with separator | |
| result = "\n\n".join(out) if out else "No relevant text extracted from internal documents." | |
| print(f"β RAG Search returned {len(out)} chunks") | |
| return result | |
| def web_search(query: str) -> str: | |
| """ | |
| Search the public internet for recent developments, | |
| benchmarks, and up-to-date information. | |
| """ | |
| global _tavily_api_key | |
| print(f"π Web Search called with query: {query}") | |
| try: | |
| # Use Tavily API for web search | |
| tavily_client = TavilyClient(api_key=_tavily_api_key) | |
| response = tavily_client.search(query, max_results=3) | |
| # Format search results into readable text | |
| results = [] | |
| for result in response.get('results', []): | |
| results.append(f"Title: {result.get('title', 'N/A')}\nContent: {result.get('content', 'N/A')}\nURL: {result.get('url', 'N/A')}") | |
| final_result = "\n\n---\n\n".join(results) if results else "No web search results found." | |
| print(f"β Web Search returned {len(results)} results") | |
| return final_result | |
| except Exception as e: | |
| print(f"β Web search error: {str(e)}") | |
| return f"Web search error: {str(e)}" | |
| # ============================================================================ | |
| # TOOL NODE SETUP | |
| # ============================================================================ | |
| # Combine tools into a list for the agent | |
| tools = [rag_search, web_search] | |
| # These will be initialized when initialize_clients() is called | |
| tool_node = None | |
| llm_with_tools = None | |
| # ============================================================================ | |
| # STATE DEFINITION | |
| # ============================================================================ | |
| # Define the state structure that will be passed between nodes | |
| class AgentState(TypedDict): | |
| messages: Annotated[List, add_messages] # Conversation history with automatic message aggregation | |
| research_steps: List[str] # Track the research plan steps | |
| final_answer: str # Store the synthesized final answer | |
| iterations: int # Count how many research iterations have occurred | |
| # ============================================================================ | |
| # CLARIFICATION NODE | |
| # ============================================================================ | |
| # System prompt for the clarification phase | |
| CLARIFICATION_PROMPT = """ | |
| You are a research assistant helping refine a user's research request. | |
| Your goal is NOT to answer yet. | |
| Instead: | |
| 1. Acknowledge the topic positively | |
| 2. Ask smart follow-up questions to narrow scope | |
| 3. Offer categories to choose from | |
| 4. Ask about: | |
| - target audience | |
| - depth level | |
| - specific domains | |
| - time range | |
| - technical vs business focus | |
| Example style: | |
| "Great topic! Before I begin deep research, could you help me refine the scope?" | |
| Then ask 3-5 concise questions. | |
| DO NOT start researching yet. | |
| """ | |
| def clarification_node(state: AgentState): | |
| """ | |
| Node that asks clarifying questions to refine the research scope. | |
| This runs BEFORE research begins. | |
| """ | |
| print("\n㪠Clarification phase...\n") | |
| messages = state["messages"] | |
| # If we already asked clarification, just wait for user input | |
| if state.get("phase") == "awaiting_user": | |
| return state | |
| # Use lighter LLM to generate clarification questions | |
| response = light_llm.invoke([ | |
| SystemMessage(content=CLARIFICATION_PROMPT), | |
| messages[-1] | |
| ]) | |
| return { | |
| "messages": [response] | |
| } | |
| # ============================================================================ | |
| # PLANNER NODE | |
| # ============================================================================ | |
| # System prompt for research planning | |
| PLANNER_PROMPT = """ | |
| You are a deep research planning assistant. | |
| Your job is to create a DUAL-SOURCE research plan. | |
| For each major aspect of the user question: | |
| Generate: | |
| - ONE query specifically designed for INTERNAL knowledge (rag_search) | |
| - ONE complementary query for EXTERNAL knowledge (web_search) | |
| Return the plan in this EXACT format: | |
| TOPIC 1: | |
| RAG_QUERY: <query text optimized for internal documents> | |
| WEB_QUERY: <query text optimized for current internet info> | |
| TOPIC 2: | |
| RAG_QUERY: ... | |
| WEB_QUERY: ... | |
| TOPIC 3: | |
| RAG_QUERY: ... | |
| WEB_QUERY: ... | |
| At least 3 topics must be generated. | |
| The goal is to ensure BOTH tools are used for comprehensive coverage. | |
| """ | |
| def planner_node(state: AgentState): | |
| """ | |
| Node that creates a structured research plan. | |
| Generates paired RAG and Web queries for each research topic. | |
| """ | |
| print("\nπ§ Planning research approach...\n") | |
| # Extract the user's refined question | |
| user_question = state["messages"][-1].content | |
| messages = [ | |
| SystemMessage(content=PLANNER_PROMPT), | |
| HumanMessage(content=user_question) | |
| ] | |
| # Generate the research plan | |
| plan = llm.invoke(messages) | |
| return { | |
| "messages": [plan], | |
| "research_steps": [plan.content] # Store plan for tracking | |
| } | |
| # ============================================================================ | |
| # RESEARCH AGENT NODE | |
| # ============================================================================ | |
| # System prompt for the research agent | |
| RESEARCH_PROMPT = """ | |
| You are a balanced deep research assistant. | |
| You MUST use BOTH tools for every major topic: | |
| - rag_search β to gather internal curated knowledge | |
| - web_search β to gather current external information | |
| Do NOT rely on only one tool. | |
| Process: | |
| 1. Look at the research plan | |
| 2. For each topic: | |
| - First call rag_search with the RAG_QUERY | |
| - Then call web_search with the WEB_QUERY | |
| You may call tools multiple times in one response. | |
| Continue until all planned topics have been covered. | |
| Only stop when: | |
| - every RAG query has been executed | |
| - every WEB query has been executed | |
| """ | |
| def research_agent_node(state: AgentState): | |
| """ | |
| Node that executes the research plan by calling tools. | |
| This is the core agentic loop that gathers information. | |
| """ | |
| print("\nπ Research agent analyzing next step...\n") | |
| messages = state["messages"] | |
| # Add system prompt if not already present | |
| if not any(isinstance(msg, SystemMessage) for msg in messages): | |
| messages = [SystemMessage(content=RESEARCH_PROMPT)] + messages | |
| # LLM decides which tools to call based on the plan | |
| response = llm_with_tools.invoke(messages) | |
| return { | |
| "messages": [response], | |
| "iterations": state.get("iterations", 0) + 1 # Increment iteration counter | |
| } | |
| # ============================================================================ | |
| # SYNTHESIZER NODE | |
| # ============================================================================ | |
| # System prompt for final synthesis | |
| SYNTHESIS_PROMPT = """ | |
| You are a research report writer. | |
| Using ALL the previous research results: | |
| - Internal RAG findings | |
| - Web findings | |
| - Multiple iterations of searches | |
| Create a detailed, well-structured final answer. | |
| Format: | |
| OVERVIEW | |
| ------- | |
| INTERNAL KNOWLEDGE FINDINGS | |
| -------------------------- | |
| WEB RESEARCH FINDINGS | |
| --------------------- | |
| FINAL SYNTHESIS | |
| -------------- | |
| CONCLUSION | |
| --------- | |
| """ | |
| def synthesizer_node(state: AgentState): | |
| """ | |
| Node that synthesizes all research findings into a structured report. | |
| This is the final step that produces the deliverable. | |
| """ | |
| print("\nβοΈ Synthesizing final answer...\n") | |
| # Clean messages to remove tool calls and tool responses | |
| # (only keep actual content for cleaner synthesis) | |
| clean_messages = [] | |
| for msg in state["messages"]: | |
| # Skip any message containing tool calls | |
| if hasattr(msg, "tool_calls") and msg.tool_calls: | |
| continue | |
| # Skip any raw tool response messages | |
| if msg.type == "tool": | |
| continue | |
| clean_messages.append(msg) | |
| # Add synthesis prompt and generate final report | |
| messages = clean_messages + [ | |
| SystemMessage(content=SYNTHESIS_PROMPT) | |
| ] | |
| final = llm.invoke(messages) | |
| return { | |
| "messages": [final], | |
| "final_answer": final.content # Store the final answer | |
| } | |
| # ============================================================================ | |
| # ROUTING LOGIC | |
| # ============================================================================ | |
| def research_router(state: AgentState) -> Literal["tools", "synthesize"]: | |
| """ | |
| Router that decides whether to continue research or move to synthesis. | |
| Decision logic: | |
| 1. Ensure both RAG and Web tools have been used at least once | |
| 2. Stop if max iterations reached (safety limit) | |
| 3. Continue if agent is still calling tools | |
| 4. Otherwise, move to synthesis | |
| """ | |
| last_message = state["messages"][-1] | |
| current_iterations = state.get("iterations", 0) | |
| print(f"π Iteration count: {current_iterations}") | |
| # Check conversation history to see which tools were used | |
| history = str(state["messages"]) | |
| used_rag = "rag_search" in history | |
| used_web = "web_search" in history | |
| # Force at least one call to each tool for comprehensive research | |
| if not (used_rag and used_web): | |
| print("π Ensuring both RAG and Web sources are used...") | |
| return "tools" | |
| # HARD STOP: Prevent infinite loops by limiting iterations | |
| if current_iterations >= MAX_ITERATIONS: | |
| print("π Max iterations reached β forcing synthesis") | |
| return "synthesize" | |
| # If agent is still requesting tool calls, continue research | |
| if hasattr(last_message, "tool_calls") and last_message.tool_calls: | |
| print("π Continuing research loop...") | |
| return "tools" | |
| # Otherwise, research is complete | |
| print("β Research sufficient. Moving to synthesis.") | |
| return "synthesize" | |
| # ============================================================================ | |
| # GRAPH CONSTRUCTION | |
| # ============================================================================ | |
| # ---------- CLARIFICATION GRAPH ---------- | |
| # Simple linear graph: just asks clarifying questions | |
| clarify_graph = StateGraph(AgentState) | |
| # Add nodes | |
| clarify_graph.add_node("clarify", clarification_node) | |
| # Add edges: START β clarify β END | |
| clarify_graph.add_edge(START, "clarify") | |
| clarify_graph.add_edge("clarify", END) | |
| # Compile the graph into an executable app | |
| clarify_app = clarify_graph.compile() | |
| # ---------- RESEARCH WORKFLOW GRAPH ---------- | |
| # This will be compiled on first use after clients are initialized | |
| research_app = None | |
| def create_research_graph(): | |
| """ | |
| Create and compile the research workflow graph. | |
| Must be called after initialize_clients() so that tool_node is ready. | |
| """ | |
| global research_app | |
| if tool_node is None: | |
| raise ValueError("Tool node not initialized. Call initialize_clients first.") | |
| research_graph = StateGraph(AgentState) | |
| # Add nodes | |
| research_graph.add_node("planner", planner_node) | |
| research_graph.add_node("researcher", research_agent_node) | |
| research_graph.add_node("tools", tool_node) | |
| research_graph.add_node("synthesizer", synthesizer_node) | |
| # Add edges | |
| # Flow: START β planner β researcher β (conditional loop) β synthesizer β END | |
| research_graph.add_edge(START, "planner") | |
| research_graph.add_edge("planner", "researcher") | |
| # Conditional edge: researcher decides to continue or finish | |
| research_graph.add_conditional_edges( | |
| "researcher", | |
| research_router, # Router function decides next step | |
| { | |
| "tools": "tools", # Continue research | |
| "synthesize": "synthesizer" # Finish and synthesize | |
| } | |
| ) | |
| # After tools execute, loop back to researcher | |
| research_graph.add_edge("tools", "researcher") | |
| # After synthesis, end the workflow | |
| research_graph.add_edge("synthesizer", END) | |
| # Compile the research graph | |
| research_app = research_graph.compile() | |
| return research_app | |
| # ============================================================================ | |
| # BACKEND API FUNCTIONS | |
| # ============================================================================ | |
| def create_initial_state(): | |
| """ | |
| Initialize the session state for a new conversation. | |
| Tracks: messages, iterations, answers, and current stage. | |
| """ | |
| return { | |
| "messages": [], | |
| "iterations": 0, | |
| "final_answer": "", | |
| "research_steps": [], | |
| "stage": "awaiting_topic" # UI flow stage | |
| } | |
| def process_message(user_input, history, state, openai_api_key, tavily_api_key, max_iterations=2): | |
| """ | |
| Main message processing function that handles the multi-turn conversation. | |
| Flow: | |
| 1. User enters topic β Clarification questions | |
| 2. User answers β Deep research begins | |
| 3. Research completes β Final report shown | |
| Args: | |
| max_iterations: Number of research loops to perform (2 means one loop of the research node) | |
| """ | |
| global _tavily_api_key, MAX_ITERATIONS | |
| # Set the global MAX_ITERATIONS with user-provided value | |
| MAX_ITERATIONS = max_iterations | |
| # Initialize clients with provided API keys | |
| try: | |
| initialize_clients(openai_api_key, tavily_api_key) | |
| _tavily_api_key = tavily_api_key | |
| # Retrieve vector store ID with initialized client | |
| get_vector_store_id() | |
| except ValueError as e: | |
| error_msg = f"β Configuration Error: {str(e)}" | |
| if history is None: | |
| history = [] | |
| history.append({"role": "assistant", "content": error_msg}) | |
| return "", history, state | |
| # Initialize state if first message | |
| if state is None: | |
| state = create_initial_state() | |
| if history is None: | |
| history = [] | |
| stage = state.get("stage", "awaiting_topic") | |
| # ---- FIRST TURN: Initial topic entry ---- | |
| if stage == "awaiting_topic": | |
| # Store user's initial question | |
| state["messages"] = [HumanMessage(content=user_input)] | |
| # Run clarification graph to ask follow-up questions | |
| state = clarify_app.invoke(state) | |
| clarification = state["messages"][-1].content | |
| # Update chat history | |
| history.append({"role": "user", "content": user_input}) | |
| history.append({"role": "assistant", "content": clarification}) | |
| # Move to next stage | |
| state["stage"] = "awaiting_clarification" | |
| return "", history, state | |
| # ---- SECOND TURN: User provides clarification ---- | |
| elif stage == "awaiting_clarification": | |
| # Add user's clarification to conversation | |
| state["messages"].append(HumanMessage(content=user_input)) | |
| # Clean artifacts from previous interactions | |
| clean_messages = [] | |
| for msg in state["messages"]: | |
| if hasattr(msg, "tool_calls") and msg.tool_calls: | |
| continue | |
| if msg.type == "tool": | |
| continue | |
| clean_messages.append(msg) | |
| # Reset state for fresh research | |
| state["messages"] = clean_messages | |
| state["iterations"] = 0 | |
| # Update UI | |
| history.append({"role": "user", "content": user_input}) | |
| history.append({"role": "assistant", "content": "π Starting deep research... please wait..."}) | |
| # Run the full research workflow graph | |
| final_state = research_app.invoke(state) | |
| # Extract final answer | |
| final_answer = final_state["messages"][-1].content | |
| # Show result in chat | |
| history.append({"role": "assistant", "content": final_answer}) | |
| # Mark research as completed | |
| final_state["stage"] = "completed" | |
| return "", history, final_state | |
| # ---- AFTER COMPLETION: No further research ---- | |
| else: | |
| history.append({"role": "assistant", "content": "Research already completed. Refresh page to start a new topic."}) | |
| return "", history, state |