Timmy-time-dashboard/docs/research/deerflow-evaluation.md

DeerFlow Evaluation — Autonomous Research Orchestration Layer

Status: No-go for full adoption · Selective borrowing recommended Date: 2026-03-23 Issue: #1283 (spawned from #1275 screenshot triage) Refs: #972 (Timmy research pipeline) · #975 (ResearchOrchestrator)

---

What Is DeerFlow?

DeerFlow (bytedance/deer-flow) is an open-source "super-agent harness" built by ByteDance on top of LangGraph. It provides a production-grade multi-agent research and code-execution framework with a web UI, REST API, Docker deployment, and optional IM channel integration (Telegram, Slack, Feishu/Lark).

• Stars: ~39,600 · License: MIT
• Stack: Python 3.12+ (backend) · TypeScript/Next.js (frontend) · LangGraph runtime
• Entry point: http://localhost:2026 (Nginx reverse proxy, configurable via PORT)

---

Research Questions — Answers

1. Agent Roles

DeerFlow uses a two-tier architecture:

Role	Description
Lead Agent	Entry point; decomposes tasks, dispatches sub-agents, synthesizes results
Sub-Agent (general-purpose)	All tools except task; spawned dynamically
Sub-Agent (bash)	Command-execution specialist

The lead agent runs through a 12-middleware chain in order: thread setup → uploads → sandbox → tool-call repair → guardrails → summarization → todo tracking → title generation → memory update → image injection → sub-agent concurrency cap → clarification intercept.

Concurrency: up to 3 sub-agents in parallel (configurable), 15-minute default timeout each, structured SSE event stream (task_started / task_running / task_completed / task_failed).

Mapping to Timmy personas: DeerFlow's lead/sub-agent split roughly maps to Timmy's orchestrator + specialist-agent pattern. DeerFlow doesn't have named personas — it routes by capability (tools available to the agent type), not by identity. Timmy's persona system is richer and more opinionated.

---

2. API Surface

DeerFlow exposes a full REST API at port 2026 (via Nginx). No authentication by default.

Core integration endpoints:

Endpoint	Method	Purpose
POST /api/langgraph/threads		Create conversation thread
POST /api/langgraph/threads/{id}/runs		Submit task (blocking)
POST /api/langgraph/threads/{id}/runs/stream		Submit task (streaming SSE/WS)
GET /api/langgraph/threads/{id}/state		Get full thread state + artifacts
GET /api/models		List configured models
GET /api/threads/{id}/artifacts/{path}		Download generated artifacts
DELETE /api/threads/{id}		Clean up thread data

These are callable from Timmy with httpx — no special client library needed.

---

3. LLM Backend Support

DeerFlow uses LangChain model classes declared in config.yaml.

Documented providers: OpenAI, Anthropic, Google Gemini, DeepSeek, Doubao (ByteDance), Kimi/Moonshot, OpenRouter, MiniMax, Novita AI, Claude Code (OAuth).

Ollama: Not in official documentation, but works via the langchain_openai:ChatOpenAI class with base_url: http://localhost:11434/v1 and a dummy API key. Community-confirmed (GitHub issues #37, #1004) with Qwen2.5, Llama 3.1, and DeepSeek-R1.

vLLM: Not documented, but architecturally identical — vLLM exposes an OpenAI-compatible endpoint. Should work with the same base_url override.

Practical caveat: The lead agent requires strong instruction-following for consistent tool use and structured output. Community findings suggest ≥14B parameter models (Qwen2.5-14B minimum) for reliable orchestration. Our current qwen3:14b should be viable.

---

4. License

MIT License — Copyright 2025 ByteDance Ltd. and DeerFlow Authors 2025–2026.

Permissive: use, modify, distribute, commercialize freely. Attribution required. No warranty.

Compatible with Timmy's use case. No CLA, no copyleft, no commercial restrictions.

---

5. Docker Port Conflicts

DeerFlow's Docker Compose exposes a single host port:

Service	Host Port	Notes
Nginx (entry point)	2026 (configurable via PORT)	Only externally exposed port
Frontend (Next.js)	3000	Internal only
Gateway API	8001	Internal only
LangGraph runtime	2024	Internal only
Provisioner (optional)	8002	Internal only, Kubernetes mode only

Timmy's existing Docker Compose exposes:

• 8000 — dashboard (FastAPI)
• 8080 — openfang (via openfang profile)
• 11434 — Ollama (host process, not containerized)

No conflict. Port 2026 is not used by Timmy. DeerFlow can run alongside the existing stack without modification.

---

Full Capability Comparison

Capability	DeerFlow	Timmy (research.py)
Multi-agent fan-out	✅ 3 concurrent sub-agents	❌ Sequential only
Web search	✅ Tavily / InfoQuest	✅ research_tools.py
Web fetch	✅ Jina AI / Firecrawl	✅ trafilatura
Code execution (sandbox)	✅ Local / Docker / K8s	❌ Not implemented
Artifact generation	✅ HTML, Markdown, slides	❌ Markdown report only
Document upload + conversion	✅ PDF, PPT, Excel, Word	❌ Not implemented
Long-term memory	✅ LLM-extracted facts, persistent	✅ SQLite semantic cache
Streaming results	✅ SSE + WebSocket	❌ Blocking call
Web UI	✅ Next.js included	✅ Jinja2/HTMX dashboard
IM integration	✅ Telegram, Slack, Feishu	✅ Telegram, Discord
Ollama backend	✅ (via config, community-confirmed)	✅ Native
Persona system	❌ Role-based only	✅ Named personas
Semantic cache tier	❌ Not implemented	✅ SQLite (Tier 4)
Free-tier cascade	❌ Not applicable	🔲 Planned (Groq, #980)
Python version requirement	3.12+	3.11+
Lock-in	LangGraph + LangChain	None

---

Integration Options Assessment

Option A — Full Adoption (replace research.py)

Verdict: Not recommended.

DeerFlow is a substantial full-stack system (Python + Node.js, Docker, Nginx, LangGraph). Adopting it fully would:

• Replace Timmy's custom cascade tier system (SQLite cache → Ollama → Claude API → Groq) with a single-tier LangChain model config
• Lose Timmy's persona-aware research routing
• Add Python 3.12+ dependency (Timmy currently targets 3.11+)
• Introduce LangGraph/LangChain lock-in for all research tasks
• Require running a parallel Node.js frontend process (redundant given Timmy's own UI)

Option B — Sidecar for Heavy Research (call DeerFlow's API from Timmy)

Verdict: Viable but over-engineered for current needs.

DeerFlow could run as an optional sidecar (docker compose --profile deerflow up) and Timmy could delegate multi-agent research tasks via POST /api/langgraph/threads/{id}/runs. This would unlock parallel sub-agent fan-out and code-execution sandboxing without replacing Timmy's stack.

The integration would be ~50 lines of httpx code in a new DeerFlowClient adapter. The ResearchOrchestrator in research.py could route tasks above a complexity threshold to DeerFlow.

Barrier: DeerFlow's lack of default authentication means the sidecar would need to be network-isolated (internal Docker network only) or firewalled. Also, DeerFlow's Ollama integration is community-maintained, not officially supported — risk of breaking on upstream updates.

Option C — Selective Borrowing (copy patterns, not code)

Verdict: Recommended.

DeerFlow's architecture reveals concrete gaps in Timmy's current pipeline that are worth addressing independently:

DeerFlow Pattern	Timmy Gap to Close	Implementation Path
Parallel sub-agent fan-out	Research is sequential	Add asyncio.gather() to ResearchOrchestrator for concurrent query execution
SummarizationMiddleware	Long contexts blow token budget	Add a context-trimming step in the synthesis cascade
TodoListMiddleware	No progress tracking during long research	Wire into the dashboard task panel
Artifact storage + serving	Reports are ephemeral (not persistently downloadable)	Add file-based artifact store to research.py (issue #976 already planned)
Skill modules (Markdown-based)	Research templates are .md files — same pattern	Already done in skills/research/
MCP integration	Research tools are hard-coded	Add MCP server discovery to research_tools.py for pluggable tool backends

---

Recommendation

No-go for full adoption or sidecar deployment at this stage.

Timmy's ResearchOrchestrator already covers the core pipeline (query → search → fetch → synthesize → store). DeerFlow's value proposition is primarily the parallel sub-agent fan-out and code-execution sandbox — capabilities that are useful but not blocking Timmy's current roadmap.

Recommended actions:

1. Close the parallelism gap (high value, low effort): Refactor ResearchOrchestrator to execute queries concurrently with asyncio.gather(). This delivers DeerFlow's most impactful capability without any new dependencies.

2. Re-evaluate after #980 and #981 are done: Once Timmy has the Groq free-tier cascade and a sovereignty metrics dashboard, we'll have a clearer picture of whether the custom orchestrator is performing well enough to make DeerFlow unnecessary entirely.

3. File a follow-up for MCP tool integration: DeerFlow's use of langchain-mcp-adapters for pluggable tool backends is the most architecturally interesting pattern. Adding MCP server discovery to research_tools.py would give Timmy the same extensibility without LangGraph lock-in.

4. Revisit DeerFlow's code-execution sandbox if #978 (Paperclip task runner) proves insufficient: DeerFlow's sandboxed bash tool is production-tested and well-isolated. If Timmy's task runner needs secure code execution, DeerFlow's sandbox implementation is worth borrowing or wrapping.

---

Follow-up Issues to File

Issue	Title	Priority
New	Parallelize ResearchOrchestrator query execution (asyncio.gather)	Medium
New	Add context-trimming step to synthesis cascade	Low
New	MCP server discovery in research_tools.py	Low
#976	Semantic index for research outputs (already planned)	High