Diffusion Loop
+
+ Tool: think. Identify draft gaps and propose diverse research questions tied to
+ those gaps.
+
Expected: 3–5 targeted questions, each mapped to a draft gap with scope/priority notes.
+ +
+ Tool: ConductResearch. Delegate distinct questions to sub-agents with explicit
+ instructions and expected returns.
+
Expected: cited findings (URLs + quotes) per sub-agent, deduped URLs, short summaries.
+ +
+ Tool: refine_draft_report. Fold new findings into the draft; keep structure
+ concise to conserve context.
+
+ Expected: draft updated with citations/quotes; bullets or short paragraphs retained for + clarity and context efficiency. +
+ +Heuristic: diverse new searches should stop yielding new facts. If not, loop again.
+
+ Expected: a clear decision to continue or call ResearchComplete, with rationale
+ noted.
+
Diffusion Overview
++ The report covers [pillars] across labs, + highlighting [methods] with citations to + [sources]. +
+ ), + }, + { + label: 'Refined text', + render: ( ++ OpenAI: RLHF + eval gates. Anthropic: Constitutional AI + red-team. DeepMind: + interpretability + strict evals. Cited incidents and mitigations mapped to primary URLs. +
+ ), + }, +]; + +interface DraftDenoisingProps { + className?: string; +} + +export function DraftDenoising({ className }: DraftDenoisingProps) { + const ref = useRefDraft Denoising
+
+
+
+ The report converges toward a comprehensive, insight-rich, and readable deliverable + with clean citations that pass the FACT evaluation. +
+Parallel Sub-Agents
++ {stage === 'assign' && 'Assigning distinct questions...'} + {stage === 'research' && 'Monitoring parallel research...'} + {stage === 'collect' && 'Collecting findings...'} + {stage === 'refine' && 'Refining draft...'} + {stage === 'decide' && 'Assessing completeness...'} +
+
+
+ Topic: {agent.topic} +
++ Focus: {agent.focus} +
+ + {/* Status messages container - always render, control opacity */} ++ {stage === 'refine' + ? 'Incorporating findings with citations...' + : 'Draft updated with citations'} +
+How it works:
+
+
+ Note: At this time, Trivy tops this benchmark with a secret model. +
+Self-Balancing
+Outputs
++ Goal: close evidence gaps with primary sources before any polish. +
+Outputs
++ Goal: readable, insightful synthesis once facts are locked. +
+- The command will prompt you with "what would you like to research?" Provide a detailed - prompt like: + The command will prompt you with "what would you like to research?" Provide a + detailed prompt like:
This generates a research document with file references, target architecture, and - critically—a "What not to do" section that helps guide Claude in the right direction - without detours. + critically—a "What not to do" section that helps guide Claude in the right + direction without detours.
Important: Review the research document closely. Check if it found all relevant files, if the target architecture looks reasonable, and if you agree with the - "what not to do" section. In about 50% of cases, I edit these sections manually using - Cursor with a powerful model or by editing the file directly. + "what not to do" section. In about 50% of cases, I edit these sections manually + using Cursor with a powerful model or by editing the file directly.
@@ -420,9 +420,10 @@ Follow @frontend/ARCHITECTURE.md guidelines and patterns.`}
- Additional instructions might include: "make it 4 phases", "make sure to add e2e tests in - the frontend to the plan", etc. You can also add "think deeply" for higher accuracy (but - avoid "ultrathink"—it's a token burner that uses the main context to explore). + Additional instructions might include: "make it 4 phases", "make sure to + add e2e tests in the frontend to the plan", etc. You can also add "think + deeply" for higher accuracy (but avoid "ultrathink"—it's a token + burner that uses the main context to explore).
@@ -462,9 +463,9 @@ Follow @frontend/ARCHITECTURE.md guidelines and patterns.`}
Repeat this loop for each phase until all phases are complete, then run a final validation on the full plan. I typically review the code between iterations to ensure it makes sense - and guide the AI if needed. Aim for "working software" in each phase—tests should pass and - there should be no lint errors. The validation step will catch missing interface - implementations and run your linters. + and guide the AI if needed. Aim for "working software" in each phase—tests + should pass and there should be no lint errors. The validation step will catch missing + interface implementations and run your linters.
In my experience, this flow completely 1-shots (after research/plan refinements) 2-5 such - features per day. I run up to 3 in parallel—one "big hairy" problem and two simpler, more - straightforward ones. + features per day. I run up to 3 in parallel—one "big hairy" problem and two + simpler, more straightforward ones.
- In the future, I want to make this a "linear workflow" where humans gather information - into Linear issues (the initial research prompts), and moving issues into different phases - would auto-trigger different steps, creating PRs with research docs, etc. + In the future, I want to make this a "linear workflow" where humans gather + information into Linear issues (the initial research prompts), and moving issues into + different phases would auto-trigger different steps, creating PRs with research docs, etc.
I don't think this will work well in all settings and codebases. The right type of - "mid/mid+" size problems is the right fit. The better your codebase is, the better code AI - will write. Just like in boomer-coding, quality compounds into velocity over time, and - tech debt snowballs to a turd, but with AI the effects of this have increased. Prioritize - solving your tech debt! + "mid/mid+" size problems is the right fit. The better your codebase is, the + better code AI will write. Just like in boomer-coding, quality compounds into velocity + over time, and tech debt snowballs to a turd, but with AI the effects of this have + increased. Prioritize solving your tech debt!
Also, in my experience, language matters... in TS/JS you can loop in 20+ different ways or - chain useEffects in magical ways to create foot-cannons... if Cloudflare can't properly - use useEffect... are you sure our PhD-level next token predictors can? I actually like a - lot of things about TS, but too many variations confuse the AI. In my "big" codebase I'm - working on our backend is built in Go, and Claude/Cursor are simply fantastic there! - Simplicity = clarity = less hallucination = higher velocity. This is at least the state - late 2025, in a year or so... who knows. + chain useEffects in magical ways to create foot-cannons... if Cloudflare can't + properly use useEffect... are you sure our PhD-level next token predictors can? I actually + like a lot of things about TS, but too many variations confuse the AI. In my + "big" codebase I'm working on our backend is built in Go, and Claude/Cursor + are simply fantastic there! Simplicity = clarity = less hallucination = higher velocity. + This is at least the state late 2025, in a year or so... who knows.
+ {tokens.map((line, lineIndex) => {
+ const lineProps = getLineProps({ line });
+ return (
+
+ {line.map((token, tokenIndex) => {
+ const tokenProps = getTokenProps({ token });
+ return ;
+ })}
+
+ );
+ })}
+
+ )}
+ + Remember back in school when you had one of those infamous and dreaded group projects (I + kinda liked them)... +
++ At least a few times you probably tried the “parallel” way of working, + optimizing for a bit less collaboration and each participant owning one segment of the + report. Off you go! Each person for themselves writing extensive backgrounds, history, + theory, or whatever segments you decided on. Then you meet up 3 hours before the deadline + to “glue the report” together—how did that turn out? +
+The result was probably:
++ It turns out, when we construct our AI research agents like this (plan -> parallel + research -> glue research into report), we get the same problem! When no context of the + “evolving report” is shared across sub-agents, we get a fragmented ball of + mud. +
++ These sequential and isolated group projects/research agents have their perks, like high + level of autonomy and parallelism... but there are probably better ways to do it. +
+ ++ Think of diffusion agent models like brainstorming, but instead of everyone writing their + own part in isolation and building a Frankenstein report, the research spreads and + overlaps as it evolves within the team. Ideas for each segment are not isolated, as not + one person owns each segment. +
++ The team starts off by writing a draft, only based on their internal knowledge. Typically + in bullet point format with clear notes about missing references, knowledge gaps, outdated + information, and uncertainty. +
++ The students prioritize these knowledge gaps together and research different perspectives + of those gaps (in parallel isolation) and add them back to the report in an iterative + manner as a group. Gradually the draft evolves into an iteratively better report, filling + gaps and enriching knowledge. The draft grows to become the final report. In each writing + step, the students have a clear process for transforming rich knowledge into a concise + report that fits into the whole story they are trying to tell. +
++ To me, this makes a lot more sense! I'll explore the implementation details of text + diffusion in this blog post. Enjoy! +
+
+ Traditional AI research agents follow a linear paradigm:{' '}
+ Query → Search → Synthesize → Report. This suffers from fundamental
+ limitations:
+
+ Diffusion models, originally developed for image generation, provide an elegant solution. + Instead of generating content in one pass, they start with a{' '} + noisy initial state (random noise for images, rough draft for research) and{' '} + iteratively refine through multiple denoising steps, using{' '} + guidance signals to steer the refinement. +
+ ++ “The iterative nature of diffusion models naturally mirrors how humans actually + conduct research—cycles of searching, reasoning, and revision.” ++ +
+ + — Google Research, Deep Researcher with Test-Time Diffusion, 2025 + +
+ The implementation consists of four primary phases, orchestrated through a state machine: +
+ ++ Transform the user query into a detailed research brief with sources, constraints, and + scope. This ensures all downstream research is grounded in explicit requirements. +
+ ++ Generate a draft from the LLM's internal knowledge only—no external + information retrieval yet. This is the “noisy” initial state that provides + structure to guide subsequent research. It may contain outdated or incomplete information, + and that's intentional. +
+ +The core innovation. Each iteration follows four steps:
++ Apply quality optimization with Insightfulness + Helpfulness rules. Deduplicate findings by + URL, add granular breakdowns, detailed mapping tables, nuanced discussion, and proper + citations. +
+ ++ The core innovation is the Self-Balancing Test-Time Diffusion algorithm, + encoded directly in the supervisor's system prompt. Here is the exact algorithm from + the Go implementation: +
+ ++ The full diffusion algorithm prompt is available as a collapsible block in the code + walkthrough below. +
+ ++ In classical diffusion models (DDPM, Stable Diffusion), the process consists of two phases: +
+
+ Forward Diffusion: Gradually add noise to data:{' '}
+ x₀ → x₁ → x₂ → ... → xₜ (pure noise)
+
+ Reverse Diffusion: Learn to denoise step by step:{' '}
+ xₜ → xₜ₋₁ → ... → x₁ → x₀ (clean data)
+
+ For the readers that have walked the fields of Machine Learning, this feels like an + autoencoder but that goes to complete noise instead of a low-dimensional latent space + representation (that still actually means something). With key differences of course.. (for + another blog post) +
+ +For research report generation, we reinterpret this process:
+ +| Classical Diffusion | +Research Diffusion | +
|---|---|
| Random noise (xₜ) | +Initial draft from model knowledge | +
| Denoising step | +Research iteration + draft refinement | +
| Guidance signal | +Retrieved information from web search | +
| Clean output (x₀) | +Comprehensive, accurate research report | +
+ The key insight is that the initial draft generated purely from the + LLM's training data represents the “noisy” starting state. Each iteration + of identifying gaps, searching for information, and incorporating findings acts as a{' '} + denoising step that brings the report closer to ground truth. +
+ +The process terminates when (in priority order):
++ A walkthrough of how the supervisor and sub-agents iterate, including prompts, parallel + fan-out, and final synthesis. The code is complementary to the free-text explanations, to + skip or deep-dive into the details as you see fit. +
+ +
+ The entry point is AgentLoop.Research. This function orchestrates all four
+ phases of the diffusion algorithm. The first two phases are straightforward LLM calls:
+
This is the heart of the algorithm. The supervisor runs an iterative loop that:
+
+ Now let's look inside SupervisorAgent.Coordinate to see the actual loop.
+ This is where tool calls are parsed, parallelism is handled, and the draft evolves:
+
+ When the supervisor receives multiple conduct_research calls in one response,
+ they execute in parallel (maxConcurrent defaults to 3). If a batch is still
+ running, avoid issuing a new fan-out to reduce thrash/backpressure.
+
+ Each sub-researcher is a complete agent with its own tool loop. It receives only the topic + (no visibility into other agents' work) and runs its own search/analysis cycle: +
++ After the diffusion loop completes, the final phase synthesizes everything into a polished + report. This applies the Insightfulness + Helpfulness quality rules: +
++ The algorithm explicitly separates information gap closing from{' '} + generation gap closing: +
+ ++ “There is a trade-off between the two gaps. We cannot optimize the generation gap too + early when the system is still optimizing the information gap because the generation gap + tends to bring more verbose and stylistic content that can distract from finding missing + information.” ++ +
+ — Paichun Lin, ThinkDepth.ai +
+ Stage 1 characteristics: +
++ Stage 2 characteristics: +
++ Long-horizon research tasks face several context challenges. The diffusion approach + addresses each systematically: +
+ +| Problem | +Description | +Diffusion Solution | +
|---|---|---|
| Context Poisoning | +Hallucinations enter context | +Draft serves as verified state | +
| Context Distraction | +Too much context overwhelms focus | +Parallel sub-agents with isolated contexts | +
| Context Confusion | +Superfluous context influences output | +Structured finding format with compression | +
| Context Clash | +Parts of context disagree | +Supervisor resolves conflicts during refinement | +
+ The draft serves as a persistent, verified context that: +
+refine_draft call is validated
+ + Sub-researchers operate with isolated contexts—they cannot see each + other's work. This prevents topic A's findings from biasing topic B's + research, keeps context from growing unboundedly during parallel work, and avoids confusion + from interleaved search results. +
+ ++ RACE (report quality) and FACT (citation quality) are the primary DeepResearch Bench lenses: + RACE judges coverage, insight, instruction-following, and readability; FACT scores citation + accuracy and effective citations. +
+
+
RACE evaluates report generation quality through four dimensions:
+FACT evaluates information retrieval and grounding capabilities:
+
+ I implemented a version of this in go in the blog repository, in: /go-research.
+ It expects API keys and runs a REPL with multiple architectures, including{' '}
+ /think_deep (diffusion), /storm, and /fast (just a
+ simple ReAct agent). It is not finished software and can execute ai generated code in your
+ environment... :) At your own risk!
+
+ Browse the code:{' '}
+
+ CLI with multiple architectures:{' '}
+
+ Acknowledgment: Paichun Lin — seminal work on self-balancing agentic AI and text-time + diffusion directly inspired this implementation. Well done! +
+
+ {value}
+
+ ` tags)
@@ -570,13 +628,14 @@ academic fields.
**Unified Sandbox**: Thread-safe, cached results, exponential backoff, redundant providers
**MVP Plan (Phase 1: 2 Tools, Phase 3: +1 Tool):**
+
- **Phase 1**:
1. **Search**: Brave or Serper API, max 10 results
2. **Fetch**: Jina Reader or simple httpx (basic HTML stripping)
-- **Phase 3**:
- 3. **Python Executor**: Jupyter kernel with AST-based safety checks
+- **Phase 3**: 3. **Python Executor**: Jupyter kernel with AST-based safety checks
**Gap Summary:**
+
- ❌ **Scholar Tool**: MVP has no academic search capability
- ❌ **File Parser**: MVP lacks multi-format document parsing
- ❌ **Goal-Specific Summarization**: MVP's fetch is basic; no goal-alignment
@@ -590,6 +649,7 @@ academic fields.
### 4. Storage & State Management
**Alibaba-NLP/DeepResearch:**
+
- **Input**: JSONL (recommended) or JSON array format
- **Trajectory Storage**: JSONL for training data and evaluation
- **Caching**: `diskcache.Cache` with SHA256 keys for file parser
@@ -597,6 +657,7 @@ academic fields.
- **Environment Abstraction**: Three-tier (Prior World, Simulated, Real-world)
**MVP Plan:**
+
- **Phase 1**:
- Simple JSON file store (`FileStore` class)
- Session logs saved to `outputs/sessions/.json`
@@ -605,6 +666,7 @@ academic fields.
- **Phase 3**: Notebook outputs saved as `.ipynb` files
**Gap Summary:**
+
- ❌ **Trajectory Format**: MVP uses simple JSON; no JSONL training format
- ❌ **Result Caching**: MVP has no caching layer (could add easily)
- ❌ **Environment Abstraction**: MVP only interacts with real-world; no simulated environments
@@ -616,6 +678,7 @@ academic fields.
### 5. Memory & Context Management
**Alibaba-NLP/DeepResearch:**
+
- **128K Context Window**: Trained with progressive expansion (32K → 128K)
- **IterResearch Paradigm**:
- Workspace reconstruction each round
@@ -629,6 +692,7 @@ academic fields.
- ReSumTool-30B specialized compression model
**MVP Plan:**
+
- **Token Counting**: Basic `tiktoken` usage
- **Budget Management**:
- Phase 1: 50K token limit with 90% warning
@@ -639,6 +703,7 @@ academic fields.
- **No Structured Memory**: Linear message history until budget exhausted
**Gap Summary:**
+
- ❌ **Sophisticated Compression**: No IterResearch or ReSum paradigm
- ❌ **Workspace Reconstruction**: MVP maintains full message history
- ❌ **Specialized Compression Model**: MVP uses same LLM for compression
@@ -652,6 +717,7 @@ academic fields.
### 6. LLM Integration & Prompting
**Alibaba-NLP/DeepResearch:**
+
- **Custom Model**: Tongyi-DeepResearch-30B-A3B (Apache 2.0 license)
- **Training**: Agentic CPT + SFT + GRPO reinforcement learning
- **Prompting**: "Vanilla setup, no prompt hacks" - native ReAct generation
@@ -660,6 +726,7 @@ academic fields.
- **Summarization**: OpenAI-compatible APIs for Visit tool
**MVP Plan:**
+
- **Phase 1**: OpenRouter/OpenAI/Anthropic API clients
- **Models**: GPT-4o-mini (default), GPT-4, Claude variants
- **Prompting**:
@@ -670,6 +737,7 @@ academic fields.
- **No Custom Training**: Zero model optimization
**Gap Summary:**
+
- ❌ **Custom Model**: MVP has no proprietary model; fully API-dependent
- ❌ **Agentic Training**: No CPT, SFT, or RL training pipeline
- ❌ **Native ReAct**: MVP requires prompt engineering and parsing
@@ -683,6 +751,7 @@ academic fields.
### 7. Tech Stack & Infrastructure
**Alibaba-NLP/DeepResearch:**
+
- **Language**: Python 3.10.0 (strict)
- **ML Framework**: Transformers, likely vLLM, rLLM (custom RL framework)
- **Concurrency**: ThreadPoolExecutor (20 workers), threading.Lock, async RL rollouts
@@ -695,6 +764,7 @@ academic fields.
- **Data**: JSONL processing, knowledge graph libraries
**MVP Plan:**
+
- **Language**: Python 3.11+
- **Package Manager**: `uv` (modern, fast)
- **Framework**: LangGraph (multi-agent orchestration)
@@ -710,6 +780,7 @@ academic fields.
- **No Training Infrastructure**
**Gap Summary:**
+
- ❌ **Training Pipeline**: MVP has zero training capabilities
- ❌ **Custom RL Framework**: No rLLM, GRPO, or AgentFounder/AgentScaler
- ✅ **Modern Package Manager**: `uv` faster than pip/conda
@@ -724,6 +795,7 @@ academic fields.
### 8. Evaluation & Quality
**Alibaba-NLP/DeepResearch:**
+
- **Benchmarks**: 7+ datasets (BrowseComp, Wiki1B, etc.)
- **Model Judges**: Qwen2.5-72B, Gemini-2.0-Flash, GPT-4o, o3-mini
- **Performance**: Comparable or exceeding o3
@@ -731,6 +803,7 @@ academic fields.
- **Metrics**: Task success rate, reasoning quality, tool usage efficiency
**MVP Plan:**
+
- **Automated Verification**:
- `uv sync`, `ruff check`, `mypy src/`, `pytest tests/`
- CLI execution tests
@@ -742,6 +815,7 @@ academic fields.
- **No Formal Benchmarks**: Testing on ad-hoc queries
**Gap Summary:**
+
- ❌ **Benchmark Suite**: MVP has no formal evaluation datasets
- ❌ **Model Judges**: No automated quality assessment
- ❌ **Performance Metrics**: No systematic measurement
@@ -910,10 +984,12 @@ academic fields.
### Main Repository & Papers
**GitHub**:
+
- [Alibaba-NLP/DeepResearch](https://github.com/Alibaba-NLP/DeepResearch) - Main repository
- [Alibaba-NLP/WebAgent](https://github.com/Alibaba-NLP/WebAgent) - WebAgent family
**Technical Papers**:
+
1. [Tongyi DeepResearch Technical Report (arXiv:2510.24701)](https://arxiv.org/abs/2510.24701) - Main paper
2. [AgentFounder: Scaling Agents via Continual Pre-training (arXiv:2509.13310)](https://arxiv.org/abs/2509.13310)
3. [AgentScaler: Environment Scaling for Agentic Intelligence (arXiv:2509.13311)](https://arxiv.org/abs/2509.13311)
diff --git a/thoughts/shared/research/2025-11-17_improving-eda-agent-multi-source-parallel.md b/thoughts/shared/research/2025-11-17_improving-eda-agent-multi-source-parallel.md
index 166473f..3083afb 100644
--- a/thoughts/shared/research/2025-11-17_improving-eda-agent-multi-source-parallel.md
+++ b/thoughts/shared/research/2025-11-17_improving-eda-agent-multi-source-parallel.md
@@ -4,7 +4,7 @@ researcher: Claude (Sonnet 4.5)
git_commit: f02b5c6740b7d3c156f172c0e49106b37563d25a
branch: feat/custom-deep-research
repository: addcommitpush.io
-topic: "Improving EDA Agent: Multi-Data Source Support & Parallel Execution as Sub-Agent"
+topic: 'Improving EDA Agent: Multi-Data Source Support & Parallel Execution as Sub-Agent'
tags: [research, deep-research, eda, multi-agent, data-analysis, parallel-execution, tool-system]
status: complete
last_updated: 2025-11-17
@@ -22,6 +22,7 @@ last_updated_by: Claude
## Research Question
How can the IterativeEDAAgent be transformed into a sub-agent tool that:
+
1. Can be used by the multi-agent system as a tool
2. Supports running multiple EDA agents concurrently (parallel execution)
3. Handles multiple data source types (pickle, csv, excel, parquet, etc.)
@@ -43,22 +44,26 @@ This research provides a comprehensive implementation plan with code references,
### 1. Current EDA Agent Architecture
#### Implementation Location
+
- **Primary**: `deep-research-agent/src/deep_research/agent/iterative_eda.py:19-655`
- **Alternative**: `deep-research-agent/src/deep_research/agent/data_agent.py:16-419` (simpler, older version)
#### Current Workflow (4 Phases)
**Phase 1: Load & Understand** (`iterative_eda.py:49-50`, `iterative_eda.py:95-172`)
+
- Loads CSV into pandas: `df = pd.read_csv(filepath)` (line 98)
- Executes setup code in Jupyter kernel via CodeExecutor
- Extracts schema: shape, columns, dtypes, missing values, head samples
**Phase 2: Identify Target** (`iterative_eda.py:53-55`, `iterative_eda.py:174-212`)
+
- LLM analyzes query + schema to identify target variable
- Uses heuristic fallbacks: "price", "cost", "value" patterns
- Returns target column for analysis focus
**Phase 3: Iterative Exploration** (`iterative_eda.py:58-86`)
+
- Loop up to `max_iterations` (default: 7):
1. **Goal Check** (after 3+ iterations): LLM evaluates if sufficient insights gathered → early stop
2. **Plan**: LLM generates Python exploration code based on insights so far
@@ -67,6 +72,7 @@ This research provides a comprehensive implementation plan with code references,
5. **Store**: Append insight to list, continue loop
**Phase 4: Generate Outputs** (`iterative_eda.py:89-90`, `iterative_eda.py:435-456`)
+
- Generate markdown report summarizing insights
- Build executed Jupyter notebook with:
- Executive summary (LLM-generated from all insights)
@@ -77,16 +83,19 @@ This research provides a comprehensive implementation plan with code references,
#### Current Limitations
**Single File Format** (`iterative_eda.py:98`, `data_agent.py:34`)
+
- Hardcoded `pd.read_csv(filepath)` calls
- No file extension detection or format validation
- Only CSV support (no Excel, Parquet, Pickle, etc.)
**Not a Tool**
+
- EDA agent is directly instantiated by CLI (`cli.py:275`)
- Not registered in tool system
- Cannot be called by other agents (ReactAgent, WorkerAgent)
**No Parallel Support**
+
- Single synchronous execution
- No mechanism to run multiple EDA analyses concurrently
- CodeExecutor creates single kernel instance (blocks concurrent use)
@@ -127,6 +136,7 @@ class Tool(ABC):
```
**Key Pattern**: Tools return `ToolResult` with:
+
- `success`: Boolean execution status
- `content`: String output (formatted for LLM consumption)
- `metadata`: Dict with diagnostic info (query, URL, tokens, etc.)
@@ -174,6 +184,7 @@ class SearchTool(Tool):
```
**Key Aspects**:
+
- Environment-based configuration (API keys)
- Error handling with try/except → returns failure ToolResult
- Helper methods for API calls and formatting
@@ -212,6 +223,7 @@ class ReactAgent:
```
**Key Pattern**:
+
1. Custom tool implements `Tool` base class (domain logic)
2. `@tool` decorated function wraps custom tool (LangChain integration)
3. Decorated function returns string (LangChain requirement)
@@ -257,12 +269,14 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
```
**Key Mechanism**:
+
1. **Dynamic Fan-Out**: `Send` objects created for each task → LangGraph parallelizes execution
2. **State Reducer**: `worker_results: Annotated[list[dict], add]` automatically merges parallel outputs
3. **Isolated Instances**: Each worker gets own agent instance (no shared state)
4. **Result Compression**: Summaries compressed to prevent state bloat
**Graph Structure** (`orchestrator.py:80-101`):
+
```
START → analyze → plan → [workers in parallel] → synthesize → END
↑
@@ -369,11 +383,13 @@ class CodeExecutor:
```
**Limitation for Parallel Execution**:
+
- Single kernel instance per CodeExecutor
- `execute()` is synchronous (blocks)
- No kernel pooling or management
**Needed for Parallel EDA**:
+
- Kernel pool or factory pattern
- Async execution support
- Kernel lifecycle management (auto-cleanup)
@@ -385,22 +401,27 @@ class CodeExecutor:
#### File Format Support Analysis
**Current Implementation** (`iterative_eda.py:98`, `data_agent.py:34`):
+
```python
# Only CSV loading implemented
df = pd.read_csv(filepath)
```
**CLI Validation** (`cli.py:231`):
+
```python
@click.argument("filepath", type=click.Path(exists=True))
```
+
- Only validates file existence, not format
- No extension checking
**Available Dependencies** (`pyproject.toml:19`):
+
- `pandas>=2.2.0` - supports all formats via different readers
**Missing Formats**:
+
- Excel (.xlsx, .xls) - no `read_excel` calls
- Parquet (.parquet) - no `read_parquet` calls
- Pickle (.pkl) - no `read_pickle` calls
@@ -408,6 +429,7 @@ df = pd.read_csv(filepath)
- Other: TSV, HDF5, Feather, etc.
**Required Dependencies** (need to add to pyproject.toml):
+
```toml
dependencies = [
# ... existing ...
@@ -496,6 +518,7 @@ class DataLoader:
```
**Usage in IterativeEDAAgent**:
+
```python
# Replace line 98 in iterative_eda.py
from ..tools.data_loader import DataLoader
@@ -659,6 +682,7 @@ self.tools = [search, fetch, eda] # Add eda to list
**Result**: ReactAgent can now perform EDA during research workflows!
Example usage:
+
```bash
uv run research research "Analyze customer_churn.csv and identify key churn drivers"
@@ -677,6 +701,7 @@ uv run research research "Analyze customer_churn.csv and identify key churn driv
#### Problem: Single Kernel Limitation
Current CodeExecutor creates one kernel per agent instance:
+
- `IterativeEDAAgent.__init__()` → `self.executor = CodeExecutor()` → starts single kernel
- Multiple agents → multiple kernels (OK for parallelization!)
@@ -685,6 +710,7 @@ Current CodeExecutor creates one kernel per agent instance:
#### Step 1: Verify Kernel Isolation
Each EDA agent gets own executor:
+
```python
# In EDATool.execute()
agent = IterativeEDAAgent(model=self.model) # Line 46
@@ -692,6 +718,7 @@ agent = IterativeEDAAgent(model=self.model) # Line 46
```
**Test**: Spawn 2 EDA agents with same dataset:
+
```python
# Both run concurrently without interference
task1 = eda_tool.execute(filepath="data.csv", query="analyze sales trends")
@@ -743,6 +770,7 @@ Return JSON array of tasks.
```
**Result**: Orchestrator can now spawn parallel mix of:
+
- Web research workers (using search/fetch tools)
- Data analysis workers (using eda tool)
@@ -753,6 +781,7 @@ Return JSON array of tasks.
#### Implementation Plan
**Step 1**: Add DataLoader to project
+
- Create `src/deep_research/tools/data_loader.py` (code shown above in section 5)
- Add dependencies to `pyproject.toml`:
```toml
@@ -904,6 +933,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
- [ ] Update README.md with examples for each format
**Success Criteria**:
+
- [ ] `uv run research eda data.csv "query"` works
- [ ] `uv run research eda data.xlsx "query"` works
- [ ] `uv run research eda data.parquet "query"` works
@@ -924,6 +954,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
- [ ] Test integration with ReactAgent
**Success Criteria**:
+
- [ ] ReactAgent can call eda tool during research
- [ ] Tool returns formatted insights to agent
- [ ] Agent can reason about data analysis results
@@ -942,6 +973,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
- Test result merging
**Success Criteria**:
+
- [ ] Multiple EDA analyses can run concurrently without conflicts
- [ ] No kernel crashes or interference
- [ ] Results from parallel executions are correctly merged
@@ -961,6 +993,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
- [ ] Performance optimization: cache data loading, kernel reuse
**Success Criteria**:
+
- [ ] Query like "Analyze sales.csv and compare with industry" completes
- [ ] Final report includes both data insights and web research
- [ ] Notebook + markdown report both generated
@@ -979,6 +1012,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
- [ ] Security review: ensure AST checks cover all formats
**Success Criteria**:
+
- [ ] Documentation has clear examples for all use cases
- [ ] New users can run examples without errors
- [ ] Performance meets targets (<3 min for combined queries)
@@ -1016,12 +1050,14 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
### Relevant Planning Documents
**Deep Research Agent MVP Plan** (`thoughts/shared/plans/deep-research-agent-python-mvp.md`)
+
- Phase 3 (Week 3) details EDA implementation with notebook generation
- 7-act narrative structure for notebooks
- Jupyter kernel integration patterns
- Code executor safety checks
**Architecture Research** (`thoughts/shared/research/2025-11-15_deep-research-agent-architecture.md`)
+
- ReAct framework implementation
- LangGraph state management patterns
- Tool suite design
@@ -1031,18 +1067,21 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
### Design Decisions
**Why Not External Sandboxing** (from architecture doc):
+
- Local Jupyter kernel for privacy
- No API costs (E2B/Modal avoided)
- Full control over execution environment
- Sufficient for MVP with AST safety checks
**Why LangGraph Over Custom Orchestration**:
+
- Built-in state management and checkpointing
- Send API for dynamic parallelization
- Conditional routing without complex control flow
- State reducers handle result merging automatically
**Why Tool Base Pattern**:
+
- Consistent interface across all tools
- Easy to test in isolation
- Metadata tracking for observability
@@ -1059,6 +1098,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
**Current**: Each EDA agent creates new kernel (isolated but resource-heavy)
**Options**:
+
- **A. Keep current approach**: Simple, isolated, but uses more memory
- **B. Kernel pool**: Reuse kernels across analyses, add cleanup between uses
- **C. Hybrid**: Pool for sequential, isolated for parallel
@@ -1072,6 +1112,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
**Current**: Uses default pandas options
**Options**:
+
- **A. Hardcoded defaults**: Simple, works for 90% of cases
- **B. Kwargs passthrough**: `DataLoader.load(path, **pandas_kwargs)`
- **C. Config file**: `.edaconfig.json` with per-file settings
@@ -1085,6 +1126,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
**Current**: Executed at end of IterativeEDAAgent.analyze()
**Options**:
+
- **A. Always execute**: Validates code works, adds outputs
- **B. Optional flag**: `--execute/--no-execute`
- **C. Lazy execution**: Generate notebook, let user execute
@@ -1098,6 +1140,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
**Current**: WorkerAgent compresses to 2000 tokens
**Options**:
+
- **A. Compress EDA insights**: Summary only (loses detail)
- **B. Full insights**: Better context, uses more tokens
- **C. Hybrid**: Full insights + notebook path reference
@@ -1162,12 +1205,14 @@ The IterativeEDAAgent can be successfully transformed into a multi-agent tool wi
4. **Incremental delivery** - each phase adds standalone value
**Key Insights**:
+
- **Parallelization already works** - each agent gets isolated kernel
- **Tool pattern is proven** - SearchTool and FetchTool demonstrate the pattern
- **Orchestrator is ready** - Send API generalizes to any worker type (web or data)
- **Multi-format is straightforward** - DataLoader factory pattern handles all pandas formats
**Biggest Wins**:
+
- **Combined insights**: Web research + data analysis in single query
- **Parallel execution**: 3-5x faster with multiple concurrent analyses
- **Format flexibility**: CSV, Excel, Parquet, Pickle all supported
diff --git a/thoughts/shared/research/2025-11-20_obsidian-iterative-research-architecture.md b/thoughts/shared/research/2025-11-20_obsidian-iterative-research-architecture.md
index e186a35..ba25184 100644
--- a/thoughts/shared/research/2025-11-20_obsidian-iterative-research-architecture.md
+++ b/thoughts/shared/research/2025-11-20_obsidian-iterative-research-architecture.md
@@ -4,7 +4,7 @@ researcher: Emil Wareus
git_commit: c032b77aec5b215d766dad45f6511c629f728e73
branch: feat/custom-deep-research
repository: addcommitpush.io
-topic: "Obsidian-Based Iterative Research System Architecture"
+topic: 'Obsidian-Based Iterative Research System Architecture'
tags: [research, deep-research-agent, obsidian, knowledge-graph, multi-agent, langgraph]
status: complete
last_updated: 2025-11-20
@@ -22,6 +22,7 @@ last_updated_by: Emil Wareus
## Research Question
How can we transform the deep-research multi-agent system into an iterative, knowledge-graph-driven research platform using Obsidian as the persistence layer, enabling:
+
1. Full traceable session storage with complete worker context
2. Worker-specific research expansion via CLI
3. Report recompilation with custom synthesis instructions
@@ -33,6 +34,7 @@ How can we transform the deep-research multi-agent system into an iterative, kno
Through comprehensive codebase analysis and external research into Obsidian's knowledge management capabilities, we discovered a viable architectural pattern for transforming the existing multi-agent research system into an iterative research platform. The current system loses critical context during worker result compression (orchestrator.py:352), limiting the ability to expand or reanalyze research. By implementing full context capture and Obsidian-based storage, we can enable iterative research workflows while maintaining backwards compatibility.
**Key Findings**:
+
- Current architecture compresses worker outputs from full context (10-50KB) to 2000 tokens (~8KB), losing 80-90% of research detail
- Obsidian's markdown + YAML frontmatter + wikilinks provide natural structure for research sessions as knowledge graphs
- LangGraph's state machine supports session tracking with minimal modifications
@@ -87,6 +89,7 @@ return {
```
**What's Lost**:
+
- Full worker reasoning steps (ReAct thought-action-observation loops)
- All individual tool calls and their complete results
- Complete search queries and fetched page contents
@@ -94,6 +97,7 @@ return {
- Intermediate insights before compression
**Impact**: 80-90% of worker research context is discarded, making it impossible to:
+
- Accurately expand on specific worker findings
- Debug why certain conclusions were reached
- Recompile reports with different analytical angles
@@ -115,6 +119,7 @@ def save_session(self, session_id: str, data: dict[str, Any]) -> None:
```
**Limitations Discovered**:
+
1. Only saves compressed summaries (not full worker context)
2. Single JSON file per session (no versioning)
3. No graph structure (can't link insights across sessions)
@@ -132,7 +137,7 @@ Research into Obsidian documentation revealed that YAML frontmatter (also called
type: research_session
session_id: session_abc123
version: 1
-query: "What are the latest trends in AI research?"
+query: 'What are the latest trends in AI research?'
status: completed
created_at: 2025-01-20T14:25:00Z
updated_at: 2025-01-20T14:45:00Z
@@ -148,6 +153,7 @@ tags:
```
**Benefits**:
+
- Queryable via Dataview plugin
- Native Obsidian UI display
- Git-friendly version control
@@ -160,14 +166,17 @@ Obsidian's `[[note name]]` syntax creates bidirectional links automatically:
```markdown
**Session**: [[session_abc123_v1]]
**Workers**:
+
- [[task_1_worker|Worker 1]]: Foundation models research
- [[task_2_worker|Worker 2]]: Multimodal AI systems
**Key Insights**:
+
- [[insight_20250120_143052|Foundation models reaching 10T parameters]]
```
**Graph View Benefits**:
+
- Visual exploration of research connections
- Discover non-obvious relationships
- Navigate between session → worker → insight → source
@@ -185,6 +194,7 @@ SORT created_at ASC
```
**Use Cases**:
+
- Aggregate worker costs across sessions
- Find all insights related to a topic
- Generate session summaries dynamically
@@ -221,6 +231,7 @@ outputs/obsidian/
```
**Rationale**:
+
- **sessions/**: Central MOCs that link to all related entities
- **workers/**: Grouped by session for organizational clarity
- **insights/**: Flat structure enables cross-session linking
@@ -306,6 +317,7 @@ class ResearchSession:
```
**Versioning Pattern**: `session_{hash}_v{N}`
+
- Same base query → same session ID
- Expansions/recompilations increment version
- Never delete previous versions (audit trail)
@@ -316,12 +328,12 @@ class ResearchSession:
**File**: `outputs/obsidian/sessions/session_abc123_v1.md`
-```markdown
+````markdown
---
type: research_session
session_id: session_abc123
version: 1
-query: "What are the latest trends in AI research?"
+query: 'What are the latest trends in AI research?'
status: completed
created_at: 2025-01-20T14:25:00Z
updated_at: 2025-01-20T14:45:00Z
@@ -339,6 +351,7 @@ tags:
# Research Session: Latest AI Research Trends
## Query
+
> What are the latest trends in AI research?
## Research Plan
@@ -346,6 +359,7 @@ tags:
Complexity: 0.75 (5 workers)
### Workers
+
1. [[task_1_worker|Worker 1]]: Foundation models and scaling laws
2. [[task_2_worker|Worker 2]]: Multimodal AI systems
3. [[task_3_worker|Worker 3]]: AI safety and alignment research
@@ -367,6 +381,7 @@ Complexity: 0.75 (5 workers)
Total: 45 sources across all workers
### By Worker
+
- Worker 1: 12 sources
- Worker 2: 9 sources
- Worker 3: 8 sources
@@ -380,7 +395,9 @@ LIST
FROM [[session_abc123_v1]]
WHERE type = "worker" OR type = "insight"
```
-```
+````
+
+````
**Purpose**: Central navigation hub linking to all session components
@@ -441,7 +458,7 @@ tags:
*This is what gets passed to the synthesis step:*
Foundation models in 2024-2025 show continued scaling trends with models reaching 10T parameters through mixture-of-experts architectures...
-```
+````
**Critical Feature**: Full ReAct trace preserved for expansion and debugging
@@ -454,8 +471,8 @@ Foundation models in 2024-2025 show continued scaling trends with models reachin
type: insight
insight_id: insight_20250120_143052
created_at: 2025-01-20T14:30:52Z
-source_session: "[[session_abc123_v1]]"
-source_worker: "[[task_1_worker]]"
+source_session: '[[session_abc123_v1]]'
+source_worker: '[[task_1_worker]]'
tags:
- scaling-laws
- foundation-models
@@ -508,6 +525,7 @@ def expand(session: str, worker: str, prompt: str, model: str | None, verbose: b
```
**Workflow**:
+
1. Load session from Obsidian vault
2. Extract target worker's full context
3. Build expansion query incorporating previous findings
@@ -515,6 +533,7 @@ def expand(session: str, worker: str, prompt: str, model: str | None, verbose: b
5. Save as new version (v2, v3, etc.)
**Example Usage**:
+
```bash
research expand --session=session_abc123 --worker=task_1 "Research GPU costs in detail"
```
@@ -531,6 +550,7 @@ def recompile_report(session: str, instructions: str | None, model: str | None)
```
**Workflow**:
+
1. Load session from Obsidian
2. Extract ALL worker full contexts (not compressed summaries)
3. Generate new synthesis with custom instructions
@@ -538,6 +558,7 @@ def recompile_report(session: str, instructions: str | None, model: str | None)
5. Update session MOC to reference new report
**Example Usage**:
+
```bash
research recompile-report --session=session_abc123 "Focus on cost-benefit analysis"
```
@@ -549,6 +570,7 @@ research recompile-report --session=session_abc123 "Focus on cost-benefit analys
**Location**: `src/deep_research/obsidian/writer.py` (new module)
**Core Responsibilities**:
+
1. Create vault directory structure
2. Write session MOCs with frontmatter and wikilinks
3. Write worker notes with full ReAct traces
@@ -558,6 +580,7 @@ research recompile-report --session=session_abc123 "Focus on cost-benefit analys
7. Maintain bidirectional link integrity
**Key Methods**:
+
```python
class ObsidianWriter:
def write_session(self, session: ResearchSession) -> Path:
@@ -584,6 +607,7 @@ class ObsidianWriter:
**Location**: `src/deep_research/agent/orchestrator.py` (modifications)
**Required Changes**:
+
1. Add `save_to_obsidian` flag to `__init__()`
2. Initialize `ObsidianWriter` instance
3. Create `ResearchSession` tracking at start of `research()`
@@ -592,6 +616,7 @@ class ObsidianWriter:
6. Add session ID and version to result metadata
**Critical Modification** (orchestrator.py:320-393):
+
```python
async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
"""Execute worker - CAPTURE FULL CONTEXT."""
@@ -627,6 +652,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
#### Why Obsidian Over Database?
**Advantages Discovered**:
+
- **Human-readable**: Direct markdown editing and reading
- **Built-in graph view**: Visual knowledge exploration (no custom visualization needed)
- **Dataview plugin**: SQL-like queries without database setup
@@ -636,6 +662,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
- **Offline-first**: Works without network connection
**Trade-offs**:
+
- File I/O slower than database for large-scale queries (10,000+ notes)
- No ACID guarantees (but single-user research doesn't need them)
- Manual index management (Dataview provides virtual indexes)
@@ -645,6 +672,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
#### Why Store Full Context (Not Compressed)?
**Rationale**:
+
1. **Expansion accuracy**: LLM needs full context to continue research coherently
2. **Recompilation quality**: Different synthesis angles require access to all evidence
3. **Debugging capability**: Understand exactly what the worker saw and did
@@ -652,6 +680,7 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
5. **Research evolution**: Build knowledge over time, not just final outputs
**Cost Analysis**:
+
- Compressed: ~50KB per worker
- Full context: ~500KB - 2MB per worker (10-40x larger)
- Storage cost: ~$0.023/GB/month (S3 Standard)
@@ -664,12 +693,14 @@ async def _worker_execution(self, state: dict[str, Any]) -> dict[str, Any]:
**Pattern**: `session_{hash}_v{N}`
**How It Works**:
+
- Initial query "What are AI trends?" → `session_abc123_v1`
- Expansion of worker 1 → `session_abc123_v2` (same base ID)
- Recompilation → `session_abc123_v3`
- Different query "What is Python?" → `session_def456_v1` (new base ID)
**Alternative Considered**: UUID per execution
+
- **Rejected**: Loses connection between related research sessions
- No way to know v2 expanded v1
- Graph becomes disconnected forest instead of connected graph
@@ -727,9 +758,11 @@ class ReActIteration:
The key architectural insight: **Compress for synthesis, never for storage.**
Current flow:
+
1. Worker generates full output → compress → store compressed → synthesize
Proposed flow:
+
1. Worker generates full output → store full → compress copy → synthesize
This adds minimal overhead (one extra data structure) but preserves all context.
@@ -744,11 +777,13 @@ The proposed architecture maintains full backwards compatibility:
- `research recompile-report` - New command, requires Obsidian
Users opt-in via:
+
```bash
research multi "query" --save-obsidian
```
Or environment variable:
+
```bash
export DEEP_RESEARCH_OBSIDIAN=true
```
@@ -793,6 +828,7 @@ This research builds on previous work documented in:
### Similar Systems
**Comparison with Obsidian Research Plugins**:
+
- **Research Assistant** plugin - Manual note-taking focused
- **Zotero Integration** plugin - Academic paper management
- **Smart Connections** plugin - Embedding-based search
@@ -825,6 +861,7 @@ Based on the research, we identified measurable success criteria:
**Question**: Should insights be auto-extracted from worker outputs using LLM, or manually curated?
**Options**:
+
- **Auto-extraction**: Use LLM to identify key insights from worker output
- Pro: Automated, consistent, scales
- Con: May miss nuance, requires prompt engineering, adds cost
@@ -840,6 +877,7 @@ Based on the research, we identified measurable success criteria:
**Question**: Should we link insights between sessions (cross-session graph)?
**Options**:
+
- **Within-session only**: Each session is isolated graph
- Pro: Simpler, clearer boundaries
- Con: Misses connections across research topics
@@ -855,6 +893,7 @@ Based on the research, we identified measurable success criteria:
**Question**: How to handle same URL fetched by multiple workers?
**Options**:
+
- **No deduplication**: Store separately per worker
- Pro: Simple, preserves exact context
- Con: Wastes storage, fragments references
@@ -870,6 +909,7 @@ Based on the research, we identified measurable success criteria:
**Question**: Should we require Dataview plugin for full functionality?
**Options**:
+
- **Required**: Vault assumes Dataview installed
- Pro: Rich queries, better UX
- Con: Adds setup friction
@@ -885,10 +925,12 @@ Based on the research, we identified measurable success criteria:
Based on the research findings, a phased implementation approach is recommended:
### Phase 1: Data Capture (Foundation)
+
**Duration**: 1 week
**Focus**: Preserve full context without changing synthesis
**Tasks**:
+
1. Create enhanced data structures (`WorkerFullContext`, `ResearchSession`, `ToolCall`, `ReActIteration`)
2. Modify `WorkerAgent` to track ReAct iterations
3. Modify `LeadResearcher._worker_execution()` to build full context
@@ -897,10 +939,12 @@ Based on the research findings, a phased implementation approach is recommended:
**Validation**: Workers complete successfully, full context captured in memory
### Phase 2: Obsidian Writer (Storage)
+
**Duration**: 1 week
**Focus**: Write sessions to Obsidian vault
**Tasks**:
+
1. Create `obsidian/` module
2. Implement `ObsidianWriter` class
3. Implement note generation (session MOC, workers, sources, reports)
@@ -910,10 +954,12 @@ Based on the research findings, a phased implementation approach is recommended:
**Validation**: Session writes to Obsidian, graph view shows connections
### Phase 3: CLI Commands (Iteration)
+
**Duration**: 1 week
**Focus**: Enable expansion and recompilation
**Tasks**:
+
1. Implement `research expand` command
2. Implement `research recompile-report` command
3. Add session loading from Obsidian
@@ -923,10 +969,12 @@ Based on the research findings, a phased implementation approach is recommended:
**Validation**: Can expand worker research, recompile with new instructions
### Phase 4: Testing & Documentation (Polish)
+
**Duration**: 1 week
**Focus**: Ensure reliability and usability
**Tasks**:
+
1. Test full workflow with multiple sessions
2. Performance testing with 10+ workers
3. Write user documentation
@@ -950,6 +998,7 @@ The research demonstrates that transforming the deep-research multi-agent system
5. **Implementation Feasibility**: 4-week phased approach leverages existing patterns (CLI, state management, HTTP pooling)
**Critical Success Factors**:
+
- Full context capture must not break existing synthesis pipeline
- Obsidian vault structure must be intuitive for human exploration
- Version management must clearly show research lineage
@@ -960,6 +1009,7 @@ The research demonstrates that transforming the deep-research multi-agent system
## References
### Internal Codebase
+
- `deep-research-agent/src/deep_research/agent/orchestrator.py` - Multi-agent orchestration
- `deep-research-agent/src/deep_research/agent/worker.py` - Worker agent implementation
- `deep-research-agent/src/deep_research/agent/state.py` - LangGraph state definitions
@@ -967,12 +1017,14 @@ The research demonstrates that transforming the deep-research multi-agent system
- `deep-research-agent/src/deep_research/cli.py` - CLI command patterns
### External Documentation
+
- **LangGraph**: https://langchain-ai.github.io/langgraph/ - State machine and parallel execution patterns
- **Obsidian Format**: https://help.obsidian.md/ - Markdown, frontmatter, wikilinks specification
- **Dataview Plugin**: https://blacksmithgu.github.io/obsidian-dataview/ - Query language documentation
- **Zettelkasten Method**: https://zettelkasten.de/posts/overview/ - Knowledge management principles
### Research Papers
+
- Alibaba DeepResearch (2024) - Multi-agent research system architecture
- LangGraph Documentation - Dynamic parallel execution with Send API
- Obsidian Community Best Practices - MOC patterns and vault organization
diff --git a/thoughts/shared/research/2025-11-21_interactive-research-cli-architecture.md b/thoughts/shared/research/2025-11-21_interactive-research-cli-architecture.md
index a7d32c5..076e069 100644
--- a/thoughts/shared/research/2025-11-21_interactive-research-cli-architecture.md
+++ b/thoughts/shared/research/2025-11-21_interactive-research-cli-architecture.md
@@ -4,8 +4,18 @@ researcher: Emil Wareus
git_commit: 6a27b87a0b5c98277f9e2c7f1fb3348e5edadc17
branch: feat/custom-deep-research
repository: addcommitpush.io
-topic: "Interactive Research CLI Mode Architecture - REPL for Deep Research Agent"
-tags: [research, deep-research-agent, cli, repl, interactive-mode, session-management, prompt-toolkit, user-experience]
+topic: 'Interactive Research CLI Mode Architecture - REPL for Deep Research Agent'
+tags:
+ [
+ research,
+ deep-research-agent,
+ cli,
+ repl,
+ interactive-mode,
+ session-management,
+ prompt-toolkit,
+ user-experience,
+ ]
status: complete
last_updated: 2025-11-21
last_updated_by: Emil Wareus
@@ -34,6 +44,7 @@ Through comprehensive parallel research across the codebase and external resourc
- ✅ Rich terminal output with progress indicators
**What's Missing**:
+
- ❌ REPL/interactive prompt loop
- ❌ In-memory active session state manager
- ❌ Natural language command parser
@@ -82,6 +93,7 @@ def cli() -> None:
```
**Existing Commands**:
+
1. **`research`** (`cli.py:74-159`) - Single-agent research
2. **`multi`** (`cli.py:178-239`) - Multi-agent parallel research
3. **`expand`** (`cli.py:242-355`) - Expand specific worker from session
@@ -90,6 +102,7 @@ def cli() -> None:
6. **`list-workers`** (`cli.py:552-650`) - Show workers for specific session
**Async Execution Pattern** (used by all commands):
+
```python
def command_name(...):
async def _async_implementation():
@@ -135,6 +148,7 @@ class WorkerFullContext:
```
**Critical Feature**: `WorkerFullContext` stores **both** full output and compressed summary. This dual storage enables:
+
- Full context for human review and continuation
- Compressed summaries for LLM synthesis
- Complete audit trail of tool usage
@@ -177,6 +191,7 @@ class ResearchSession:
#### Orchestrator Execution Flow (`orchestrator.py:69-136`)
**Session Initialization** (`orchestrator.py:72-85`):
+
```python
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
session_hash = abs(hash(query)) % 1000000
@@ -195,11 +210,13 @@ self.session = ResearchSession(
```
**LangGraph Workflow**:
+
```
START → analyze → plan → [worker₁, worker₂, ...] → synthesize → END
```
**Worker Spawning** (`orchestrator.py:378-383`):
+
```python
def _spawn_workers(self, state: ResearchState) -> list[Send]:
sends = [Send("worker", {"task": task}) for task in state["sub_tasks"]]
@@ -209,6 +226,7 @@ def _spawn_workers(self, state: ResearchState) -> list[Send]:
LangGraph's `Send` API enables **dynamic parallel worker execution** - workers run concurrently and populate results as they complete.
**Context Capture** (`orchestrator.py:419-445`):
+
```python
# After worker completes
if self.session and hasattr(worker, "full_context") and worker.full_context:
@@ -241,12 +259,14 @@ if self.session and hasattr(worker, "full_context") and worker.full_context:
#### Progress Display (`utils/live_progress.py:24-201`)
**LiveProgress System**:
+
- Uses Rich library's `Live` display with 4Hz refresh
- Thread-safe with `threading.RLock()`
- Protocol-based design (`ProgressCallback` protocol)
- Displays worker table with real-time status updates
**Example Output**:
+
```
🔍 Multi-agent research: What are Swedish housing prices?
@@ -273,6 +293,7 @@ Recent Activity
#### Obsidian Vault Structure
**Directory Layout**:
+
```
outputs/obsidian/
├── session_20250120_142530_abc123/
@@ -291,12 +312,13 @@ outputs/obsidian/
```
**Session MOC Frontmatter** (`writer.py:92-106`):
+
```yaml
---
type: research_session
session_id: session_20250120_142530_abc123
version: 1
-query: "What are Swedish housing prices?"
+query: 'What are Swedish housing prices?'
status: completed
created_at: 2025-01-20T14:25:00Z
updated_at: 2025-01-20T14:45:00Z
@@ -304,7 +326,7 @@ model: anthropic/claude-3.5-sonnet
complexity: 0.75
num_workers: 3
total_cost: 0.0234
-parent_session: session_20250120_142530_abc123_v1 # For v2+
+parent_session: session_20250120_142530_abc123_v1 # For v2+
tags: [sweden, housing, economics]
---
```
@@ -314,6 +336,7 @@ tags: [sweden, housing, economics]
#### Session Loading (`loader.py:19-65`)
**Load Flow**:
+
1. Locate session file at `{vault_path}/{session_id}/session.md`
2. Parse YAML frontmatter and markdown body
3. Reconstruct `ResearchSession` object from frontmatter
@@ -323,6 +346,7 @@ tags: [sweden, housing, economics]
7. Aggregate unique sources across all workers
**Example Usage**:
+
```python
loader = SessionLoader(vault_path="outputs/obsidian")
session = loader.load_session("session_20250120_142530_abc123", version=1)
@@ -337,6 +361,7 @@ print(session.workers[0].final_output) # Full uncompressed output
#### Worker Full Context Preservation (`writer.py:141-183`)
**What Gets Stored**:
+
- **ReAct iterations**: Full thought-action-observation loops
- **Tool calls**: All invocations with arguments, results, duration
- **Final output**: Complete uncompressed worker output
@@ -344,12 +369,13 @@ print(session.workers[0].final_output) # Full uncompressed output
- **Sources**: All accessed URLs
**Worker Note Template** (`templates.py:85-144`):
+
```markdown
---
type: worker
session_id: session_abc123
task_id: task_1
-objective: "Research Swedish housing prices"
+objective: 'Research Swedish housing prices'
status: completed
tool_calls: 15
cost: 0.0245
@@ -360,19 +386,23 @@ cost: 0.0245
## Research Process (ReAct Loop)
### Iteration 1
+
**Thought**: I need to find recent data on Swedish housing prices
**Actions**:
+
- `search(query="swedish housing prices 2024")`
- Success: true
- Duration: 2.3s
-**Observation**: Found 10 results including SCB statistics
+ **Observation**: Found 10 results including SCB statistics
[... all iterations preserved ...]
## Final Output
+
[Full uncompressed output - 5000+ words]
## Compressed Summary
+
[2000-token summary for synthesis]
```
@@ -381,6 +411,7 @@ cost: 0.0245
#### Session Versioning Pattern (`cli.py:332-338`)
**Expand Command Creates v2**:
+
```python
# Load parent session
parent_session = loader.load_session(session_id, version)
@@ -399,6 +430,7 @@ result = await orchestrator.research(expansion_query)
```
**Versioning Strategy**:
+
- **Same session_id** across versions (e.g., `session_20250120_142530_abc123`)
- **Incremented version** (1, 2, 3...)
- **Parent reference** format: `{session_id}_v{version}`
@@ -416,6 +448,7 @@ result = await orchestrator.research(expansion_query)
**Official Documentation**: https://python-prompt-toolkit.readthedocs.io/en/master/
**Core Features**:
+
- Native asyncio support (version 3.0+)
- Built-in history management via `PromptSession`
- Syntax highlighting using Pygments lexers
@@ -424,6 +457,7 @@ result = await orchestrator.research(expansion_query)
- Multi-line editing support
**Async REPL Pattern**:
+
```python
from prompt_toolkit.patch_stdout import patch_stdout
from prompt_toolkit.shortcuts import PromptSession
@@ -439,6 +473,7 @@ async def interactive_shell():
```
**Auto-completion Example**:
+
```python
from prompt_toolkit.completion import NestedCompleter
@@ -462,12 +497,14 @@ session = PromptSession(completer=completer)
```
**Key Features for Interactive Research CLI**:
+
- `patch_stdout()` context manager prevents async output from corrupting prompt
- `prompt_async()` method integrates with asyncio event loop
- `ThreadedCompleter` wrapper for expensive completion operations
- Command history persisted to `~/.research_history`
**Production Examples**:
+
- **IPython** - Uses prompt_toolkit for terminal REPL
- **ptpython** - Enhanced Python REPL built on prompt_toolkit
- **AWS CLI tools** - Interactive mode implementations
@@ -477,6 +514,7 @@ session = PromptSession(completer=completer)
**Repository**: https://github.com/python-cmd2/cmd2
**Comparison**:
+
- ✅ Out-of-the-box tab completion, history, scripting
- ✅ Minimal development effort
- ❌ Limited async support (GitHub Issue #764)
@@ -487,6 +525,7 @@ session = PromptSession(completer=completer)
#### Command Parsing Patterns
**shlex + argparse Integration**:
+
```python
import shlex
import argparse
@@ -516,12 +555,14 @@ except argparse.ArgumentError as e:
```
**Natural Language Patterns**:
+
- Tokenize → intent classification → entity extraction → argparse
- Support aliases: `start`/`new`/`begin`, `continue`/`resume`, `exit`/`quit`
#### Async State Management
**aiomonitor Pattern** (https://aiomonitor.aio-libs.org/):
+
```python
import aiomonitor
import asyncio
@@ -535,6 +576,7 @@ with aiomonitor.start_monitor(loop, locals=locals):
```
**State Injection Strategy**:
+
- Maintain `active_session: ResearchSession | None` in REPL context
- Inject into REPL namespace for debugging
- Update on session start/switch/complete
@@ -542,6 +584,7 @@ with aiomonitor.start_monitor(loop, locals=locals):
#### Progress Display During Long Operations
**Rich Progress Integration**:
+
```python
from rich.progress import Progress
from rich.console import Console
@@ -559,6 +602,7 @@ async def start_research(query: str):
```
**tqdm with asyncio**:
+
```python
import tqdm.asyncio
@@ -573,12 +617,14 @@ await tqdm.asyncio.gather(*worker_tasks, desc="Workers")
#### Component Overview
**New Components** (to be implemented):
+
1. **REPL Shell** - `prompt_toolkit` based interactive loop
2. **SessionManager** - In-memory active session tracking
3. **CommandParser** - Natural language → action mapping
4. **ContextManager** - Prepare continuation context from previous sessions
**Existing Components** (reuse):
+
- `LeadResearcher` (orchestrator) - Research execution
- `ObsidianWriter` - Session persistence
- `SessionLoader` - Session loading
@@ -587,12 +633,14 @@ await tqdm.asyncio.gather(*worker_tasks, desc="Workers")
#### SessionManager Class (New)
**Responsibilities**:
+
- Track active session in memory
- Session lifecycle (start/pause/resume/stop)
- Sync with ObsidianWriter/Loader
- Context preparation for continuations
**Interface**:
+
```python
class SessionManager:
def __init__(self, vault_path: str = "outputs/obsidian"):
@@ -642,11 +690,13 @@ class SessionManager:
#### CommandParser Class (New)
**Responsibilities**:
+
- Parse user input into commands
- Support aliases and natural language
- Extract arguments and validate
**Interface**:
+
```python
class CommandParser:
def __init__(self):
@@ -712,6 +762,7 @@ class CommandParser:
#### Interactive REPL Loop (New)
**Main Loop**:
+
```python
async def interactive_repl():
"""Main interactive REPL for research CLI."""
@@ -796,6 +847,7 @@ async def interactive_repl():
#### Command Implementations
**Start Command**:
+
```python
async def cmd_start(
manager: SessionManager,
@@ -838,6 +890,7 @@ async def cmd_start(
```
**Continue Command**:
+
```python
async def cmd_continue(
manager: SessionManager,
@@ -880,6 +933,7 @@ async def cmd_continue(
```
**Status Command**:
+
```python
async def cmd_status(manager: SessionManager, console: Console) -> None:
"""Show active session status."""
@@ -915,6 +969,7 @@ async def cmd_status(manager: SessionManager, console: Console) -> None:
```
**List Sessions Command**:
+
```python
async def cmd_list(
manager: SessionManager,
@@ -979,6 +1034,7 @@ async def cmd_list(
#### Context Preparation for Continuation
**Compression Strategy**:
+
```python
def _build_continuation_context(session: ResearchSession) -> str:
"""Build compressed context from previous session for continuation.
@@ -1009,6 +1065,7 @@ def _build_continuation_context(session: ResearchSession) -> str:
```
**Alternative: Include Full Worker Context**:
+
```python
def _build_full_continuation_context(session: ResearchSession, worker_id: str) -> str:
"""Include full worker output for deep continuation."""
@@ -1041,6 +1098,7 @@ SOURCES:
**Goal**: Basic REPL loop with command parsing
**Tasks**:
+
1. Add `prompt_toolkit` dependency to `pyproject.toml`
2. Create `src/deep_research/repl/` module
3. Implement `CommandParser` class
@@ -1051,6 +1109,7 @@ SOURCES:
**Deliverable**: Interactive shell that accepts commands but doesn't execute research yet
**Validation**:
+
```bash
$ deep-research interactive
research> start What is quantum computing?
@@ -1063,6 +1122,7 @@ research> exit
**Goal**: In-memory session tracking and lifecycle
**Tasks**:
+
1. Implement `SessionManager` class
2. Integrate with `ObsidianWriter` and `SessionLoader`
3. Implement `start` command with full research execution
@@ -1073,6 +1133,7 @@ research> exit
**Deliverable**: Can start research sessions and track active session
**Validation**:
+
```bash
research> start What is quantum computing?
[... research executes with live progress ...]
@@ -1091,6 +1152,7 @@ Cost: $0.45
**Goal**: Enable continuation and expansion
**Tasks**:
+
1. Implement `continue` command
2. Implement context compression from previous session
3. Implement `expand` command for worker-specific expansion
@@ -1100,6 +1162,7 @@ Cost: $0.45
**Deliverable**: Can continue previous sessions with new queries
**Validation**:
+
```bash
research> continue How does quantum computing relate to AI?
[Loads v1 context, creates v2, executes research]
@@ -1116,6 +1179,7 @@ research> expand --worker task_1 "Research specific quantum algorithms"
**Goal**: Track and switch between multiple sessions
**Tasks**:
+
1. Implement session stack in `SessionManager`
2. Implement `switch` command
3. Implement `reset` command
@@ -1126,6 +1190,7 @@ research> expand --worker task_1 "Research specific quantum algorithms"
**Deliverable**: Can manage multiple concurrent sessions
**Validation**:
+
```bash
research> list sessions
Session ID | Version | Query
@@ -1144,6 +1209,7 @@ research> continue Analyze price trends in Malmö
**Goal**: Production-ready UX
**Tasks**:
+
1. Implement rich auto-completion with context-aware suggestions
2. Add cost estimation before starting research
3. Implement `export` command (to notebook, PDF)
@@ -1155,6 +1221,7 @@ research> continue Analyze price trends in Malmö
**Deliverable**: Polished, production-ready interactive CLI
**Validation**:
+
- Auto-completion suggests session IDs when typing `switch`
- Help text shows examples for each command
- Keyboard shortcuts work as expected
@@ -1167,6 +1234,7 @@ research> continue Analyze price trends in Malmö
#### Async REPL Architecture
**Key Pattern**: Nested event loops
+
```python
async def interactive_repl():
# Outer loop: REPL prompt
@@ -1185,6 +1253,7 @@ async def interactive_repl():
#### Command Aliases
**Natural Language Support**:
+
- `start` / `new` / `begin`
- `continue` / `resume`
- `exit` / `quit` / `q`
@@ -1192,6 +1261,7 @@ async def interactive_repl():
- `reset` / `clear`
**Implementation**:
+
```python
start = subparsers.add_parser('start', aliases=['new', 'begin'])
```
@@ -1199,6 +1269,7 @@ start = subparsers.add_parser('start', aliases=['new', 'begin'])
#### Session State Persistence
**On REPL Start**:
+
```python
state_file = Path.home() / ".deep_research_state"
if state_file.exists():
@@ -1210,6 +1281,7 @@ if state_file.exists():
```
**On Session Change**:
+
```python
state_file.write_text(json.dumps({
"last_session_id": session.session_id,
@@ -1220,6 +1292,7 @@ state_file.write_text(json.dumps({
#### Auto-completion for Session IDs
**Dynamic Completer**:
+
```python
def build_completer(manager: SessionManager) -> Completer:
"""Build dynamic completer with session IDs."""
@@ -1256,6 +1329,7 @@ def build_completer(manager: SessionManager) -> Completer:
**Decision**: Use `prompt_toolkit`
**Rationale**:
+
- ✅ Native async support (critical for long-running research)
- ✅ Used by production tools (IPython, ptpython, AWS CLI)
- ✅ Rich customization (styling, completion, history)
@@ -1269,12 +1343,14 @@ def build_completer(manager: SessionManager) -> Completer:
**Decision**: SessionManager maintains active session in memory, syncs with vault
**Rationale**:
+
- Vault (Obsidian) is **slow** for querying (file I/O)
- In-memory tracking enables fast `status` and `switch` commands
- Vault remains single source of truth (SSOT) - memory is cache
- Sync on session start/complete/switch
**Alternative Considered**: Load from vault every time
+
- **Rejected**: Too slow, would block REPL responsiveness
#### Continuation Context Size
@@ -1282,16 +1358,19 @@ def build_completer(manager: SessionManager) -> Completer:
**Decision**: Compress context to ~50k tokens (insights + report summary)
**Rationale**:
+
- Full session context can be 500k-5M tokens (all workers, tool calls)
- LLM context limits (200k for Claude 3.5 Sonnet)
- Balance: Enough context for coherent continuation, not overwhelming
- Full context available in vault for human review
**Strategy**:
+
- Include: Original query, insights (10 max), report summary (2000 chars), worker count, source count
- Exclude: Full worker outputs, all tool calls, full sources
**Alternative**: Include full worker outputs
+
- **Rejected**: Would hit token limits with 5+ workers
#### Session ID Reuse for Versions
@@ -1299,12 +1378,14 @@ def build_completer(manager: SessionManager) -> Completer:
**Decision**: Same session_id across versions (e.g., `session_20250121_120000_abc123`)
**Rationale**:
+
- ✅ Clear lineage (all versions in same directory)
- ✅ Easy to find related research
- ✅ Graph view shows version chain
- ✅ Simplifies session switching (don't need to remember v2 ID)
**Alternative**: UUID per version
+
- **Rejected**: Loses relationship between versions, harder to navigate
#### Command vs Natural Language Parsing
@@ -1312,12 +1393,14 @@ def build_completer(manager: SessionManager) -> Completer:
**Decision**: Structured commands with aliases (not full natural language)
**Rationale**:
+
- ✅ Predictable, unambiguous
- ✅ Faster to implement
- ✅ Tab completion works
- ✅ Easier to document
**Natural Language**: Could add later with LLM-based intent parsing
+
- Example: "Continue my last session" → parse → `continue`
---
@@ -1367,21 +1450,25 @@ def build_completer(manager: SessionManager) -> Completer:
#### Design Patterns
**Repository Pattern**:
+
- `SessionLoader` - Read operations
- `ObsidianWriter` - Write operations
- Separation of concerns
**Protocol Pattern** (`ProgressCallback`):
+
- `NoOpProgress` - Quiet mode
- `LiveProgress` - Rich display
- Pluggable progress implementations
**State Machine** (LangGraph):
+
- analyze → plan → workers → synthesize
- Already supports parallel execution
- Ready for REPL integration
**Context Manager** (`LiveProgress`):
+
- Clean setup/teardown
- Exception-safe resource management
- Integrates with Rich `Live`
@@ -1393,7 +1480,9 @@ def build_completer(manager: SessionManager) -> Completer:
#### Previous Research
**2025-11-15_deep-research-agent-architecture.md** (lines 850-860):
+
> **Interactive Mode** section describes step-by-step execution:
+>
> ```
> CLI: deep-research research "query" --interactive
> User prompt: Continue? [Y/n/stop] after each agent step
@@ -1403,6 +1492,7 @@ def build_completer(manager: SessionManager) -> Completer:
This was the **original vision** for interactive mode - step-by-step control. Our REPL design extends this to full session management and continuation.
**2025-11-20_obsidian-iterative-research-architecture.md**:
+
> "Previous research identified the need for 'session expansion' and 'iterative refinement' but didn't specify the storage mechanism. This research provides the missing piece: Obsidian as the persistence and exploration layer."
The **storage problem is solved**. Now we're adding the **interaction layer**.
@@ -1419,6 +1509,7 @@ Detailed plan for session versioning, expand command, recompile command. Our REP
#### Key Historical Decision
From 2025-11-16_alibaba-deepresearch-gap-analysis.md:
+
> "Human-in-the-loop decision points enhance research quality"
This reinforces the value of interactive mode - not just for UX, but for **research quality** through human guidance.
@@ -1430,11 +1521,13 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
#### High Risk
**1. Async REPL Complexity**
+
- **Risk**: Nested event loops (prompt + research execution) can deadlock
- **Mitigation**: Use `patch_stdout()`, test extensively with concurrent output
- **Fallback**: Implement synchronous mode that blocks during research
**2. State Synchronization**
+
- **Risk**: In-memory session state gets out of sync with vault
- **Mitigation**: Always sync on session start/complete, add sync command
- **Fallback**: Reload from vault on every command (slower but safe)
@@ -1442,16 +1535,19 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
#### Medium Risk
**3. Token Limits for Continuation**
+
- **Risk**: Compressed context still too large for some queries
- **Mitigation**: Aggressive summarization, configurable context size
- **Fallback**: Allow user to select which workers to include in context
**4. User Confusion**
+
- **Risk**: Command syntax unclear, users struggle
- **Mitigation**: Rich help text, examples, tab completion
- **Fallback**: Add wizard mode for guided workflows
**5. REPL Performance**
+
- **Risk**: Auto-completion sluggish with many sessions
- **Mitigation**: Cache session list, lazy load details
- **Fallback**: Disable auto-completion, use manual entry
@@ -1459,11 +1555,13 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
#### Low Risk
**6. Dependency Stability**
+
- **Risk**: prompt_toolkit breaking changes
- **Mitigation**: Pin version, test upgrades
- **Fallback**: Minimal dependencies, can fork if needed
**7. History File Corruption**
+
- **Risk**: `.deep_research_history` gets corrupted
- **Mitigation**: Graceful fallback to no history
- **Fallback**: Clear history file on corruption
@@ -1473,23 +1571,28 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
### 11. Success Metrics
**1. Command Execution Speed**:
+
- Metric: `status` command < 100ms
- Metric: `list sessions` < 500ms
- Metric: Session switch < 200ms
**2. User Productivity**:
+
- Metric: Time to continue session < 30s (vs 2 min with CLI commands)
- Metric: 80% of users prefer interactive mode in survey
**3. Context Effectiveness**:
+
- Metric: Continuation context < 50k tokens
- Metric: Continuation coherence score > 8/10 (human eval)
**4. Reliability**:
+
- Metric: Zero crashes in 100 REPL sessions
- Metric: State sync accuracy 100% (vault matches memory)
**5. UX Quality**:
+
- Metric: First-time users complete tutorial in < 5 min
- Metric: Tab completion used in 60%+ of commands
@@ -1502,6 +1605,7 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
**Question**: Should we allow users to customize continuation context size?
**Options**:
+
- **Fixed 50k tokens**: Simple, consistent
- **Auto-adjust by complexity**: More context for complex queries
- **User-configurable**: `--context-size` flag
@@ -1513,6 +1617,7 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
**Question**: Should we support collaborative research sessions?
**Options**:
+
- **Single-user only**: Simpler, current architecture
- **Shared vault**: Multiple users, same Obsidian vault
- **Cloud sync**: Real-time collaboration
@@ -1524,6 +1629,7 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
**Question**: Should REPL warn/block expensive operations?
**Options**:
+
- **No limits**: Trust users
- **Soft warnings**: Show estimate, ask confirmation
- **Hard limits**: Configurable max cost per session
@@ -1535,6 +1641,7 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
**Question**: What export formats should we support?
**Options**:
+
- **Markdown**: Already in vault
- **Jupyter Notebook**: For analysis workflows
- **PDF**: For sharing/archiving
@@ -1547,6 +1654,7 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
**Question**: Should we auto-delete old sessions?
**Options**:
+
- **Never delete**: Manual cleanup only
- **Auto-archive**: Move old sessions to `.archive/`
- **TTL-based**: Delete after N days
@@ -1558,6 +1666,7 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
## Code References
### Current CLI Implementation
+
- `deep-research-agent/src/deep_research/cli.py:68-71` - Click group entry point
- `deep-research-agent/src/deep_research/cli.py:74-159` - `research` command (single-agent)
- `deep-research-agent/src/deep_research/cli.py:178-239` - `multi` command (multi-agent)
@@ -1567,10 +1676,12 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
- `deep-research-agent/src/deep_research/cli.py:552-650` - `list-workers` command
### State Management
+
- `deep-research-agent/src/deep_research/agent/state.py:8-58` - Core data structures (`ToolCall`, `ReActIteration`, `WorkerFullContext`, `ResearchSession`)
- `deep-research-agent/src/deep_research/agent/state.py:60-93` - `ResearchSession` with versioning fields
### Orchestrator
+
- `deep-research-agent/src/deep_research/agent/orchestrator.py:69-136` - Research execution entry point
- `deep-research-agent/src/deep_research/agent/orchestrator.py:72-85` - Session initialization
- `deep-research-agent/src/deep_research/agent/orchestrator.py:138-160` - LangGraph workflow construction
@@ -1578,6 +1689,7 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
- `deep-research-agent/src/deep_research/agent/orchestrator.py:419-445` - Full context capture from workers
### Obsidian Integration
+
- `deep-research-agent/src/deep_research/obsidian/writer.py:22-346` - Complete ObsidianWriter implementation
- `deep-research-agent/src/deep_research/obsidian/writer.py:27-49` - Directory structure creation
- `deep-research-agent/src/deep_research/obsidian/writer.py:51-77` - Session write flow
@@ -1589,12 +1701,14 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
- `deep-research-agent/src/deep_research/obsidian/loader.py:143-203` - ReAct trace parsing
### Progress Display
+
- `deep-research-agent/src/deep_research/utils/live_progress.py:24-201` - LiveProgress implementation
- `deep-research-agent/src/deep_research/utils/live_progress.py:14-24` - Initialization with thread-safe lock
- `deep-research-agent/src/deep_research/utils/live_progress.py:26-41` - Context manager pattern
- `deep-research-agent/src/deep_research/utils/live_progress.py:94-185` - Rich rendering logic
### Testing
+
- `deep-research-agent/tests/test_session_loader.py:82-105` - Round-trip persistence test
- `deep-research-agent/tests/test_session_loader.py:266-310` - Parent session linking test
@@ -1603,11 +1717,13 @@ This reinforces the value of interactive mode - not just for UX, but for **resea
## Architecture Comparison
### Current Architecture (Fire-and-Forget)
+
```
User types command → Click parses → asyncio.run() → Execute research → Save to vault → Exit
```
### Proposed Architecture (Interactive REPL)
+
```
Launch REPL → prompt_toolkit loop
↓
@@ -1637,6 +1753,7 @@ The deep-research agent has a **strong foundation** for interactive CLI mode:
5. ✅ **Rich progress display** - Production-grade terminal UI
**What's needed**:
+
1. ❌ REPL loop with `prompt_toolkit`
2. ❌ SessionManager for in-memory state
3. ❌ CommandParser for natural language
@@ -1645,6 +1762,7 @@ The deep-research agent has a **strong foundation** for interactive CLI mode:
**Implementation is straightforward** because the hard parts (state management, persistence, execution) are **already implemented**. The REPL is a thin layer on top.
**Critical Success Factors**:
+
- ✅ prompt_toolkit for rich async REPL experience
- ✅ SessionManager for fast session switching
- ✅ Context compression for continuation (50k tokens)
@@ -1658,6 +1776,7 @@ The deep-research agent has a **strong foundation** for interactive CLI mode:
## References
### Internal Codebase
+
- `deep-research-agent/src/deep_research/cli.py` - Current CLI implementation
- `deep-research-agent/src/deep_research/agent/orchestrator.py` - Research execution engine
- `deep-research-agent/src/deep_research/agent/state.py` - Data structures
@@ -1667,6 +1786,7 @@ The deep-research agent has a **strong foundation** for interactive CLI mode:
### External Documentation
**prompt_toolkit**:
+
- Official Documentation: https://python-prompt-toolkit.readthedocs.io/en/master/
- SQLite REPL Tutorial: https://python-prompt-toolkit.readthedocs.io/en/master/pages/tutorials/repl.html
- Asyncio Support: https://python-prompt-toolkit.readthedocs.io/en/master/pages/advanced_topics/asyncio.html
@@ -1674,17 +1794,20 @@ The deep-research agent has a **strong foundation** for interactive CLI mode:
- Async Example: https://github.com/prompt-toolkit/python-prompt-toolkit/blob/main/examples/prompts/asyncio-prompt.py
**REPL Frameworks**:
+
- cmd2 Documentation: https://cmd2.readthedocs.io/
- cmd2 GitHub: https://github.com/python-cmd2/cmd2
- cmd2 Alternatives Comparison: https://cmd2.readthedocs.io/en/0.9.0/alternatives.html
**Async REPL Patterns**:
+
- aiomonitor Documentation: https://aiomonitor.aio-libs.org/en/latest/tutorial/
- aiomonitor GitHub: https://github.com/aio-libs/aiomonitor
- IPython Autoawait: https://ipython.readthedocs.io/en/stable/interactive/autoawait.html
- Jupyter Architecture: https://docs.jupyter.org/en/latest/projects/architecture/content-architecture.html
**Command Parsing**:
+
- shlex Documentation: https://docs.python.org/3/library/shlex.html
- argparse Documentation: https://docs.python.org/3/library/argparse.html
- REPL + argparse Pattern: https://gist.github.com/benkehoe/2e6a08b385e3385f8a54805c99914c75
@@ -1692,10 +1815,12 @@ The deep-research agent has a **strong foundation** for interactive CLI mode:
- Stack Overflow Discussion: https://stackoverflow.com/questions/69062838/python-library-for-repl-and-cli-argument-parsing
**Progress Display**:
+
- Rich Progress: https://rich.readthedocs.io/en/stable/progress.html
- tqdm with asyncio: https://towardsdatascience.com/using-tqdm-with-asyncio-in-python-5c0f6e747d55
**Production Examples**:
+
- ptpython GitHub: https://github.com/prompt-toolkit/ptpython
- ptpython Basic Embed: https://github.com/prompt-toolkit/ptpython/blob/main/examples/python-embed.py
- ptpython Asyncio Embed: https://github.com/prompt-toolkit/ptpython/blob/main/examples/asyncio-python-embed.py
@@ -1703,12 +1828,14 @@ The deep-research agent has a **strong foundation** for interactive CLI mode:
- aws-cli-repl (Performance-Optimized): https://github.com/janakaud/aws-cli-repl
**Additional Resources**:
+
- 4 Python Libraries for CLIs: https://opensource.com/article/17/5/4-practical-python-libraries
- Python asyncio Documentation: https://docs.python.org/3/library/asyncio.html
- Writing an async REPL (blog): https://carreau.github.io/posts/27-Writing-an-async-REPL---Part-1.ipynb/
- Python readline module: https://docs.python.org/3/library/readline.html
### Historical Research Documents
+
- `thoughts/shared/research/2025-11-20_obsidian-iterative-research-architecture.md` - Obsidian-based iterative research architecture
- `thoughts/shared/research/2025-11-15_deep-research-agent-architecture.md` - Original deep research agent architecture with interactive mode vision (lines 850-860)
- `thoughts/shared/research/2025-11-15_multi-agent-deep-research-architecture-v2.md` - Multi-agent architecture v2
diff --git a/thoughts/shared/research/2025-11-22_go-deep-research-agent-architecture.md b/thoughts/shared/research/2025-11-22_go-deep-research-agent-architecture.md
index 0c919df..309301f 100644
--- a/thoughts/shared/research/2025-11-22_go-deep-research-agent-architecture.md
+++ b/thoughts/shared/research/2025-11-22_go-deep-research-agent-architecture.md
@@ -4,7 +4,7 @@ researcher: Claude
git_commit: 86dca03ec2e572219e7ffd1612e60a4aae8331ef
branch: feat/custom-deep-research
repository: addcommitpush.io
-topic: "Go Deep Research Agent Architecture"
+topic: 'Go Deep Research Agent Architecture'
tags: [architecture, golang, deep-research, interactive-cli, multi-agent]
status: complete
last_updated: 2025-11-22
@@ -34,14 +34,14 @@ This document defines the architecture for a Go-based deep research agent that r
## Core Requirements
-| Requirement | Description |
-|-------------|-------------|
-| Fast Research | Single worker, quick turnaround for simple queries |
-| Deep Research | Multi-worker parallel execution for complex queries |
-| Obsidian Integration | Markdown vault with YAML frontmatter, linked notes |
-| Session Management | Persist, load, continue, expand sessions |
-| Interactive Mode | REPL with `/commands`, natural follow-ups route to expand |
-| Streaming Output | Real-time feedback as workers progress |
+| Requirement | Description |
+| -------------------- | --------------------------------------------------------- |
+| Fast Research | Single worker, quick turnaround for simple queries |
+| Deep Research | Multi-worker parallel execution for complex queries |
+| Obsidian Integration | Markdown vault with YAML frontmatter, linked notes |
+| Session Management | Persist, load, continue, expand sessions |
+| Interactive Mode | REPL with `/commands`, natural follow-ups route to expand |
+| Streaming Output | Real-time feedback as workers progress |
---
@@ -2010,21 +2010,21 @@ func getEnvOrDefault(key, def string) string {
## Command Reference
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/fast ` | `/f` | Single-worker quick research |
-| `/deep ` | `/d` | Multi-worker deep research |
-| `/expand ` | `/e` | Expand on current session |
-| `/sessions` | `/s` | List all saved sessions |
-| `/load ` | `/l` | Load a specific session |
-| `/workers` | `/w` | Show workers in current session |
-| `/rerun ` | `/r` | Re-run worker n |
-| `/recompile [text]` | `/rc` | Recompile report with optional instructions |
-| `/model` | | Show/change current model |
-| `/verbose` | `/v` | Toggle verbose output |
-| `/help` | `/h`, `/?` | Show help |
-| `/quit` | `/q` | Exit REPL |
-| `` | | Follow-up question (routes to expand) |
+| Command | Alias | Description |
+| ------------------- | ---------- | ------------------------------------------- |
+| `/fast ` | `/f` | Single-worker quick research |
+| `/deep ` | `/d` | Multi-worker deep research |
+| `/expand ` | `/e` | Expand on current session |
+| `/sessions` | `/s` | List all saved sessions |
+| `/load ` | `/l` | Load a specific session |
+| `/workers` | `/w` | Show workers in current session |
+| `/rerun ` | `/r` | Re-run worker n |
+| `/recompile [text]` | `/rc` | Recompile report with optional instructions |
+| `/model` | | Show/change current model |
+| `/verbose` | `/v` | Toggle verbose output |
+| `/help` | `/h`, `/?` | Show help |
+| `/quit` | `/q` | Exit REPL |
+| `` | | Follow-up question (routes to expand) |
---
@@ -2109,6 +2109,7 @@ func getEnvOrDefault(key, def string) string {
## Implementation Phases
### Phase 1: Core Infrastructure
+
- [ ] Project structure and go.mod
- [ ] Configuration loading
- [ ] LLM client (OpenRouter + Alibaba model)
@@ -2116,6 +2117,7 @@ func getEnvOrDefault(key, def string) string {
- [ ] Basic terminal renderer
### Phase 2: Agent & Tools
+
- [ ] Search tool (Brave API)
- [ ] Fetch tool (web scraping)
- [ ] Tool registry
@@ -2123,6 +2125,7 @@ func getEnvOrDefault(key, def string) string {
- [ ] Answer detection and extraction
### Phase 3: Orchestration
+
- [ ] Query complexity analysis
- [ ] Task decomposition planner
- [ ] Worker pool with goroutines
@@ -2130,6 +2133,7 @@ func getEnvOrDefault(key, def string) string {
- [ ] Cost tracking
### Phase 4: Session Management
+
- [ ] Session data structures
- [ ] In-memory store
- [ ] JSON persistence
@@ -2137,6 +2141,7 @@ func getEnvOrDefault(key, def string) string {
- [ ] Context building for continuation
### Phase 5: Obsidian Integration
+
- [ ] Vault directory structure
- [ ] Worker markdown files
- [ ] Report files with versions
@@ -2144,6 +2149,7 @@ func getEnvOrDefault(key, def string) string {
- [ ] YAML frontmatter
### Phase 6: Interactive REPL
+
- [ ] Readline integration
- [ ] Command parser
- [ ] Router (command vs text)
@@ -2152,6 +2158,7 @@ func getEnvOrDefault(key, def string) string {
- [ ] Session restore on startup
### Phase 7: Polish
+
- [ ] Streaming output
- [ ] Progress indicators
- [ ] Error handling
@@ -2183,17 +2190,22 @@ Minimal dependencies - no heavy frameworks. The LLM client uses stdlib `net/http
## Open Questions
1. **Streaming vs Batched**: Should final synthesis stream to terminal or batch?
- - Streaming. Try to use streaming APIs when interacting with LLMs, I want it to feel responsive to users.
+
+- Streaming. Try to use streaming APIs when interacting with LLMs, I want it to feel responsive to users.
+
2. **Insight Extraction**: Keep separate LLM call (Python uses Claude) or same model?
- - No, same model for everything. but centralize the configuration of what model I use for what parts. so it is easy to change. but same model (alibaba/tongyi-deepresearch-30b-a3b) for everything now for simplicity.
+
+- No, same model for everything. but centralize the configuration of what model I use for what parts. so it is easy to change. but same model (alibaba/tongyi-deepresearch-30b-a3b) for everything now for simplicity.
+
3. **Search Provider**: Brave only, or add fallback to DuckDuckGo?
- - Brave only
+
+- Brave only
+
4. **State File Format**: JSON sufficient, or use SQLite for complex queries?
- - JSON to begin with.
+- JSON to begin with.
-ALSO, no fallback logic whatsoever. fallback logic is strictly forbidding. IMPORTANT! NO FALLBACK LOGIC EVER!
----
+## ALSO, no fallback logic whatsoever. fallback logic is strictly forbidding. IMPORTANT! NO FALLBACK LOGIC EVER!
## References
diff --git a/thoughts/shared/research/2025-12-01_event-sourced-storage-architecture.md b/thoughts/shared/research/2025-12-01_event-sourced-storage-architecture.md
index d676471..6a9d307 100644
--- a/thoughts/shared/research/2025-12-01_event-sourced-storage-architecture.md
+++ b/thoughts/shared/research/2025-12-01_event-sourced-storage-architecture.md
@@ -4,7 +4,7 @@ researcher: Claude
git_commit: 389794cff579752d9f38f5df80b0da22ab1c6e24
branch: feat/custom-deep-research
repository: addcommitpush.io
-topic: "Event-Sourced Adapter-Based Storage Architecture for Interruptible Agents"
+topic: 'Event-Sourced Adapter-Based Storage Architecture for Interruptible Agents'
tags: [research, architecture, event-sourcing, storage, adapters, interruptible-agents, go-research]
status: complete
last_updated: 2025-12-01
@@ -22,6 +22,7 @@ last_updated_by: Claude
## Research Question
How to move storage to an adapter-based system that:
+
1. Mirrors state with extra information (metadata, timestamps, audit trail)
2. Keeps "memory" that can be paused and restored from any point (interruptible agent)
3. Allows the agent to pick up work where it left off
@@ -46,23 +47,23 @@ The architecture uses a **port/adapter pattern** for pluggable storage backends,
### 1.1 Current Architecture Problems
-| Problem | Current State | Impact |
-|---------|--------------|--------|
-| **No State Persistence** | State is local variables in `Research()` | Cannot resume interrupted research |
-| **No Event Log** | Events are fire-and-forget | Cannot replay or audit state changes |
-| **Direct State Mutation** | `plan.DAG.SetStatus()` mutates directly | No history, no undo capability |
-| **Session-Centric Storage** | Only saves complete sessions | Partial progress lost on failure |
-| **Tight Storage Coupling** | JSON filesystem hardcoded | Cannot swap backends easily |
+| Problem | Current State | Impact |
+| --------------------------- | ---------------------------------------- | ------------------------------------ |
+| **No State Persistence** | State is local variables in `Research()` | Cannot resume interrupted research |
+| **No Event Log** | Events are fire-and-forget | Cannot replay or audit state changes |
+| **Direct State Mutation** | `plan.DAG.SetStatus()` mutates directly | No history, no undo capability |
+| **Session-Centric Storage** | Only saves complete sessions | Partial progress lost on failure |
+| **Tight Storage Coupling** | JSON filesystem hardcoded | Cannot swap backends easily |
### 1.2 Key Files to Transform
-| File | Current Role | New Role |
-|------|--------------|----------|
-| `internal/events/bus.go` | Fire-and-forget pub/sub | Event bus + persistence trigger |
-| `internal/events/types.go` | UI progress events | Domain events (state changes) |
-| `internal/session/session.go` | Domain + storage conflated | Pure domain aggregate |
-| `internal/session/store.go` | Direct JSON persistence | Event store + projection |
-| `internal/orchestrator/deep.go` | Stateless coordinator | State machine with event sourcing |
+| File | Current Role | New Role |
+| ------------------------------- | -------------------------- | --------------------------------- |
+| `internal/events/bus.go` | Fire-and-forget pub/sub | Event bus + persistence trigger |
+| `internal/events/types.go` | UI progress events | Domain events (state changes) |
+| `internal/session/session.go` | Domain + storage conflated | Pure domain aggregate |
+| `internal/session/store.go` | Direct JSON persistence | Event store + projection |
+| `internal/orchestrator/deep.go` | Stateless coordinator | State machine with event sourcing |
---
@@ -180,10 +181,10 @@ The architecture uses a **port/adapter pattern** for pluggable storage backends,
The system needs two categories of events:
-| Category | Purpose | Persistence | Examples |
-|----------|---------|-------------|----------|
-| **Domain Events** | State changes (facts) | YES - Event Store | `ResearchStarted`, `WorkerCompleted`, `ReportGenerated` |
-| **Progress Events** | UI updates (ephemeral) | NO - Fire-and-forget | `LLMChunk`, `ToolCall`, `Progress` |
+| Category | Purpose | Persistence | Examples |
+| ------------------- | ---------------------- | -------------------- | ------------------------------------------------------- |
+| **Domain Events** | State changes (facts) | YES - Event Store | `ResearchStarted`, `WorkerCompleted`, `ReportGenerated` |
+| **Progress Events** | UI updates (ephemeral) | NO - Fire-and-forget | `LLMChunk`, `ToolCall`, `Progress` |
### 3.2 Domain Event Definitions
@@ -2294,23 +2295,23 @@ func main() {
### Benefits
-| Benefit | How It's Achieved |
-|---------|-------------------|
-| **Interruptibility** | State persisted after every event |
-| **Resumability** | Replay events to reconstruct state |
-| **Audit Trail** | Every change is an immutable event |
-| **Pluggable Storage** | Port/adapter pattern for backends |
-| **Time Travel** | Replay to any point in history |
-| **Multiple Projections** | Same events → Obsidian, DB, API |
+| Benefit | How It's Achieved |
+| ------------------------ | ---------------------------------- |
+| **Interruptibility** | State persisted after every event |
+| **Resumability** | Replay events to reconstruct state |
+| **Audit Trail** | Every change is an immutable event |
+| **Pluggable Storage** | Port/adapter pattern for backends |
+| **Time Travel** | Replay to any point in history |
+| **Multiple Projections** | Same events → Obsidian, DB, API |
### Trade-offs
-| Trade-off | Mitigation |
-|-----------|------------|
-| Storage overhead | Snapshots reduce replay cost |
-| Complexity | Clear command/event separation |
+| Trade-off | Mitigation |
+| -------------------- | ------------------------------------- |
+| Storage overhead | Snapshots reduce replay cost |
+| Complexity | Clear command/event separation |
| Eventual consistency | Inline projections for critical paths |
-| Event versioning | Schema evolution strategy needed |
+| Event versioning | Schema evolution strategy needed |
---
@@ -2333,6 +2334,7 @@ func main() {
## Sources
### Event Sourcing References
+
- [Event Sourcing pattern - Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/patterns/event-sourcing)
- [Event Sourcing pattern - AWS Prescriptive Guidance](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/event-sourcing.html)
- [Event Sourcing - Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
@@ -2340,10 +2342,12 @@ func main() {
- [Snapshots in Event Sourcing - Kurrent](https://www.kurrent.io/blog/snapshots-in-event-sourcing)
### Domain Events References
+
- [Domain Events vs. Event Sourcing - INNOQ](https://www.innoq.com/en/blog/2019/01/domain-events-versus-event-sourcing/)
- [Domain Events vs. Integration Events - Cesar de la Torre](https://devblogs.microsoft.com/cesardelatorre/domain-events-vs-integration-events-in-domain-driven-design-and-microservices-architectures/)
### Go Implementation References
+
- [hallgren/eventsourcing - GitHub](https://github.com/hallgren/eventsourcing)
- [Event Sourcing in Go: From Zero to Production - Serge Skoredin](https://skoredin.pro/blog/golang/event-sourcing-go)
- [Simplifying Event Sourcing in Golang - TheFabric.IO](https://www.thefabric.io/blog/simplifying-event-sourcing-in-golang)
@@ -2351,6 +2355,7 @@ func main() {
- [Implementing pluggable backends in Go - Justin Azoff](https://justin.azoff.dev/blog/implementing-pluggable-backends-in-go/)
### Patterns and Best Practices
+
- [CQRS Best Practices - GitHub](https://github.com/slashdotdash/cqrs-best-practices)
- [Guide to Projections and Read Models - Event-Driven.io](https://event-driven.io/en/projections_and_read_models_in_event_driven_architecture/)
- [Saga Pattern in Distributed Transactions - Rost Glukhov](https://www.glukhov.org/post/2025/11/saga-transactions-in-microservices/)
diff --git a/thoughts/shared/research/2025-12-03_09-45-00_thinkdepth-architecture.md b/thoughts/shared/research/2025-12-03_09-45-00_thinkdepth-architecture.md
index 1bcb353..4ecb696 100644
--- a/thoughts/shared/research/2025-12-03_09-45-00_thinkdepth-architecture.md
+++ b/thoughts/shared/research/2025-12-03_09-45-00_thinkdepth-architecture.md
@@ -4,12 +4,12 @@ researcher: Claude
git_commit: 7a0d7034c05fc3e2dd0010ea7c396615afe9d632
branch: main
repository: go-research
-topic: "ThinkDepth.ai Deep Research Architecture Analysis and Implementation Plan"
+topic: 'ThinkDepth.ai Deep Research Architecture Analysis and Implementation Plan'
tags: [research, thinkdepth, deep-research, agentic-ai, architecture, cli-visualization]
status: complete
last_updated: 2025-12-03
last_updated_by: Claude
-last_updated_note: "Added comprehensive CLI visualization design section with event types, display components, and example output"
+last_updated_note: 'Added comprehensive CLI visualization design section with event types, display components, and example output'
---
# Research: ThinkDepth.ai Deep Research Architecture Analysis and Implementation Plan
@@ -72,6 +72,7 @@ ThinkDepth uses a multi-agent supervisor pattern with LangGraph:
### 2. Key Components
#### 2.1 Supervisor Agent (Lead Researcher)
+
- **File**: `multi_agent_supervisor.py`
- **Model Used**: `openai:gpt-5` (in original)
- **Our Model**: `alibaba/tongyi-deepresearch-30b-a3b`
@@ -82,6 +83,7 @@ ThinkDepth uses a multi-agent supervisor pattern with LangGraph:
- `think_tool` - Strategic reflection
#### 2.2 Research Sub-Agent
+
- **File**: `research_agent.py`
- **Model Used**: `openai:gpt-5` (in original)
- **Tools Available**:
@@ -89,6 +91,7 @@ ThinkDepth uses a multi-agent supervisor pattern with LangGraph:
- `think_tool` - Reflection after each search
#### 2.3 State Management
+
- `SupervisorState`: supervisor_messages, research_brief, notes, research_iterations, raw_notes, draft_report
- `ResearcherState`: researcher_messages, tool_call_iterations, research_topic, compressed_research, raw_notes
- `AgentState`: messages, research_brief, supervisor_messages, raw_notes, notes, draft_report, final_report
@@ -110,11 +113,13 @@ Key insight: **Never complete based on draft report looking good** - always veri
### 4. Self-Balancing Rules
#### 4.1 Insightfulness Rules (Applied in Final Report)
+
- Granular breakdown of topics with specific causes/impacts
- Detailed mapping tables connecting relationships
- Nuanced exploration with explicit discussion
#### 4.2 Helpfulness Rules (Applied in Final Report)
+
- Direct user intent satisfaction
- Fluent, coherent logical structure
- Factual accuracy
@@ -125,6 +130,7 @@ Key insight: **Never complete based on draft report looking good** - always veri
### 5. Context Compression Strategy
#### 5.1 Research Compression (`compress_research_system_prompt`)
+
- Preserve ALL information from tool calls verbatim
- Clean up but don't summarize
- Include inline citations for each source
@@ -135,6 +141,7 @@ Key insight: **Never complete based on draft report looking good** - always veri
- List of All Relevant Sources
#### 5.2 Draft Report as Context
+
- Acts as "dynamic context" that guides subsequent research
- Similar to "gradually adding features to an initial prototype"
- Mitigates context pollution, distraction, confusion, and clash
@@ -142,6 +149,7 @@ Key insight: **Never complete based on draft report looking good** - always veri
### 6. Tool Implementations
#### 6.1 tavily_search Tool
+
```python
# Executes search → deduplicates by URL → summarizes raw content → formats output
@tool
@@ -153,6 +161,7 @@ def tavily_search(query: str, max_results: int = 3, topic: str = "general") -> s
```
#### 6.2 think_tool
+
```python
@tool
def think_tool(reflection: str) -> str:
@@ -161,6 +170,7 @@ def think_tool(reflection: str) -> str:
```
#### 6.3 refine_draft_report Tool
+
```python
@tool
def refine_draft_report(research_brief: str, findings: str, draft_report: str) -> str:
@@ -172,6 +182,7 @@ def refine_draft_report(research_brief: str, findings: str, draft_report: str) -
### 7. Configuration Constants
From the original implementation:
+
- `max_researcher_iterations = 15` (tool calls per sub-agent)
- `max_concurrent_researchers = 3` (parallel sub-agents)
- `MAX_CONTEXT_LENGTH = 250000` (for webpage summarization)
@@ -179,12 +190,14 @@ From the original implementation:
### 8. Key Prompts (Detailed Analysis)
#### 8.1 Lead Researcher Prompt (`lead_researcher_with_multiple_steps_diffusion_double_check_prompt`)
+
- Emphasizes diffusion algorithm
- Critical: "CompleteResearch only based on findings' completeness, not draft report"
- Always run diverse research questions to verify comprehensiveness
- Use parallel ConductResearch for multi-faceted questions
#### 8.2 Research Agent Prompt (`research_agent_prompt`)
+
- Hard limits: 2-3 searches for simple, up to 5 for complex
- Stop immediately when:
- Can answer comprehensively
@@ -192,6 +205,7 @@ From the original implementation:
- Last 2 searches returned similar information
#### 8.3 Final Report Prompt (`final_report_generation_with_helpfulness_insightfulness_hit_citation_prompt`)
+
- Applies both Insightfulness and Helpfulness rules
- Flexible section structure (comparison, list, overview, etc.)
- Strict citation rules with sequential numbering
@@ -199,6 +213,7 @@ From the original implementation:
## Implementation Plan for Go
### File Structure
+
```
internal/architectures/think_deep/
├── README.md # Architecture documentation
@@ -1107,17 +1122,19 @@ func init() {
5. **Parallel Sub-Agents**: Up to 3 concurrent sub-researchers for independent topics
### Model Mapping
-| Original Model | Our Model |
-|----------------|-----------|
+
+| Original Model | Our Model |
+| -------------- | ------------------------------------- |
| `openai:gpt-5` | `alibaba/tongyi-deepresearch-30b-a3b` |
-| Tavily Search | Brave Search (existing) |
+| Tavily Search | Brave Search (existing) |
### Configuration Mapping
-| Original | Our Go Implementation |
-|----------|----------------------|
+
+| Original | Our Go Implementation |
+| -------------------------------- | ------------------------------ |
| `max_researcher_iterations = 15` | `MaxSupervisorIterations = 15` |
-| `max_concurrent_researchers = 3` | `MaxConcurrentResearch = 3` |
-| `MAX_CONTEXT_LENGTH = 250000` | (handled by model) |
+| `max_concurrent_researchers = 3` | `MaxConcurrentResearch = 3` |
+| `MAX_CONTEXT_LENGTH = 250000` | (handled by model) |
## Open Questions
@@ -1533,15 +1550,15 @@ When running ThinkDeep research, the user sees:
### Color Scheme
-| Phase | Color | Icon |
-|-------|-------|------|
-| Brief | Blue (HiBlue) | 📋 |
-| Draft | Yellow (HiYellow) | 📝 |
-| Diffuse | Magenta (HiMagenta) | 🔄 |
-| Sub-research | Yellow/Cyan | 🔍💭📦 |
-| Refinement | Cyan | ✏️ |
-| Final | Green (HiGreen) | ✓ |
-| Thinking | Dim | 💭 |
+| Phase | Color | Icon |
+| ------------ | ------------------- | ------ |
+| Brief | Blue (HiBlue) | 📋 |
+| Draft | Yellow (HiYellow) | 📝 |
+| Diffuse | Magenta (HiMagenta) | 🔄 |
+| Sub-research | Yellow/Cyan | 🔍💭📦 |
+| Refinement | Cyan | ✏️ |
+| Final | Green (HiGreen) | ✓ |
+| Thinking | Dim | 💭 |
## References
diff --git a/thoughts/shared/research/2025-12-03_interactive-cli-agentic-research.md b/thoughts/shared/research/2025-12-03_interactive-cli-agentic-research.md
index 86ce925..fb446e5 100644
--- a/thoughts/shared/research/2025-12-03_interactive-cli-agentic-research.md
+++ b/thoughts/shared/research/2025-12-03_interactive-cli-agentic-research.md
@@ -4,7 +4,7 @@ researcher: Claude
git_commit: 6a32cb5cc41e10a32999f565d10ca639bbecc06c
branch: main
repository: addcommitpush.io/go-research
-topic: "Interactive CLI Agentic Research Experience"
+topic: 'Interactive CLI Agentic Research Experience'
tags: [research, cli, interactive, obsidian, think_deep, storm, agents]
status: complete
last_updated: 2025-12-03
@@ -22,6 +22,7 @@ last_updated_by: Claude
## Research Question
Design an interactive CLI experience for deep research where:
+
1. Users can invoke different research modes (fast, storm, think_deep)
2. Sessions maintain context about written reports (outputs only, not full agent context)
3. Smart mode selection based on query complexity
@@ -32,12 +33,14 @@ Design an interactive CLI experience for deep research where:
## Summary
The current go-research CLI has strong foundations for an interactive agentic experience. The architecture supports:
+
- Session management with versioning and parent tracking
- Event-driven visualization of research progress
- Existing `/expand` handler for follow-up queries
- Obsidian integration for persistence (though sub-insights not yet saved)
The proposed "Claude Code-style" interactive experience requires:
+
1. A **Chat Router** that intelligently routes queries to appropriate agents
2. **Session Context Manager** that maintains report summaries without full agent state
3. **Expand Knowledge Pipeline** with injection points into each agent architecture
@@ -48,18 +51,21 @@ The proposed "Claude Code-style" interactive experience requires:
### 1. Current Architecture Analysis
#### Entry Points (`cmd/research/main.go:51-52`)
+
```go
vaultWriter := obsidian.NewWriter(cfg.VaultPath)
store.SetVaultWriter(vaultWriter)
```
The CLI initializes with:
+
- Session store (filesystem-based JSON)
- Event bus for real-time visualization
- Obsidian vault writer for human-readable output
- REPL with command router
#### Router Intelligence (`internal/repl/router.go:59-74`)
+
```go
// Natural language: if session exists, expand; otherwise start storm research
if r.ctx.Session != nil {
@@ -72,6 +78,7 @@ return handler, []string{parsed.RawText}, nil
```
**Current behavior**:
+
- Commands (`/fast`, `/deep`, `/expand`) → explicit routing
- Natural language WITH session → `/expand` handler
- Natural language WITHOUT session → `/storm` handler
@@ -79,6 +86,7 @@ return handler, []string{parsed.RawText}, nil
**Gap**: No smart mode selection or chat/QA detection.
#### Expand Handler (`internal/repl/handlers/expand.go:32-55`)
+
```go
// Build continuation context from previous session
continuationCtx := session.BuildContinuationContext(ctx.Session)
@@ -93,6 +101,7 @@ newSess := ctx.Session.NewVersion()
```
**Current behavior**:
+
- Builds context from previous session (report + sources)
- Creates versioned session with parent link
- Runs research with injected context
@@ -104,15 +113,16 @@ newSess := ctx.Session.NewVersion()
#### ThinkDeep Injection Points (`internal/orchestrator/think_deep.go`)
-| Stage | Line | Injection Opportunity |
-|-------|------|----------------------|
-| Research Brief | 264 | Inject domain knowledge, previous findings |
-| Initial Draft | 284 | Inject existing report as baseline |
-| Supervisor Context | `supervisor.go:209` | Add `` section |
-| Sub-Researcher | `sub_researcher.go:102` | Inject visited URLs, known facts |
-| Final Report | 312 | Add style guidelines, structure template |
+| Stage | Line | Injection Opportunity |
+| ------------------ | ----------------------- | ------------------------------------------ |
+| Research Brief | 264 | Inject domain knowledge, previous findings |
+| Initial Draft | 284 | Inject existing report as baseline |
+| Supervisor Context | `supervisor.go:209` | Add `` section |
+| Sub-Researcher | `sub_researcher.go:102` | Inject visited URLs, known facts |
+| Final Report | 312 | Add style guidelines, structure template |
**Key insight**: ThinkDeep's `SupervisorState` already tracks:
+
- `Notes []string` - compressed findings
- `RawNotes []string` - raw search results
- `VisitedURLs map[string]bool` - deduplication
@@ -121,14 +131,15 @@ These can be pre-populated for "expand" workflows.
#### STORM Injection Points (`internal/orchestrator/deep_storm.go`)
-| Stage | Line | Injection Opportunity |
-|-------|------|----------------------|
-| Perspective Discovery | 124 | Inject known perspectives, skip survey |
-| Conversation Simulation | 159 | Inject previous conversations as context |
-| Cross-Validation | 192 | Inject validated facts from previous run |
-| Synthesis | 230 | Inject previous outline, sections |
+| Stage | Line | Injection Opportunity |
+| ----------------------- | ---- | ---------------------------------------- |
+| Perspective Discovery | 124 | Inject known perspectives, skip survey |
+| Conversation Simulation | 159 | Inject previous conversations as context |
+| Cross-Validation | 192 | Inject validated facts from previous run |
+| Synthesis | 230 | Inject previous outline, sections |
**Key insight**: STORM produces rich intermediate artifacts:
+
- `[]Perspective` - expert viewpoints
- `map[string]*ConversationResult` - full dialogue transcripts
- `*AnalysisResult` - validated facts, contradictions, gaps
@@ -169,6 +180,7 @@ const (
```
**Classification Logic**:
+
1. No session → `IntentResearch`
2. Question about report content → `IntentQuestion`
3. "Expand on X", "Tell me more about Y" → `IntentExpand`
@@ -302,6 +314,7 @@ type InjectionContext struct {
```
**ThinkDeep Expansion Flow**:
+
```go
func (h *ExpandKnowledgeHandler) expandWithThinkDeep(
ctx *repl.Context,
@@ -338,6 +351,7 @@ func (h *ExpandKnowledgeHandler) expandWithThinkDeep(
Current gap: `internal/obsidian/writer.go` creates `insights/` directory but never populates it.
**Proposed structure**:
+
```
/
└── /
@@ -505,33 +519,39 @@ research> /fast Who invented transformers?
### 6. Implementation Roadmap
#### Phase 1: Sub-Insight Capture (think_deep)
+
- [ ] Add `SubInsights []SubInsight` to `SupervisorState`
- [ ] Capture insights in `executeParallelResearch`
- [ ] Return insights in `ThinkDeepResult`
- [ ] Update Obsidian writer to save insights
#### Phase 2: Session Context Manager
+
- [ ] Create `SessionContext` struct
- [ ] Implement `ExtractContext(session) SessionContext`
- [ ] Add context to session store
#### Phase 3: Question Handler
+
- [ ] Create `QuestionHandler`
- [ ] Implement `buildQAContext`
- [ ] Add expansion suggestion logic
#### Phase 4: Smart Router
+
- [ ] Create `QueryClassifier` interface
- [ ] Implement LLM-based classifier
- [ ] Update `Router` to use classifier
#### Phase 5: Expand Knowledge Pipeline
+
- [ ] Create `InjectionContext` struct
- [ ] Implement ThinkDeep injection options
- [ ] Implement STORM injection options
- [ ] Create merge logic for expanded sessions
#### Phase 6: Enhanced Obsidian
+
- [ ] Implement research-notes structure
- [ ] Add source index with quality scores
- [ ] Create bi-directional links between insights
diff --git a/thoughts/shared/research/2025-12-03_think-deep-data-tools.md b/thoughts/shared/research/2025-12-03_think-deep-data-tools.md
index 421a865..d3beb49 100644
--- a/thoughts/shared/research/2025-12-03_think-deep-data-tools.md
+++ b/thoughts/shared/research/2025-12-03_think-deep-data-tools.md
@@ -4,7 +4,7 @@ researcher: Claude
git_commit: 6a32cb5cc41e10a32999f565d10ca639bbecc06c
branch: main
repository: addcommitpush.io/go-research
-topic: "Data Analysis and File Reading Tools for ThinkDeep Agent"
+topic: 'Data Analysis and File Reading Tools for ThinkDeep Agent'
tags: [research, think_deep, tools, data_analysis, eda, pdf, csv, pickle]
status: complete
last_updated: 2025-12-03
@@ -39,6 +39,7 @@ The design should mirror the existing `search` → `ContentSummarizer` pattern w
### 1. Current Tool Architecture
**Tool Interface** (`internal/tools/registry.go:9-13`):
+
```go
type Tool interface {
Name() string
@@ -48,6 +49,7 @@ type Tool interface {
```
**ToolExecutor Interface** (`internal/tools/registry.go:15-19`):
+
```go
type ToolExecutor interface {
Execute(ctx context.Context, name string, args map[string]interface{}) (string, error)
@@ -56,6 +58,7 @@ type ToolExecutor interface {
```
**Key Pattern - Search with Optional Summarization** (`internal/tools/search.go`):
+
- `SearchTool` performs basic web search
- Optional `ContentSummarizer` enhances results with LLM-generated summaries
- This pattern is directly applicable to data analysis tools
@@ -63,6 +66,7 @@ type ToolExecutor interface {
### 2. Sub-Researcher Agent Pattern
The `SubResearcherAgent` (`internal/agents/sub_researcher.go:23-29`) demonstrates how to create a focused agent that:
+
- Has access to specific tools (search, think)
- Executes an iterative loop with hard limits
- Compresses findings for the supervisor
@@ -75,6 +79,7 @@ This pattern can be adapted for a `DataAnalysisAgent` sub-researcher.
#### 3.1 Data Analysis Tools
**CSVAnalysisTool** - For CSV/tabular data:
+
```go
// internal/tools/csv_analysis.go
@@ -101,6 +106,7 @@ func (t *CSVAnalysisTool) Execute(ctx context.Context, args map[string]interface
```
**PickleAnalysisTool** - For Python pickle files:
+
```go
// internal/tools/pickle_analysis.go
@@ -123,6 +129,7 @@ func (t *PickleAnalysisTool) Execute(ctx context.Context, args map[string]interf
```
**GoalDirectedEDATool** - High-level EDA orchestrator:
+
```go
// internal/tools/eda.go
@@ -142,6 +149,7 @@ Args: {"path": "/path/to/data", "goal": "research question or hypothesis to expl
#### 3.2 Document Reading Tools
**PDFReadTool** - For PDF documents:
+
```go
// internal/tools/pdf.go
@@ -165,6 +173,7 @@ func (t *PDFReadTool) Execute(ctx context.Context, args map[string]interface{})
```
**DOCXReadTool** - For Word documents:
+
```go
// internal/tools/docx.go
@@ -180,6 +189,7 @@ func (t *DOCXReadTool) Description() string {
```
**PPTXReadTool** - For PowerPoint:
+
```go
// internal/tools/pptx.go
@@ -195,6 +205,7 @@ func (t *PPTXReadTool) Description() string {
```
**GenericDocumentReadTool** - Auto-detect format:
+
```go
// internal/tools/document.go
@@ -259,6 +270,7 @@ func (a *DataAnalystAgent) Analyze(ctx context.Context, dataPath string, goal st
```
**Data Analyst Prompt** (new file: `internal/think_deep/data_prompts.go`):
+
```go
func DataAnalystPrompt(date, dataDescription string) string {
return fmt.Sprintf(`You are a data analyst conducting exploratory data analysis. Today is %s.
@@ -344,6 +356,7 @@ Args: {"data_path": "/path/to/data", "goal": "analysis objective"}`
```
Supervisor prompt update (`internal/think_deep/prompts.go`):
+
```go
// Add to LeadResearcherPrompt:
@@ -359,28 +372,34 @@ Supervisor prompt update (`internal/think_deep/prompts.go`):
For implementing these tools in Go:
**CSV Processing:**
+
- `encoding/csv` (stdlib) - Basic CSV reading
- `github.com/go-gota/gota` - DataFrame operations, statistics
**Pickle Files:**
+
- Python subprocess approach (safest)
- `github.com/nlpodyssey/spago` has some pickle support
**PDF Extraction:**
+
- `github.com/pdfcpu/pdfcpu` - Pure Go, good extraction
- `github.com/unidoc/unipdf` - Commercial, more features
**Office Documents:**
+
- `github.com/unidoc/unioffice` - DOCX, XLSX, PPTX
- `github.com/nguyenthenguyen/docx` - Simpler DOCX-only
**Statistics:**
+
- `gonum.org/v1/gonum/stat` - Statistical functions
- `github.com/montanaflynn/stats` - Descriptive statistics
### 7. Implementation Roadmap
**Phase 1: Document Reading Tools**
+
- [ ] Implement `PDFReadTool` with pdfcpu
- [ ] Implement `DOCXReadTool` with unioffice
- [ ] Implement `PPTXReadTool` with unioffice
@@ -388,22 +407,26 @@ For implementing these tools in Go:
- [ ] Add to SubResearcherToolRegistry
**Phase 2: Basic Data Analysis Tools**
+
- [ ] Implement `CSVAnalysisTool` with gota
- [ ] Add basic statistics: shape, dtypes, missing values, summary stats
- [ ] Add correlation analysis
- [ ] Create LLM-enhanced interpretation mode
**Phase 3: Goal-Directed EDA**
+
- [ ] Create `GoalDirectedEDATool` with LLM planning
- [ ] Implement iterative analysis loop
- [ ] Add hypothesis testing support
**Phase 4: Data Analyst Sub-Agent** (optional)
+
- [ ] Create `DataAnalystAgent` following SubResearcherAgent pattern
- [ ] Implement `conduct_data_analysis` supervisor tool
- [ ] Update supervisor prompt with new capability
**Phase 5: Pickle Support** (optional)
+
- [ ] Implement Python subprocess bridge for pickle inspection
- [ ] Add sandbox/security measures
- [ ] Create `PickleAnalysisTool`
@@ -427,6 +450,7 @@ For implementing these tools in Go:
2. **Optional LLM Enhancement**: Like `SearchTool.SetSummarizer()`, data tools should work standalone but optionally leverage LLM for deeper analysis
3. **Event Bus Integration**: For long-running analysis, emit progress events:
+
```go
bus.Publish(events.Event{
Type: events.EventDataAnalysisProgress,
diff --git a/thoughts/shared/research/2025-12-03_thinkdeep-gap-analysis.md b/thoughts/shared/research/2025-12-03_thinkdeep-gap-analysis.md
index 05cb06f..0444bfa 100644
--- a/thoughts/shared/research/2025-12-03_thinkdeep-gap-analysis.md
+++ b/thoughts/shared/research/2025-12-03_thinkdeep-gap-analysis.md
@@ -10,18 +10,19 @@
The go-research ThinkDeep implementation successfully captures the **core architecture** of the reference (diffusion-based multi-agent research with supervisor coordination), but has **significant gaps** in several areas:
-| Category | Alignment | Criticality |
-|----------|-----------|-------------|
-| Core Architecture | ✅ 90% | - |
-| Workflow Phases | ⚠️ 75% | Medium |
-| Prompts | ⚠️ 70% | High |
-| State Management | ✅ 85% | Low |
-| Tool Handling | ⚠️ 60% | High |
-| Search Strategy | ⚠️ 65% | Medium |
-| Synthesis Process | ⚠️ 70% | High |
-| Configuration | ✅ 90% | Low |
+| Category | Alignment | Criticality |
+| ----------------- | --------- | ----------- |
+| Core Architecture | ✅ 90% | - |
+| Workflow Phases | ⚠️ 75% | Medium |
+| Prompts | ⚠️ 70% | High |
+| State Management | ✅ 85% | Low |
+| Tool Handling | ⚠️ 60% | High |
+| Search Strategy | ⚠️ 65% | Medium |
+| Synthesis Process | ⚠️ 70% | High |
+| Configuration | ✅ 90% | Low |
**Critical Gaps Requiring Immediate Attention:**
+
1. Missing async parallel execution of sub-researchers
2. Missing webpage content summarization in search results
3. Prompt differences affecting research behavior
@@ -33,18 +34,19 @@ The go-research ThinkDeep implementation successfully captures the **core archit
### What Matches ✅
-| Feature | Reference | Go Implementation | Status |
-|---------|-----------|-------------------|--------|
-| 4-phase workflow | Brief → Draft → Diffusion → Final | Brief → Draft → Diffusion → Final | ✅ Match |
-| Supervisor-Worker pattern | Supervisor delegates to sub-agents | Supervisor delegates to sub-researchers | ✅ Match |
-| Diffusion concept | Draft as noisy signal, refine via research | Same conceptual approach | ✅ Match |
-| Max iterations | 15 supervisor iterations | 15 supervisor iterations | ✅ Match |
-| Max concurrent | 3 parallel sub-agents | 3 parallel sub-researchers | ✅ Match |
-| Max search/agent | 5 searches per agent | 5 searches per sub-researcher | ✅ Match |
+| Feature | Reference | Go Implementation | Status |
+| ------------------------- | ------------------------------------------ | --------------------------------------- | -------- |
+| 4-phase workflow | Brief → Draft → Diffusion → Final | Brief → Draft → Diffusion → Final | ✅ Match |
+| Supervisor-Worker pattern | Supervisor delegates to sub-agents | Supervisor delegates to sub-researchers | ✅ Match |
+| Diffusion concept | Draft as noisy signal, refine via research | Same conceptual approach | ✅ Match |
+| Max iterations | 15 supervisor iterations | 15 supervisor iterations | ✅ Match |
+| Max concurrent | 3 parallel sub-agents | 3 parallel sub-researchers | ✅ Match |
+| Max search/agent | 5 searches per agent | 5 searches per sub-researcher | ✅ Match |
### Critical Gap: User Clarification Phase 🔴
**Reference Implementation** (`research_agent_scope.py:37-68`):
+
- Has a `clarify_with_user` stage (currently disabled but implemented)
- Uses structured output `ClarifyWithUser` schema with fields:
- `need_clarification: bool`
@@ -53,6 +55,7 @@ The go-research ThinkDeep implementation successfully captures the **core archit
- Prompt asks LLM to determine if user input needs clarification
**Go Implementation**:
+
- ❌ No clarification phase implemented
- Jumps directly from user query to research brief generation
@@ -61,11 +64,13 @@ The go-research ThinkDeep implementation successfully captures the **core archit
### Gap: Entry Point Separation 🟡
**Reference Implementation**:
+
- `research_agent_full.py` defines the complete workflow
- `research_agent_scope.py` handles scoping (clarification + brief + draft)
- Clear separation between scoping and execution
**Go Implementation**:
+
- All phases combined in `orchestrator/think_deep.go`
- Less modular - harder to customize individual phases
@@ -80,7 +85,9 @@ The go-research ThinkDeep implementation successfully captures the **core archit
**Reference Prompt** (`prompts.py:196-261`) - Key sections missing from Go:
#### Missing: Explicit Diffusion Algorithm Statement
+
Reference has detailed algorithm explanation:
+
```
1. generate the next research questions to address gaps in the draft report
2. **ConductResearch**: retrieve external information to provide concrete delta for denoising
@@ -92,7 +99,9 @@ Reference has detailed algorithm explanation:
Go version has a simplified version but **lacks the critical instruction**: "even if the draft report looks complete, you should continue doing the research until all the research findings are collected."
#### Missing: Scaling Rules
+
Reference (`prompts.py:248-261`):
+
```
Simple fact-finding, lists, rankings → 1 sub-agent
Example: "List top 10 coffee shops in San Francisco" → 1 agent
@@ -104,7 +113,9 @@ Comparisons → 1 sub-agent per element
**Go Implementation**: No explicit scaling rules in supervisor prompt.
#### Missing: "Show Your Thinking" Integration
+
Reference instructs supervisor to use think_tool after each ConductResearch with specific questions:
+
- What key information did I find?
- What's missing?
- Do I have enough?
@@ -129,6 +140,7 @@ Reference instructs supervisor to use think_tool after each ConductResearch with
### Gap: Compress Research Prompt 🟡
**Reference** (`prompts.py:263-308`) includes:
+
- Explicit tool call filtering instructions (include search, exclude think)
- "Report can be as long as necessary"
- "Don't lose any sources - downstream LLM will merge reports"
@@ -139,6 +151,7 @@ Reference instructs supervisor to use think_tool after each ConductResearch with
### Gap: Final Report Prompt 🟡
**Reference** (`prompts.py:326-426`) includes detailed section guidelines:
+
```
- Explicit discussion in simple, clear language
- DO NOT oversimplify - clarify ambiguity
@@ -149,20 +162,21 @@ Reference instructs supervisor to use think_tool after each ConductResearch with
```
**Go Implementation**: Has insightfulness/helpfulness rules but missing:
+
- "DO NOT list facts in bullets" rule
- "Long, verbose sections expected" instruction
- Detailed structure examples (comparison, lists, overview patterns)
### Prompt Alignment Summary
-| Prompt | Reference Lines | Go Approx Lines | Content Match |
-|--------|-----------------|-----------------|---------------|
-| Supervisor | ~65 lines | ~40 lines | 70% |
-| Research Agent | ~45 lines | ~30 lines | 75% |
-| Compress | ~45 lines | ~35 lines | 80% |
-| Final Report | ~100 lines | ~55 lines | 65% |
-| Refine Draft | ~80 lines | ~35 lines | 60% |
-| Research Brief | ~50 lines | ~45 lines | 85% |
+| Prompt | Reference Lines | Go Approx Lines | Content Match |
+| -------------- | --------------- | --------------- | ------------- |
+| Supervisor | ~65 lines | ~40 lines | 70% |
+| Research Agent | ~45 lines | ~30 lines | 75% |
+| Compress | ~45 lines | ~35 lines | 80% |
+| Final Report | ~100 lines | ~55 lines | 65% |
+| Refine Draft | ~80 lines | ~35 lines | 60% |
+| Research Brief | ~50 lines | ~45 lines | 85% |
---
@@ -170,14 +184,14 @@ Reference instructs supervisor to use think_tool after each ConductResearch with
### What Matches ✅
-| State Field | Reference | Go | Status |
-|-------------|-----------|-----|--------|
-| supervisor_messages | ✅ | Messages | ✅ Match |
-| research_brief | ✅ | ResearchBrief | ✅ Match |
-| notes | ✅ (with operator.add) | Notes []string | ✅ Match |
-| raw_notes | ✅ (with operator.add) | RawNotes []string | ✅ Match |
-| draft_report | ✅ | DraftReport | ✅ Match |
-| research_iterations | ✅ | Iterations | ✅ Match |
+| State Field | Reference | Go | Status |
+| ------------------- | ---------------------- | ----------------- | -------- |
+| supervisor_messages | ✅ | Messages | ✅ Match |
+| research_brief | ✅ | ResearchBrief | ✅ Match |
+| notes | ✅ (with operator.add) | Notes []string | ✅ Match |
+| raw_notes | ✅ (with operator.add) | RawNotes []string | ✅ Match |
+| draft_report | ✅ | DraftReport | ✅ Match |
+| research_iterations | ✅ | Iterations | ✅ Match |
### Minor Gap: Message Accumulation Pattern 🟢
@@ -194,6 +208,7 @@ Reference instructs supervisor to use think_tool after each ConductResearch with
### Critical Gap: Parallel Execution of Sub-Researchers 🔴
**Reference Implementation** (`multi_agent_supervisor.py:189-223`):
+
```python
coros = [
researcher_agent.ainvoke({
@@ -206,6 +221,7 @@ tool_results = await asyncio.gather(*coros) # TRUE PARALLELISM
```
**Go Implementation** (`supervisor.go:150-162`):
+
```go
for _, tc := range toolCalls {
result, err := s.executeToolCall(...) // SEQUENTIAL EXECUTION
@@ -214,6 +230,7 @@ for _, tc := range toolCalls {
```
**Impact**: HIGH
+
- Reference executes multiple sub-researchers truly in parallel
- Go version executes them sequentially
- Significantly impacts research speed for comparison queries
@@ -222,6 +239,7 @@ for _, tc := range toolCalls {
### Critical Gap: refine_draft_report Tool Implementation 🔴
**Reference Implementation** (`multi_agent_supervisor.py:225-241`):
+
```python
def refine_draft_report(research_brief, findings, draft_report):
"""Refine draft report - Synthesizes research findings into comprehensive draft"""
@@ -231,6 +249,7 @@ def refine_draft_report(research_brief, findings, draft_report):
```
**Go Implementation** (`think_deep/tools.go:124-183`):
+
- Takes args from tool call (none expected)
- Joins state.Notes correctly
- BUT: Missing the `InjectedToolArg` pattern - reference auto-injects state values
@@ -240,11 +259,13 @@ def refine_draft_report(research_brief, findings, draft_report):
### Gap: Tool Call Format 🟡
**Reference**: Uses LangChain's native tool calling with `bind_tools()`:
+
```python
supervisor_model_with_tools = supervisor_model.bind_tools(supervisor_tools)
```
**Go Implementation**: Uses XML-style tool call parsing:
+
```xml
{"research_topic": "..."}
```
@@ -254,11 +275,13 @@ supervisor_model_with_tools = supervisor_model.bind_tools(supervisor_tools)
### Gap: Think Tool Semantic Handling 🟡
**Reference** (`research_agent.py:178-187`):
+
- Think tool calls are processed synchronously
- Recorded as part of conversation
- Explicitly filtered out during compression
**Go Implementation**:
+
- Think tool acknowledged but treated as no-op
- `FilterThinkToolCalls()` removes them from compression
@@ -271,6 +294,7 @@ supervisor_model_with_tools = supervisor_model.bind_tools(supervisor_tools)
### Critical Gap: Webpage Content Summarization 🔴
**Reference Implementation** (`utils.py:80-111`, `132-156`):
+
```python
def summarize_webpage_content(raw_content: str) -> str:
"""Summarizes web page content using structured output"""
@@ -280,17 +304,20 @@ def summarize_webpage_content(raw_content: str) -> str:
```
The reference:
+
1. Fetches raw page content via Tavily (`include_raw_content=True`)
2. Summarizes each page using LLM with structured output
3. Returns formatted summary with key excerpts
**Go Implementation**:
+
- Uses Brave Search API
- Returns search snippets directly
- ❌ NO webpage content fetching
- ❌ NO content summarization
**Impact**: HIGH
+
- Reference gets much richer content from web pages
- Go version only gets search snippets (typically 150-200 chars)
- Significantly impacts research quality and depth
@@ -298,6 +325,7 @@ The reference:
### Gap: Search Deduplication 🟡
**Reference** (`utils.py:113-130`):
+
```python
def deduplicate_search_results(search_results: List[dict]) -> dict:
unique_results = {}
@@ -329,16 +357,17 @@ def deduplicate_search_results(search_results: List[dict]) -> dict:
**Reference Implementation** uses structured output (Pydantic models) at key decision points:
-| Stage | Reference Schema | Go Equivalent |
-|-------|------------------|---------------|
-| Clarification | `ClarifyWithUser` | ❌ Missing |
+| Stage | Reference Schema | Go Equivalent |
+| -------------- | ------------------ | ------------- |
+| Clarification | `ClarifyWithUser` | ❌ Missing |
| Research Brief | `ResearchQuestion` | ❌ Plain text |
-| Draft Report | `DraftReport` | ❌ Plain text |
-| Compression | `Summary` | ❌ Plain text |
+| Draft Report | `DraftReport` | ❌ Plain text |
+| Compression | `Summary` | ❌ Plain text |
**Go Implementation**: All stages use plain text LLM responses.
**Impact**: HIGH
+
- Structured output prevents hallucination in decisions
- Ensures consistent parsing
- Reference can deterministically route based on schema fields
@@ -347,11 +376,13 @@ def deduplicate_search_results(search_results: List[dict]) -> dict:
### Gap: Draft Refinement Accumulation Strategy 🟡
**Reference** (`multi_agent_supervisor.py:225-241`):
+
- Calls `get_notes_from_tool_calls()` which extracts ALL tool message content
- Joins with newlines
- Every refinement uses ALL accumulated notes
**Go Implementation** (`tools.go:124-183`):
+
- Uses `state.Notes` which already contains compressed findings
- Joins with `\n---\n`
- Similar behavior but slightly different separator
@@ -361,6 +392,7 @@ def deduplicate_search_results(search_results: List[dict]) -> dict:
### Gap: Final Report Input Structure 🟡
**Reference** (`research_agent_full.py:42`):
+
```python
final_report_prompt = prompt.format(
research_brief=state.get("research_brief", ""),
@@ -381,13 +413,13 @@ final_report_prompt = prompt.format(
### What Matches ✅
-| Parameter | Reference | Go | Status |
-|-----------|-----------|-----|--------|
-| max_researcher_iterations | 15 | MaxSupervisorIterations: 15 | ✅ |
-| max_concurrent_researchers | 3 | MaxConcurrentResearch: 3 | ✅ |
-| max searches per agent | 5 (via prompt) | MaxIterations: 5 | ✅ |
-| compress model max_tokens | 32000 | Uses default | ⚠️ Check |
-| final report max_tokens | 40000 | Uses default | ⚠️ Check |
+| Parameter | Reference | Go | Status |
+| -------------------------- | -------------- | --------------------------- | -------- |
+| max_researcher_iterations | 15 | MaxSupervisorIterations: 15 | ✅ |
+| max_concurrent_researchers | 3 | MaxConcurrentResearch: 3 | ✅ |
+| max searches per agent | 5 (via prompt) | MaxIterations: 5 | ✅ |
+| compress model max_tokens | 32000 | Uses default | ⚠️ Check |
+| final report max_tokens | 40000 | Uses default | ⚠️ Check |
### Gap: Model Selection 🟡
@@ -400,6 +432,7 @@ final_report_prompt = prompt.format(
### Gap: Model-Specific Token Limits 🟡
**Reference** explicitly sets:
+
- `compress_model = init_chat_model(model="openai:gpt-5", max_tokens=32000)`
- `writer_model = init_chat_model(model="openai:gpt-5", max_tokens=40000)`
@@ -414,6 +447,7 @@ final_report_prompt = prompt.format(
### Feature: Jupyter Notebook Compatibility 🟢
**Reference** (`multi_agent_supervisor.py:54-65`):
+
```python
try:
import nest_asyncio
@@ -450,6 +484,7 @@ try:
- Use goroutines + WaitGroup for true parallelism
- Location: `supervisor.go:150-162`
- Pattern:
+
```go
var wg sync.WaitGroup
results := make(chan SubResearcherResult, len(conductResearchCalls))
@@ -511,18 +546,18 @@ try:
## 10. Alignment Score by Component
-| Component | Score | Notes |
-|-----------|-------|-------|
-| Core Architecture | 90% | Fundamentally correct |
-| Workflow Phases | 75% | Missing clarification phase |
-| Supervisor Agent | 70% | Missing parallel execution, prompt gaps |
-| Sub-Researcher Agent | 75% | Prompt differences, no page summarization |
-| State Management | 85% | Minor differences in patterns |
-| Tool Handling | 60% | Sequential vs parallel, no structured output |
-| Search Strategy | 65% | No page fetch, no deduplication |
-| Synthesis | 70% | Prompt gaps, no structured output |
-| Configuration | 90% | Model differences |
-| **Overall** | **73%** | Functional but needs optimization |
+| Component | Score | Notes |
+| -------------------- | ------- | -------------------------------------------- |
+| Core Architecture | 90% | Fundamentally correct |
+| Workflow Phases | 75% | Missing clarification phase |
+| Supervisor Agent | 70% | Missing parallel execution, prompt gaps |
+| Sub-Researcher Agent | 75% | Prompt differences, no page summarization |
+| State Management | 85% | Minor differences in patterns |
+| Tool Handling | 60% | Sequential vs parallel, no structured output |
+| Search Strategy | 65% | No page fetch, no deduplication |
+| Synthesis | 70% | Prompt gaps, no structured output |
+| Configuration | 90% | Model differences |
+| **Overall** | **73%** | Functional but needs optimization |
---
@@ -530,16 +565,16 @@ try:
### Reference Files → Go Equivalents
-| Reference File | Go Equivalent | Alignment |
-|----------------|---------------|-----------|
-| `research_agent_full.py` | `architectures/think_deep/think_deep.go` | 80% |
-| `multi_agent_supervisor.py` | `agents/supervisor.go` | 65% |
-| `research_agent.py` | `agents/sub_researcher.go` | 75% |
-| `research_agent_scope.py` | `orchestrator/think_deep.go` (partial) | 70% |
-| `state_multi_agent_supervisor.py` | `think_deep/state.go` | 85% |
-| `state_research.py` | `think_deep/state.go` (partial) | 80% |
-| `prompts.py` | `think_deep/prompts.go` | 70% |
-| `utils.py` | `think_deep/tools.go` + `tools/registry.go` | 55% |
+| Reference File | Go Equivalent | Alignment |
+| --------------------------------- | ------------------------------------------- | --------- |
+| `research_agent_full.py` | `architectures/think_deep/think_deep.go` | 80% |
+| `multi_agent_supervisor.py` | `agents/supervisor.go` | 65% |
+| `research_agent.py` | `agents/sub_researcher.go` | 75% |
+| `research_agent_scope.py` | `orchestrator/think_deep.go` (partial) | 70% |
+| `state_multi_agent_supervisor.py` | `think_deep/state.go` | 85% |
+| `state_research.py` | `think_deep/state.go` (partial) | 80% |
+| `prompts.py` | `think_deep/prompts.go` | 70% |
+| `utils.py` | `think_deep/tools.go` + `tools/registry.go` | 55% |
---