Document deep-research-client for curator evidence-gathering workflows

[dragon-ai-agent]

Context

ai4curation/deep-research-client is now a reusable Python CLI/library for running AI-assisted deep research across multiple providers. This generalizes the one-off deep research integration idea discussed in #36 into a package that curators and knowledge-base maintainers can actually install, script, and include in repository workflows.

aidocs is aimed at practical AI guidance for curators and maintainers of knowledge bases. deep-research-client fits that audience as a research and evidence-gathering component of a curation harness: it is not an ontology editor, validator, or MCP server, but it can generate reviewable, citation-bearing background reports before or alongside human/agent curation work.

Why this belongs in aidocs

• Curators often need repeatable literature/background research for genes, diseases, phenotypes, pathways, ontology terms, and curation tickets.
• Maintainers need practical guidance on provider choice, cost/speed tradeoffs, API key setup, timeouts, caching, and reproducible report artifacts.
• Agentic curation workflows can call the CLI from just, GitHub Actions, scripts, or agent instructions to attach research summaries to issues or PRs.
• The tool aligns with the existing aidocs framing around agent harnesses: it supplies evidence-gathering inputs that still need validation, provenance, and human review.

Capabilities to document

• Multi-provider research: OpenAI Deep Research, Perplexity, Edison Scientific/Falcon, Asta, Consensus, OpenScientist, and Cyberian.
• CLI and Python API usage.
• Markdown reports with citations, optional separate citation files, and publication-style metadata.
• Templates/input files, including Jinja2 templates, for reusable curation research prompts.
• Provider/model selection with cost, speed, and capability metadata.
• Smart caching, plus cache listing/search/browse workflows to avoid repeated costly queries.
• Provider-specific parameters such as allowed domains, recency filters, publication date ranges, and scientific-literature retrieval limits.
• Proxy/custom endpoint support, including CBORG-style setups.

Proposed documentation changes

1. Add deep-research-client to docs/reference/agentic-tools.md, probably under a new Research / evidence gathering section rather than validators, provenance, or MCP servers.
2. Add a curator-facing how-to such as docs/how-tos/use-deep-research-client-for-curation.md covering:
   • install/run via uvx deep-research-client or project dependency setup;
   • configure one provider API key;
   • run a gene, ontology-term, or KB-ticket research query;
   • save Markdown and citations as review artifacts;
   • use templates for repeatable prompts;
   • use caching to control cost and reruns;
   • make clear that generated reports support, but do not replace, curator review.
3. Optionally update docs/examples.md with ai4curation/deep-research-client under agentic infrastructure.
4. Cross-link from Add docs on how to integrate deep research into a repo #36 once this more concrete package-oriented documentation exists.

Acceptance criteria

• aidocs explains where deep-research-client fits in an AI-assisted curation workflow and who should use it.
• The docs include at least one curator-relevant example command that writes a Markdown report and citations.
• The docs describe provider-selection tradeoffs for a curation audience: quick web research, scientific literature review, academic-paper search, and comprehensive deep research.
• The docs include guardrails: reports are advisory, citations should be checked, and downstream curation changes should still pass deterministic validation and human review.
• The reference page links to the GitHub repo and package documentation.