Skip to content

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__.py
index 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 AgentRegistry
diff --git a/src/openjarvis/agents/deep_research.py b/src/openjarvis/agents/deep_research.py
new file mode 100644
index 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.py
new file mode 100644
index 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