julio-balladares/deepresearch

Purpose and Public Entry Points

DeepResearch is a Python library for AI-assisted OSINT: it turns a topic into a research plan, web searches, collected evidence, iterative gap analysis, and a structured Pydantic result. Primary embedding APIs are run_deep_research and dictionary routing, exported through deepresearch/__init__.py; orchestration is implemented in deepresearch/pipeline.py and API adaptation in deepresearch/router.py.

Request, Result, and Configuration Boundary

Typed request, plan, source, round, and final-result contracts form the internal data boundary in deepresearch/models.py. Runtime limits, provider selection, credentials, cache settings, and endpoint overrides are loaded from environment-backed configuration in deepresearch/config.py. This makes caller-supplied request settings and environment policy distinct from pipeline execution.

Research Orchestration

deepresearch/pipeline.py is the central control flow. It coordinates target interpretation, planning, query generation, search/read collection, source limits/deduplication, multi-round iteration, gap evaluation, and final result assembly. deepresearch/service.py provides the service-facing façade around this pipeline, separating application integration from lower-level stages.

LLM Planning and Provider Abstraction

Planning and synthesis-like AI tasks are divided between deepresearch/planner.py and deepresearch/gaps.py: the former derives target profiles, subquestions, and query plans; the latter determines unresolved research gaps to drive later rounds. deepresearch/llm.py abstracts calls to configured providers—including OpenAI, Anthropic, Gemini, Mistral, DeepSeek, xAI, OpenRouter, Perplexity, and Ollama—behind a common interface. Provider API keys and optional base URLs remain infrastructure concerns rather than pipeline logic.

Evidence Acquisition

deepresearch/search.py is the external search boundary, using SerpApi and a caller-selected Google, Bing, Yahoo, DuckDuckGo, or Yandex engine to turn planned queries into candidate web sources. deepresearch/reader.py is the page-content boundary: it fetches and constrains source text when page reading is enabled. The pipeline retains structured source metadata such as URL, domain, search snippet, associated query/subquestion, and fetch status.

Caching and Iterative Controls

deepresearch/cache.py provides local persistence for LLM responses, search results, and page reads, reducing repeated provider and network calls. Cache location and enablement are controlled via configuration. Iteration is explicitly bounded by settings such as rounds, queries, sources per query, total sources, per-source characters, final context size, and LLM timeout, primarily applied across deepresearch/pipeline.py, deepresearch/search.py, and deepresearch/reader.py.

Runtime and External Dependencies

The package runs as a Python library installed through pyproject.toml, with no indicated standalone server or web UI. Required external services are SerpApi plus one selected LLM provider; Ollama supports a local-model route. Utility cross-cutting behavior resides in deepresearch/utils.py, while tests currently focus on LLM behavior in tests/test_llm.py.