docs(search): document Exa as the managed search provider and BYOK option (#5138) - #5215
Conversation
…tion (tinyhumansai#5138) The Web Search page still described managed search as a Parallel-backed proxy. Managed search now resolves to Exa (MANAGED_DEFAULT_PROVIDER in search/tools/web_search.rs, tinyhumansai#5206) and Exa also ships as a bring-your-own-key engine that routes straight to api.exa.ai (tinyhumansai#5207), so the user-facing docs were stale in both directions. - gitbooks/features/native-tools/web-search.md: name Exa as the managed provider, add a Search engines table covering all six engines, and document the Exa BYOK path (key from exa.ai, direct api.exa.ai calls, the exa_search / exa_find_similar / exa_get_contents tools, config.toml and env selection). Note the no-key fallback to managed and the timeline attribution. - gitbooks/features/native-tools/README.md: refresh the toolbelt row. - gitbooks/features/privacy-and-security.md: name Exa in the web-search proxy data-flow row and note that a BYOK key egresses directly. - README.md: mention Exa-powered search and the BYOK option. OpenHuman Managed remains the default engine. Docs only.
|
@coderabbitai review |
✅ Action performedReview finished.
|
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 19 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughDocumentation now describes Exa-powered managed web search, provider selection, bring-your-own-key configuration, fallback behavior, additional Exa tools, and request-routing implications. ChangesWeb Search Documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested labels: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
coderabbitai
Bot
added
the
feature
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9effc3b325
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
| Filename | Overview |
|---|---|
| README.md | Landing-page bullet updated to name Exa as the managed search provider and mention the BYOK option; only mentions Exa BYOK (not Brave/Querit), which is acceptable brevity for a README. |
| gitbooks/features/native-tools/README.md | Web Search row in the tools overview table updated to enumerate all six engine options; no issues. |
| gitbooks/features/native-tools/web-search.md | Comprehensive engine documentation added: six-engine comparison table, Managed and Exa BYOK subsections, config.toml and env-var examples, exa_find_similar deprecation caveat, and corrected SearXNG registration scope. |
| gitbooks/features/privacy-and-security.md | Web search proxy data-flow row updated to name Exa, distinguish BYOK-direct vs. backend-proxied Parallel, and retain the SearXNG note; accurate and clear. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Agent calls web_search_tool] --> B{Selected engine?}
B -->|OpenHuman Managed default| C[OpenHuman Backend]
B -->|Exa BYOK key saved| D[api.exa.ai direct]
B -->|Brave BYOK key saved| E[Brave Search API direct]
B -->|Querit BYOK key saved| F[Querit API direct]
B -->|Parallel selected| G[OpenHuman Backend]
B -->|BYOK key missing| C
B -->|Disabled| H[No search tools registered]
C --> I[Exa — currently]
G --> J[Parallel]
K[SearXNG RPC/MCP client] --> L[SearXNG instance — self-hosted]
Reviews (5): Last reviewed commit: "docs(search): distinguish Parallel tool ..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@gitbooks/features/native-tools/web-search.md`:
- Around line 20-31: Clarify the Disabled engine description to account for the
independently registered SearXNG tool described later: either specify that
Disabled also removes SearXNG search, or narrow the row’s wording to only the
canonical web_search_tool.
- Around line 39-63: Clarify the Exa credential documentation around the
environment-variable and config.toml examples: state that
OPENHUMAN_EXA_API_KEY/EXA_API_KEY and search.exa.api_key are supported, with
environment variables taking precedence. Correct the storage description to
explain that secret encryption stores the key encrypted in config while the OS
keyring protects the encryption master key, not the Exa key itself; warn against
committing plaintext config entries and advise treating environment secrets as
sensitive.
In `@README.md`:
- Line 84: Update the “Batteries included” README text to clearly distinguish
managed web search, which is included with the OpenHuman subscription, from the
bring-your-own Exa key path, which uses the user’s own Exa account and billing.
Keep the surrounding feature descriptions and links unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 6101eaac-c63e-4796-9fea-57be8e8e332c
📒 Files selected for processing (4)
README.mdgitbooks/features/native-tools/README.mdgitbooks/features/native-tools/web-search.mdgitbooks/features/privacy-and-security.md
|
@coderabbitai review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 714df6e82a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
✅ Action performedReview finished.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: efbb540b95
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
senamakel
left a comment
senamakel
left a comment
There was a problem hiding this comment.
Blocking documentation accuracy issues remain on efbb540:
- The Parallel row still presents the required value under “Your own API key,” but
search.parallel.api_keyonly gateseffective_engine(); the request uses a session-authenticated backendIntegrationClient, not that key. Document it as a local enablement gate rather than BYOK authentication/billing. - “The agent always has working search” overstates the missing-key fallback: it resolves to Managed, which is unavailable for local/offline sessions. Qualify the fallback as requiring a backend-authenticated session and direct local providers as requiring a configured key.
- The SearXNG section says OpenHuman registers
searxng_searchfor agents, butbuild_search_tools()never constructs it; production exposure is through the RPC/MCP controller only. Remove the agent-registration claim (or implement it in the owning feature PR).
After those statements match the shipped behavior and the resulting checks are green, this docs-only PR should be safe to approve.
All three blocking documentation inaccuracies were corrected in f63d11f and their review threads are resolved.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f63d11f8a9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cc353378f9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | Family | What it covers | | ||
| | ------ | -------------- | | ||
| | [Web Search](web-search.md) | Search the live web via the managed proxy, or opt into self-hosted SearXNG. | | ||
| | [Web Search](web-search.md) | Search the live web via the managed proxy (powered by Exa), backend-proxied Parallel, your own Exa/Brave/Querit key, or self-hosted SearXNG. | |
There was a problem hiding this comment.
For desktop users reading this agent-facing Native Tools index, listing self-hosted SearXNG as a Web Search route implies that the agent can use it, but build_search_tools() never registers SearxngSearchTool; the detailed page correctly limits it to RPC/MCP. Fresh evidence beyond the prior SearXNG comments is this newly changed index row, which still advertises SearXNG inside the agent's toolbelt; remove it from this row or explicitly label it RPC/MCP-only.
AGENTS.md reference: AGENTS.md:L27-L30
Useful? React with 👍 / 👎.
|
@coderabbitai review |
✅ Action performedReview finished.
|
2 participants
Summary
README.md. The Web Search page still claimed managed search was "a server-side proxy (Parallel)", which has been wrong since feat(search): attribute managed web search to the resolved provider #5206.https://api.exa.ai(never through the managed backend), theexa_search/exa_find_similar/exa_get_contentstools, andconfig.toml/ env selection.gitbooks/features/native-tools/web-search.mdcovering all six engines (Managed, Exa, Parallel, Brave, Querit, Disabled) with "your own API key" and "where your queries go" columns.gitbooks/features/privacy-and-security.md, which is the page a privacy-conscious user reads to learn where a search query egresses.Problem
Two Exa PRs have merged and neither carried the user-facing docs:
feat(search): attribute managed web search to the resolved provider, issue Surface Exa as the provider during tool calls when OpenHuman Managed search is active #5136) made managed search self-attributing and pinnedMANAGED_DEFAULT_PROVIDER = "Exa"insrc/openhuman/search/tools/web_search.rs. The shipped settings copy now reads "Routed through the OpenHuman backend, currently powered by Exa".feat(search): add Exa as a BYOK search provider option, issue Add Exa as a BYOK search provider option alongside Parallel, Brave, and Querit #5137) addedSearchEngine::Exa,search/engines/exa.rs, the threeexa_*agent tools,[search.exa].api_key, andEXA_API_KEY/OPENHUMAN_EXA_API_KEYenv overrides.The GitBook docs and
README.mdhad zero mentions of Exa, and the Web Search page actively told users managed search was Parallel-backed..env.exampleand the internalsrc/openhuman/search/README.mdwere updated in #5207, so the internal docs were correct while the published, user-facing ones were stale and contradictory.Solution
Documented the behavior that actually shipped, verified against
upstream/mainrather than the PR descriptions:resolve_managed_provider()prefers the backend-reported provider and falls back toMANAGED_DEFAULT_PROVIDER = "Exa", anddefault_search_engine()is stillmanaged. So the docs say "currently powered by Exa" rather than hardcoding it as permanent, matching the code comment's intent that a future routing change flows through with no code edit.search/engines/exa.rsregistersweb_search_toolplusexa_search/exa_find_similar/exa_get_contents, all dialinghttps://api.exa.aiwith the user's key. Tool descriptions in the doc are taken from each tool'sdescription()so they cannot drift into marketing copy.## See also/ SearXNG / HTTP-comparison sections are unchanged; the new material is additive.docs/SUMMARY.mddoes not exist in this repo. The GitBook table of contents isgitbooks/SUMMARY.md, andfeatures/native-tools/web-search.mdis already registered there under Available Tools, so no new page and no SUMMARY entry were required.Submission Checklist
N/A: prose-only documentation change, no executable behavior. The behavior described here is already covered by the tests shipped in #5206 and #5207.diff-cover) meet the gate enforced by.github/workflows/ci-lite.yml. Runpnpm test:coverageandpnpm test:rustlocally; PRs below 80% on changed lines will not merge. —N/A: only .md files changed, no instrumentable lines in the diff.docs/TEST-COVERAGE-MATRIX.mdreflect this change (orN/A: behaviour-only change) —N/A: no feature added, removed, or renamed; #5207 already added the Exa rows.## Related—N/A: no matrix feature IDs affected by a docs-only change.exa.aiappears only as documentation hyperlinks and in illustrative config snippets.docs/RELEASE-MANUAL-SMOKE.md) —N/A: documentation only, no release-cut surface touched.Closes #NNNin the## RelatedsectionImpact
useT()UI strings, so no locale files are involved. No em dashes (U+2014) were introduced; the sole occurrence in the touched files is a pre-existing image filename that was not edited.Related
AI Authored PR Metadata (required for Codex/Linear PRs)
Linear Issue
Commit & Branch
docs/GH-5138-exa-search-docsValidation Run
pnpm --filter openhuman-app format:check—N/A: Prettier's scope is the app/ workspace only; the repo root README.md and gitbooks/ are outside it, so this command does not read any changed file.pnpm typecheck—N/A: no TypeScript changed.N/A: no executable code changed.Ran instead, targeted at the changed files: a relative-Markdown-link existence check across all four (all resolve), a U+2014 em-dash scan (no new occurrences), and an HTTP check on the newhttps://exa.ailink (200).N/A: no Rust changed.N/A: no Tauri shell code changed.Validation Blocked
command:noneerror:noneimpact:noneBehavior Changes
Parity Contract
SearchConfig::effective_engine(), and the documented tool set matches the registrations insrc/openhuman/search/engines/exa.rs.Duplicate / Superseded PR Handling
Summary by CodeRabbit