Personal AI, On Personal Devices
Python
feat: add DeepResearchAgent with multi-hop retrieval and cited reports
krypticmouse39a8117596db
diff --git a/src/openjarvis/agents/__init__.py b/src/openjarvis/agents/__init__.pyindex fa45bb94..ebf6ec6c 100644--- a/src/openjarvis/agents/__init__.py+++ b/src/openjarvis/agents/__init__.py@@ -69,6 +69,11 @@ try:except ImportError:pass+try:+ import openjarvis.agents.deep_research # noqa: F401+except ImportError:+ pass+# Registry alias: "react" -> NativeReActAgent (for backward compat)try:from openjarvis.core.registry import AgentRegistrydiff --git a/src/openjarvis/agents/deep_research.py b/src/openjarvis/agents/deep_research.pynew file mode 100644index 00000000..315991c0--- /dev/null+++ b/src/openjarvis/agents/deep_research.py@@ -0,0 +1,210 @@+"""DeepResearchAgent -- multi-hop retrieval agent with cited reports.++Searches personal data across sources (email, Slack, documents) using+native function calling (OpenAI tool_calls format), cross-references+results, and produces narrative answers with inline source citations.+"""++from __future__ import annotations++from typing import Any, List, Optional++from openjarvis.agents._stubs import AgentContext, AgentResult, ToolUsingAgent+from openjarvis.core.events import EventBus+from openjarvis.core.registry import AgentRegistry+from openjarvis.core.types import Message, Role, ToolCall, ToolResult+from openjarvis.engine._stubs import InferenceEngine+from openjarvis.tools._stubs import BaseTool++DEEP_RESEARCH_SYSTEM_PROMPT = """\+You are a deep research agent. Your job is to search the user's personal \+knowledge base thoroughly and produce a well-cited narrative report.++## Instructions++1. Use the **knowledge_search** tool to search ingested personal data \+(emails, Slack messages, documents, notes). Make multiple searches with \+different queries to cross-reference information across sources.+2. Use the **think** tool to reason between searches -- plan your next \+query, evaluate what you have found so far, and identify gaps.+3. After gathering enough evidence, produce a final narrative answer \+with inline citations in the format: [source] title -- author+4. Include a **Sources** section at the end listing all referenced sources.++## Rules++- Always cite your sources. Never present information without attribution.+- Make at least two searches to cross-reference across different sources.+- If a search returns no results, try rephrasing the query.+- Prefer specificity: filter by source, author, or date when appropriate.+- Your final answer should be a coherent narrative, not a list of raw results."""++[email protected]("deep_research")+class DeepResearchAgent(ToolUsingAgent):+ """Multi-hop research agent with native function calling and citations."""++ agent_id = "deep_research"+ _default_max_turns = 5+ _default_temperature = 0.3+ _default_max_tokens = 4096++ def __init__(+ self,+ engine: InferenceEngine,+ model: str,+ *,+ tools: Optional[List[BaseTool]] = None,+ bus: Optional[EventBus] = None,+ max_turns: Optional[int] = None,+ temperature: Optional[float] = None,+ max_tokens: Optional[int] = None,+ interactive: bool = False,+ confirm_callback=None,+ ) -> None:+ super().__init__(+ engine,+ model,+ tools=tools,+ bus=bus,+ max_turns=max_turns,+ temperature=temperature,+ max_tokens=max_tokens,+ interactive=interactive,+ confirm_callback=confirm_callback,+ )++ @staticmethod+ def _extract_sources(tool_results: List[ToolResult]) -> List[str]:+ """Collect unique source references from tool results.++ Parses the formatted output of ``KnowledgeSearchTool`` to pull out+ ``[source] title -- author`` style references.+ """+ sources: list[str] = []+ seen: set[str] = set()+ for tr in tool_results:+ if tr.tool_name != "knowledge_search" or not tr.success:+ continue+ for line in tr.content.splitlines():+ if line.startswith("**Result "):+ # Strip the **Result N:** prefix+ ref = line.split(":", 1)[1].strip() if ":" in line else line+ if ref and ref not in seen:+ seen.add(ref)+ sources.append(ref)+ return sources++ def run(+ self,+ input: str,+ context: Optional[AgentContext] = None,+ **kwargs: Any,+ ) -> AgentResult:+ self._emit_turn_start(input)++ # Build system prompt and initial messages+ messages = self._build_messages(+ input, context, system_prompt=DEEP_RESEARCH_SYSTEM_PROMPT+ )++ # Prepare OpenAI-format tool definitions for native function calling+ tools_openai = [t.to_openai_function() for t in self._tools]++ all_tool_results: list[ToolResult] = []+ turns = 0+ total_usage: dict[str, int] = {+ "prompt_tokens": 0,+ "completion_tokens": 0,+ "total_tokens": 0,+ }++ for _turn in range(self._max_turns):+ turns += 1++ if self._loop_guard:+ messages = self._loop_guard.compress_context(messages)++ # Pass tools to engine for native function calling+ result = self._generate(messages, tools=tools_openai)++ # Accumulate token usage+ usage = result.get("usage", {})+ for k in total_usage:+ total_usage[k] += usage.get(k, 0)++ content = result.get("content", "")+ tool_calls_raw = result.get("tool_calls", [])++ # No tool calls -- this is the final answer+ if not tool_calls_raw:+ self._emit_turn_end(turns=turns)+ return AgentResult(+ content=content,+ tool_results=all_tool_results,+ turns=turns,+ metadata=total_usage,+ )++ # Append assistant message with tool_calls metadata+ assistant_tool_calls = [+ ToolCall(+ id=tc["id"],+ name=tc["function"]["name"],+ arguments=tc["function"]["arguments"],+ )+ for tc in tool_calls_raw+ ]+ messages.append(+ Message(+ role=Role.ASSISTANT,+ content=content,+ tool_calls=assistant_tool_calls,+ )+ )++ # Execute each tool call and append results+ for tc_raw in tool_calls_raw:+ tc = ToolCall(+ id=tc_raw["id"],+ name=tc_raw["function"]["name"],+ arguments=tc_raw["function"]["arguments"],+ )++ # Loop guard check before execution+ if self._loop_guard:+ verdict = self._loop_guard.check_call(tc.name, tc.arguments)+ if verdict.blocked:+ tool_result = ToolResult(+ tool_name=tc.name,+ content=f"Loop guard: {verdict.reason}",+ success=False,+ )+ all_tool_results.append(tool_result)+ messages.append(+ Message(+ role=Role.TOOL,+ content=tool_result.content,+ tool_call_id=tc.id,+ name=tc.name,+ )+ )+ continue++ tool_result = self._executor.execute(tc)+ all_tool_results.append(tool_result)++ messages.append(+ Message(+ role=Role.TOOL,+ content=tool_result.content,+ tool_call_id=tc.id,+ name=tc.name,+ )+ )++ # Max turns exceeded+ return self._max_turns_result(all_tool_results, turns, metadata=total_usage)+++__all__ = ["DeepResearchAgent", "DEEP_RESEARCH_SYSTEM_PROMPT"]diff --git a/tests/agents/test_deep_research.py b/tests/agents/test_deep_research.pynew file mode 100644index 00000000..31b0400b--- /dev/null+++ b/tests/agents/test_deep_research.py@@ -0,0 +1,178 @@+"""Tests for DeepResearchAgent -- multi-hop retrieval with citations."""++from __future__ import annotations++import json+from unittest.mock import MagicMock++import pytest++from openjarvis.agents._stubs import AgentResult+from openjarvis.agents.deep_research import DeepResearchAgent+from openjarvis.connectors.store import KnowledgeStore+from openjarvis.core.registry import AgentRegistry+from openjarvis.tools.knowledge_search import KnowledgeSearchTool++# ---------------------------------------------------------------------------+# Fixtures+# ---------------------------------------------------------------------------+++def mock_engine():+ engine = MagicMock()+ engine.engine_id = "mock"+ engine.health.return_value = True+ return engine+++def store(tmp_path):+ s = KnowledgeStore(db_path=str(tmp_path / "dr_test.db"))+ s.store(+ content="Kubernetes migration proposed by Sarah",+ source="slack",+ doc_type="message",+ author="sarah",+ )+ s.store(+ content="Cost analysis shows 40% increase",+ source="gdrive",+ doc_type="document",+ author="sarah",+ )+ s.store(+ content="Migration approved March 8",+ source="gmail",+ doc_type="email",+ author="mike",+ )+ return s+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_engine_response(content, tool_calls=None):+ result = {+ "content": content,+ "usage": {+ "prompt_tokens": 50,+ "completion_tokens": 50,+ "total_tokens": 100,+ },+ "model": "test-model",+ "finish_reason": "stop",+ }+ if tool_calls:+ result["tool_calls"] = tool_calls+ result["finish_reason"] = "tool_calls"+ return result+++# ---------------------------------------------------------------------------+# Tests+# ---------------------------------------------------------------------------+++def test_agent_registration():+ """DeepResearchAgent registers under 'deep_research'."""+ AgentRegistry.register_value("deep_research", DeepResearchAgent)+ assert AgentRegistry.contains("deep_research")+++def test_agent_produces_result(mock_engine, store):+ """Engine returns final answer directly -- verify AgentResult has content."""+ mock_engine.generate.return_value = _make_engine_response(+ "Based on my research, the Kubernetes migration was approved."+ )+ ks_tool = KnowledgeSearchTool(store=store)+ agent = DeepResearchAgent(mock_engine, "test-model", tools=[ks_tool])+ result = agent.run("What happened with the Kubernetes migration?")+ assert isinstance(result, AgentResult)+ assert "migration" in result.content.lower() or "Kubernetes" in result.content+ assert result.turns == 1+ assert result.tool_results == []+++def test_agent_uses_knowledge_search(mock_engine, store):+ """Engine returns tool_call first, then final answer; verify tool was called."""+ tool_call_response = _make_engine_response(+ "",+ tool_calls=[+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "knowledge_search",+ "arguments": json.dumps({"query": "Kubernetes migration"}),+ },+ }+ ],+ )+ final_response = _make_engine_response(+ "The Kubernetes migration was proposed by Sarah and approved by Mike."+ )+ mock_engine.generate.side_effect = [tool_call_response, final_response]++ ks_tool = KnowledgeSearchTool(store=store)+ agent = DeepResearchAgent(mock_engine, "test-model", tools=[ks_tool])+ result = agent.run("Tell me about the Kubernetes migration")++ assert result.turns == 2+ assert len(result.tool_results) == 1+ assert result.tool_results[0].tool_name == "knowledge_search"+ assert result.tool_results[0].success is True+ assert "migration" in result.content.lower() or "Kubernetes" in result.content+++def test_agent_respects_max_turns(mock_engine, store):+ """Engine always returns tool_calls; verify turns <= max_turns."""+ always_search = _make_engine_response(+ "",+ tool_calls=[+ {+ "id": "call_loop",+ "type": "function",+ "function": {+ "name": "knowledge_search",+ "arguments": json.dumps({"query": "migration"}),+ },+ }+ ],+ )+ mock_engine.generate.return_value = always_search++ ks_tool = KnowledgeSearchTool(store=store)+ agent = DeepResearchAgent(mock_engine, "test-model", tools=[ks_tool], max_turns=3)+ result = agent.run("Keep searching forever")++ assert result.turns == 3+ assert result.metadata.get("max_turns_exceeded") is True+ assert len(result.tool_results) == 3+++def test_agent_system_prompt_mentions_research(mock_engine, store):+ """System message contains 'research' and 'source'."""+ mock_engine.generate.return_value = _make_engine_response("Done.")++ ks_tool = KnowledgeSearchTool(store=store)+ agent = DeepResearchAgent(mock_engine, "test-model", tools=[ks_tool])+ agent.run("test")++ call_args = mock_engine.generate.call_args+ messages = call_args[0][0]+ system_msg = messages[0]+ assert system_msg.role.value == "system"+ assert "research" in system_msg.content.lower()+ assert "source" in system_msg.content.lower()+++def test_agent_defaults():+ """Verify agent_id, default max_turns, temperature, max_tokens."""+ assert DeepResearchAgent.agent_id == "deep_research"+ assert DeepResearchAgent._default_max_turns == 5+ assert DeepResearchAgent._default_temperature == 0.3+ assert DeepResearchAgent._default_max_tokens == 4096