deep-search-agent 0.4.1__tar.gz

deep_search_agent-0.4.1/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtualenv / tooling
+.venv/
+venv/
+.test-venv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.pytype/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Docs (mkdocs build output)
+site/
+public/
+
+# Env
+.env
+.env.*
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Materialized query results / workspace
+workspace/
+
+
+# Manual test scripts against real databases
+snippets/
+
+# codebase
+graphify-out
+
+# Playwright
+test-results/
+playwright-report/

deep_search_agent-0.4.1/CHANGELOG.md

@@ -0,0 +1,327 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.1] - 2026-07-22
+
+### Added
+
+- GitHub Actions `publish` workflow that builds, tests, and uploads the package
+  to PyPI on `v*` tag pushes via PyPI Trusted Publishing (OIDC) — no stored API
+  token. See the "Publishing" section of the README for the one-time PyPI
+  trusted-publisher setup.
+
+### Changed
+
+- Trimmed the source distribution: it now ships only the package, its tests, and
+  `README`/`CHANGELOG`/`LICENSE`, excluding dev tooling (`uv.lock`,
+  `.python-version`), CI config, the docs site, and the benchmark harness.
+
+## [0.4.0] - 2026-07-17
+
+### Added
+
+- Opt-in headless-rendering fallback for `fetch_url`. When static extraction
+  finds no main content — the usual outcome for JavaScript-only pages and bot
+  walls, which previously cost the agent otherwise valid sources — the page is
+  re-fetched through a headless Chromium and extracted again. Enable it with
+  `create_deep_search_agent(enable_js_render_fallback=True)`; `js_render_timeout`
+  (default `30.0` s) bounds the wait for a page to settle ([#23]).
+
+  The fallback is off by default and needs the new `js-render` extra plus the
+  browser binary (`pip install deep-search-agent[js-render]` and
+  `playwright install chromium`). When either is missing, or rendering fails,
+  the tool returns an `ERROR: ...` string as usual instead of raising, so the
+  agent reroutes to another source. Rendering runs on a dedicated worker
+  thread, keeping Playwright's sync API off any live asyncio loop.
+
+## [0.3.2] - 2026-07-17
+
+### Changed
+
+- `fetch_url` now truncates long documents head+tail instead of keeping only
+  the opening. Previously the first `max_content_chars` were kept and the rest
+  discarded, which threw away exactly the sections that carry conclusions,
+  references and the most recent updates. The tool now keeps 60% of the budget
+  from the start and 40% from the end, joined by an explicit marker signalling
+  the omitted middle section. Both cuts snap to the nearest paragraph or
+  sentence boundary in the outer half of their slice, falling back to a hard
+  cut when no boundary qualifies, so neither end reads as a fragment ([#25]).
+
+  The truncation marker changed from a trailing `...(content truncated)` to a
+  mid-document `...(middle section omitted for length)...`. Code matching on
+  the old marker string needs updating.
+
+## [0.3.1] - 2026-07-17
+
+### Fixed
+
+- The rubric grader no longer flags a phantom "incomplete/truncated" gap on
+  long final reports. `deepagents`' `RubricMiddleware` truncates every
+  transcript message it sends to the grader at 4,000 chars, which cut off the
+  tail of the orchestrator's synthesized answer (the "Gaps & limitations"
+  section and the numbered bibliography) and made the grader report a
+  completeness gap that did not exist. The factory now wires a new
+  `DeepSearchRubricMiddleware` — a thin subclass of `RubricMiddleware` that
+  passes the final answer to the grader untruncated while keeping earlier
+  transcript messages (e.g. large tool outputs) bounded ([#22]).
+
+### Added
+
+- `DeepSearchRubricMiddleware` is exported from the package `__all__`.
+- New `on_evaluation` factory parameter that forwards a callback to the
+  evaluator middleware; it is invoked with each `RubricEvaluation` after the
+  grader scores a research cycle (e.g. to log per-criterion verdicts or stream
+  progress). Exceptions it raises are logged and suppressed.
+
+## [0.3.0] - 2026-07-16
+
+### Added
+
+- New `perspective-agent` sub-agent (`build_perspective_subagent` in
+  `subagents.py`), modeled on STORM-style perspective-guided question asking:
+  given the research topic, it runs 1-2 exploratory searches and writes 3-6
+  distinct perspectives (analysis axes, stakeholder viewpoints, dimensions of
+  the problem), each with 2-4 targeted questions, to
+  `/research/perspectives.md`.
+- New `enable_perspectives` factory parameter (default `True`). When enabled,
+  the orchestrator prompt gets a new step 0 that delegates to
+  `perspective-agent` before decomposition and builds todos as
+  perspective → questions pairs instead of a flat sub-question list. Set to
+  `False` to skip the extra delegation cycle for simple, single-axis queries.
+- New `PERSPECTIVE_AGENT_PROMPT` prompt template, exported from the package
+  `__all__` alongside the other sub-agent prompts.
+- `"perspective-agent"` is now a reserved sub-agent name (alongside
+  `search-agent`, `fetch-agent`, `fact-check-agent`): a caller-supplied
+  sub-agent with that name raises `ValueError`, even when
+  `enable_perspectives=False` ([#5]).
+
+### Changed
+
+- **Behavior change on the default path**: `enable_perspectives=True` by
+  default adds one extra delegation cycle (and its token cost) to every run,
+  without changing any function signature. Pass `enable_perspectives=False`
+  to restore the previous single-axis decomposition behavior.
+
+## [0.2.4] - 2026-07-16
+
+### Added
+
+- New `max_query_variants` factory parameter (default `3`, validated as a
+  positive integer). It is threaded into `SEARCH_AGENT_PROMPT_TEMPLATE` the
+  same way `max_search_results_per_query` is, and quoted in the search agent's
+  instructions.
+
+### Changed
+
+- `search-agent` now generates several query variants per sub-question on the
+  happy path — synonyms, broader/narrower terms, an English reformulation, or a
+  different angle — and issues them as parallel `internet_search` calls in the
+  same turn, then deduplicates by URL and keeps the best results across all
+  variants. Previously it ran a single query and only reformulated after an
+  outright failure, so recall depended on the orchestrator's first phrasing
+  ([#6]).
+
+## [0.2.3] - 2026-07-16
+
+### Changed
+
+- The orchestrator's final synthesis is now outline-first. The single
+  free-form SYNTHESIZE step in `ORCHESTRATOR_PROMPT_TEMPLATE` is split into
+  three explicit steps: **outline** (write `report/outline.md` with sections
+  derived from the researched perspectives/sub-questions, depth scaled to the
+  question's complexity), **section-by-section synthesis** with numbered `[n]`
+  citations, and **assembly** into an executive summary, the sections, a
+  required "Gaps & limitations" section, and a numbered "Sources"
+  bibliography. Refinement cycles update the outline and keep the citations and
+  bibliography consistent. `DEEP_SEARCH_RUBRIC` gains criteria grading the
+  executive summary, per-section coverage of every planned
+  perspective/sub-question, the explicit gaps section, and a numbered
+  bibliography consistent with in-text citations. Prompt-only change; no public
+  API change ([#3]).
+
+## [0.2.2] - 2026-07-16
+
+### Added
+
+- `internet_search` (the SearxNG-backed tool built by
+  `create_searxng_search_tool`) now accepts optional per-call `category` and
+  `time_range` arguments, forwarded to the SearxNG JSON API as `categories`
+  and `time_range`. `time_range` is validated against `day`/`week`/`month`/
+  `year` and an invalid value returns an `ERROR:` string without hitting the
+  network. The `search-agent` prompt now instructs the agent to set
+  `time_range` for time-sensitive sub-questions and `category="science"` for
+  academic/research ones, so different sub-questions can target recent or
+  scholarly sources instead of the same undifferentiated web search ([#4]).
+
+### Changed
+
+- `README.md` now shows license, version, and Python-version badges and links
+  to the published documentation on GitHub Pages.
+
+## [0.2.1] - 2026-07-16
+
+### Changed
+
+- The orchestrator, `search-agent`, and `fetch-agent` prompts now maintain and
+  consult a shared source index at `findings/_sources.md`: one line per URL
+  recording its status (`saved` / `failed` / `discarded`) and the associated
+  `findings/<source-slug>.md` file. Sub-agents check it before searching or
+  fetching and append their outcomes, and the orchestrator uses it to avoid
+  re-running queries or re-fetching pages — on refinement cycles it explicitly
+  instructs sub-agents to diversify domains relative to what is already indexed
+  ([#2]). Prompt-only change; no public API change.
+
+## [0.2.0] - 2026-07-16
+
+### Added
+
+- `SessionMetrics`, a thread-safe collector of observability metrics, and an
+  optional `metrics` parameter on `create_deep_search_agent` to wire it in
+  ([#15]). When a `SessionMetrics` instance is passed, observation-only
+  middleware injected into the orchestrator and each built-in sub-agent record,
+  over the whole session:
+  - per research cycle: the orchestrator's tool-call counts, each sub-agent's
+    invocation count, and each sub-agent's tool-call counts;
+  - globally: total tool-call counts (orchestrator + sub-agents), total
+    sub-agent invocations, per-sub-agent execution time (average/min/max), and
+    the overall execution time.
+  - Metrics accumulate for the lifetime of the object (across research cycles
+    and successive invocations of a reused agent) until `reset()` is called;
+    read them through typed properties (`cycles`, `global_tool_calls`,
+    `subagent_stats`, ...) or as a JSON-serializable mapping via `to_dict()`.
+  - New public symbols `SessionMetrics`, `SubagentStats`, and `CycleMetrics`.
+    The sub-agent delegation tool (`task`) is tracked as a sub-agent invocation
+    rather than as an orchestrator tool. The `metrics` parameter defaults to
+    `None` (disabled), so behavior is backward compatible.
+
+## [0.1.4] - 2026-07-15
+
+### Added
+
+- `searxng_rate_limit` and `searxng_budget` parameters on
+  `create_deep_search_agent` ([#13]) to throttle SearxNG usage when sub-agents
+  run searches concurrently through deepagents' thread pool:
+  - `searxng_rate_limit` sets the minimum number of seconds between two SearxNG
+    requests, enforced by a thread-safe min-interval limiter shared by the
+    built-in search tool. If a request would wait longer than `request_timeout`
+    for a free slot, the tool returns an `ERROR:` string instead of performing
+    it.
+  - `searxng_budget` caps the number of SearxNG searches per research cycle;
+    once exhausted the tool returns an `ERROR:` string telling the model no
+    budget is left. The counter is reset at each research-cycle boundary by the
+    new `SearchBudgetResetMiddleware`.
+  - New public symbols `SearchBudget` and `SearchBudgetResetMiddleware`; the
+    `create_searxng_search_tool` factory gains `min_request_interval` and
+    `budget` parameters. Both new factory parameters default to off/unlimited,
+    so behavior is backward compatible.
+
+## [0.1.3] - 2026-07-15
+
+### Added
+
+- `subagents_middleware` parameter on `create_deep_search_agent` ([#11]):
+  extra middleware (e.g. logging, rate limiting) injected into each built-in
+  sub-agent (`search-agent`, `fetch-agent`, `fact-check-agent`) via their
+  `SubAgent.middleware` field. Sub-agents passed via `subagents` are
+  caller-owned and left untouched.
+
+## [0.1.2] - 2026-07-15
+
+### Added
+
+- Explicit `backend` parameter on `create_deep_search_agent` ([#9]): the
+  factory now resolves a single filesystem backend (defaulting to a shared
+  `StateBackend` when none is given, otherwise propagating the caller's
+  instance) and hands it to `create_deep_agent`, so the orchestrator and every
+  sub-agent provably operate on the same virtual filesystem and
+  `findings/<source-slug>.md` files flow back to the orchestrator. Behavior is
+  backward compatible; `backend` is no longer an undocumented pass-through
+  kwarg.
+
+## [0.1.1] - 2026-07-15
+
+### Added
+
+- Opt-in, real end-to-end `benchmark/` suite: runs the agent on five
+  deliberately complex research questions via a live LLM (OpenRouter) and a
+  live SearxNG instance, then grades each answer with an independent
+  LLM-as-a-judge on four 0-5 metrics. Lives outside `src/` and is never
+  shipped with the library; adds a `benchmark` extra (`langchain-openai`).
+- MkDocs (Material + mkdocstrings) documentation site, published to GitHub
+  Pages via the `docs` workflow: home, installation, quickstart, architecture
+  and extending guides, and an auto-generated API reference.
+- `[project.urls]` metadata (Homepage, Documentation, Repository, Issues).
+- `ruff` in the dev dependency group; the codebase is now linted and formatted
+  with it.
+
+### Changed
+
+- Gap-driven refinement cycles ([#1]): on re-entry after a failed rubric
+  grading, the orchestrator prompt now instructs the agent to map the grading
+  feedback to concrete gaps (recorded in `research/gaps.md`), add targeted
+  todos for those gaps only, and re-synthesize reusing the findings already
+  collected — instead of restarting the decomposition from scratch.
+
+### Fixed
+
+- Package build: `dynamic = ["version"]` and the correct `[tool.hatch.version]`
+  path (`src/deep_search_agent/__init__.py`), so `uv build` and `twine check`
+  succeed.
+- Classifiers aligned with `requires-python >= 3.12` (dropped 3.11, added 3.13).
+
+## [0.1.0] - 2026-07-14
+
+Initial release.
+
+### Added
+
+- `create_deep_search_agent` factory: orchestrator + specialized sub-agents
+  (`search-agent`, `fetch-agent`, `fact-check-agent`) + rubric-graded
+  refinement loop, built on LangChain `deepagents`.
+- `internet_search` tool over the SearxNG JSON API
+  (`create_searxng_search_tool`).
+- URL fetch tool extracting HTML with `trafilatura` and PDF with `pypdf`
+  (`create_fetch_url_tool`).
+- `DefaultRubricMiddleware` for automatic rubric injection, and the default
+  `DEEP_SEARCH_RUBRIC`.
+- Configurable research budgets, custom rubrics, extra search tools, and extra
+  sub-agents; all unrecognized keyword arguments pass through to
+  `create_deep_agent`.
+- Typed package (`py.typed`), unit test suite (mocked HTTP/LLM), and opt-in
+  Playwright end-to-end tests.
+
+[#1]: https://github.com/giurlanda/deep-search-agent/issues/1
+[#2]: https://github.com/giurlanda/deep-search-agent/issues/2
+[#3]: https://github.com/giurlanda/deep-search-agent/issues/3
+[#4]: https://github.com/giurlanda/deep-search-agent/issues/4
+[#5]: https://github.com/giurlanda/deep-search-agent/issues/5
+[#6]: https://github.com/giurlanda/deep-search-agent/issues/6
+[#9]: https://github.com/giurlanda/deep-search-agent/issues/9
+[#11]: https://github.com/giurlanda/deep-search-agent/issues/11
+[#13]: https://github.com/giurlanda/deep-search-agent/issues/13
+[#15]: https://github.com/giurlanda/deep-search-agent/issues/15
+[#22]: https://github.com/giurlanda/deep-search-agent/issues/22
+[#23]: https://github.com/giurlanda/deep-search-agent/issues/23
+[#25]: https://github.com/giurlanda/deep-search-agent/issues/25
+[Unreleased]: https://github.com/giurlanda/deep-search-agent/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/giurlanda/deep-search-agent/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/giurlanda/deep-search-agent/compare/v0.3.2...v0.4.0
+[0.3.2]: https://github.com/giurlanda/deep-search-agent/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/giurlanda/deep-search-agent/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/giurlanda/deep-search-agent/compare/v0.2.4...v0.3.0
+[0.2.4]: https://github.com/giurlanda/deep-search-agent/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/giurlanda/deep-search-agent/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/giurlanda/deep-search-agent/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/giurlanda/deep-search-agent/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/giurlanda/deep-search-agent/compare/v0.1.4...v0.2.0
+[0.1.4]: https://github.com/giurlanda/deep-search-agent/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/giurlanda/deep-search-agent/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/giurlanda/deep-search-agent/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/giurlanda/deep-search-agent/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/giurlanda/deep-search-agent/releases/tag/v0.1.0

deep_search_agent-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Giurlanda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deep_search_agent-0.4.1/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: deep-search-agent
+Version: 0.4.1
+Summary: Deep web search agent library built on LangChain deepagents: orchestrator + specialized subagents + iterative rubric-graded refinement.
+Project-URL: Homepage, https://github.com/giurlanda/deep-search-agent
+Project-URL: Documentation, https://giurlanda.github.io/deep-search-agent/
+Project-URL: Repository, https://github.com/giurlanda/deep-search-agent
+Project-URL: Issues, https://github.com/giurlanda/deep-search-agent/issues
+Author-email: Hawk <francesco.giurlanda@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,deep-search,deepagents,langchain,llm,research,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: deepagents>=0.6.5
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: langchain-core<2.0,>=1.0
+Requires-Dist: langchain<2.0,>=1.0
+Requires-Dist: pypdf>=6.14.2
+Requires-Dist: trafilatura>=2.1.0
+Provides-Extra: benchmark
+Requires-Dist: langchain-openai<2.0,>=1.0; extra == 'benchmark'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: js-render
+Requires-Dist: playwright>=1.49; extra == 'js-render'
+Description-Content-Type: text/markdown
+
+# deep-search-agent
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/github/v/tag/giurlanda/deep-search-agent?sort=semver&label=version)](https://github.com/giurlanda/deep-search-agent/tags)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+
+A Python library for deep internet searches (deep search), similar to the deep
+research features of ChatGPT and Claude. Built on top of LangChain's
+[deepagents](https://docs.langchain.com/oss/python/deepagents).
+
+📖 **Documentation:** <https://giurlanda.github.io/deep-search-agent/>
+
+## Architecture
+
+The `create_deep_search_agent` factory returns a deep agent configured with the
+**orchestrator + specialized sub-agents + evaluation loop** pattern:
+
+| Component | Implementation |
+|---|---|
+| Orchestrator | Main agent (`create_deep_agent`): decomposes the query with `write_todos`, delegates, synthesizes with citations |
+| `perspective-agent` | Explores the topic from 3-6 distinct angles (analysis axes, stakeholder viewpoints, dimensions of the problem) before decomposition, saved to `/research/perspectives.md`; enabled by default, toggle with `enable_perspectives=False` |
+| `search-agent` | Web search via SearxNG (+ optional additional search tools), reformulates queries, saves results with their source |
+| `fetch-agent` | Downloads and extracts content from URLs: clean HTML with `trafilatura`, PDFs read with `pypdf`, User-Agent from real browsers |
+| `fact-check-agent` | Verifies claims against multiple independent sources (has both search and fetch) |
+| Shared memory | deepagents virtual filesystem: each sub-agent writes `/findings/<source-slug>.md` with URL, date, and claims |
+| Shared source index | `/findings/_sources.md`: one line per URL (`saved` / `failed` / `discarded`) that every agent consults and appends to, so searches and fetches are not duplicated across cycles |
+| Evaluator/critic | `RubricMiddleware` (beta): an LLM grader evaluates the answer against a rubric and re-runs the orchestrator up to `max_research_cycles` cycles |
+
+Each sub-agent runs with an isolated context: raw page content does not pollute
+the orchestrator's memory; only the synthetic reports and the files in
+`findings/` bubble up.
+
+## Installation
+
+```bash
+uv sync            # from the repository
+# or, as a dependency:
+uv add deep-search-agent
+```
+
+Requires Python ≥ 3.12. The search tool needs a reachable
+[SearxNG](https://docs.searxng.org/) instance with the JSON format enabled
+(default: `http://localhost:8888`).
+
+## Quickstart
+
+```python
+from deep_search_agent import create_deep_search_agent
+
+agent = create_deep_search_agent(
+    model="anthropic:claude-sonnet-4-6",
+    searxng_base_url="http://localhost:8888",
+    max_research_cycles=3,
+)
+
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "State of the art in quantum error correction in 2026?"}]},
+    config={"configurable": {"thread_id": "research-1"}},
+)
+print(result["messages"][-1].content)
+```
+
+The default evaluation rubric (`DEEP_SEARCH_RUBRIC`) is injected automatically:
+the refinement loop works with no configuration. For an ad-hoc rubric, pass it
+in the invoke state (`{"rubric": "- ..."}`) or to the factory
+(`rubric="- ..."`).
+
+## Factory parameters
+
+Deep-search-specific parameters:
+
+| Parameter | Default | Description |
+|---|---|---|
+| `model` | — (required) | Orchestrator model; inherited by sub-agents and the rubric grader |
+| `max_research_cycles` | `3` | Maximum refinement cycles of the evaluator loop (and budget cited in the orchestrator prompt) |
+| `max_query_variants` | `3` | Number of parallel query variants the search agent issues per sub-question (synonyms, broader/narrower terms, English variants) to widen recall |
+| `max_search_results_per_query` | `5` | Maximum results per search query |
+| `max_urls_to_scrape_per_cycle` | `3` | Maximum URLs to fetch per research cycle |
+| `searxng_base_url` | `http://localhost:8888` | URL of the SearxNG instance |
+| `searxng_engines` | `None` | List of SearxNG engines to restrict the search to |
+| `searxng_rate_limit` | `None` | Minimum seconds between SearxNG requests (thread-safe, shared across concurrent searches); `None` disables rate limiting |
+| `searxng_budget` | `None` | Maximum SearxNG searches per research cycle; when exhausted the tool returns an `ERROR:` telling the model no budget is left. `None` means unlimited |
+| `request_timeout` | `15.0` | HTTP timeout (s) for search and fetch |
+| `max_content_chars_per_page` | `20000` | Truncation of extracted content per page |
+| `enable_js_render_fallback` | `False` | Re-fetch pages whose static HTML yields no content through a headless Chromium, recovering JavaScript-only pages and bot walls. Requires the `js-render` extra plus `playwright install chromium` |
+| `js_render_timeout` | `30.0` | Seconds the headless renderer waits for a page to settle; ignored unless the fallback is enabled |
+| `search_tools` | `None` | Additional search tools for search-agent, fact-check-agent, and perspective-agent (e.g. Tavily, RAG retrieval) |
+| `enable_perspectives` | `True` | Adds `perspective-agent` and instructs the orchestrator to delegate to it before decomposing the query. Set `False` for simple queries where a single-axis decomposition is sufficient |
+| `rubric` | `DEEP_SEARCH_RUBRIC` | Custom evaluation rubric |
+| `auto_rubric` | `True` | Auto-inject the rubric into the state on every invoke |
+| `on_evaluation` | `None` | Callback invoked with each `RubricEvaluation` after the grader scores a cycle (e.g. to log verdicts); exceptions are logged and suppressed |
+| `subagents_middleware` | `()` | Extra middleware injected into each built-in sub-agent (perspective-agent, search-agent, fetch-agent, fact-check-agent) |
+| `subagents` | `None` | Extra sub-agents, added to the built-in ones |
+| `backend` | `StateBackend()` | Filesystem backend shared by the orchestrator and every sub-agent |
+
+All other keyword arguments (`tools`, `checkpointer`, `store`, `skills`,
+`interrupt_on`, ...) are passed through unchanged to `create_deep_agent`.
+
+## Extensions
+
+### Adding a retrieval agent (RAG) over the internal knowledge base
+
+```python
+rag_agent = {
+    "name": "rag-agent",
+    "description": "Retrieval over the internal company knowledge base",
+    "system_prompt": "Search the vector store and save results to findings/.",
+    "tools": [my_vector_store_tool],
+}
+
+agent = create_deep_search_agent(
+    model="anthropic:claude-sonnet-4-6",
+    subagents=[rag_agent],
+)
+```
+
+### Adding search engines
+
+```python
+from langchain_tavily import TavilySearch
+
+agent = create_deep_search_agent(
+    model="anthropic:claude-sonnet-4-6",
+    search_tools=[TavilySearch(max_results=5)],
+)
+```
+
+### Persistent backend for findings
+
+```python
+from deepagents.backends import FilesystemBackend
+
+agent = create_deep_search_agent(
+    model="anthropic:claude-sonnet-4-6",
+    backend=FilesystemBackend(root_dir="./research", virtual_mode=True),
+)
+```
+
+## Testing
+
+```bash
+uv run pytest
+```
+
+The unit tests require neither network nor API keys: HTTP and LLM are simulated.
+
+## Publishing
+
+Releases are published to [PyPI](https://pypi.org/project/deep-search-agent/) by
+the [`publish` workflow](.github/workflows/publish.yml), triggered on pushing a
+`v*` tag. It uses **PyPI Trusted Publishing** (OIDC), so no API token is stored.
+
+One-time setup on PyPI (Account → Publishing → *Add a pending publisher*):
+
+| Field | Value |
+|---|---|
+| PyPI project name | `deep-search-agent` |
+| Owner | `giurlanda` |
+| Repository name | `deep-search-agent` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+To cut a release: bump `__version__` in
+[`src/deep_search_agent/__init__.py`](src/deep_search_agent/__init__.py), update
+the `CHANGELOG`, then push a matching tag (e.g. `git tag v0.4.1 && git push
+origin v0.4.1`). Build locally with `uv build` and validate with
+`uvx twine check dist/*`.
+
+## Package structure
+
+```
+src/deep_search_agent/
+├── factory.py       # create_deep_search_agent
+├── prompts.py       # orchestrator/sub-agent prompts + default rubric
+├── middleware.py    # DefaultRubricMiddleware (rubric auto-injection)
+├── subagents.py     # perspective/search/fetch/fact-check agent definitions
+└── tools/
+    ├── search.py    # SearxNG tool
+    └── fetch.py     # URL fetch tool (trafilatura + pypdf)
+```