Merge d5743a5a9d into 4583f88626

2026-01-29 21:53:31 -05:00 · 2026-01-29 21:53:31 -05:00 · 9c01fb4882
commit 9c01fb4882
parent 4583f88626 d5743a5a9d
7 changed files with 204 additions and 13 deletions
--- a/docs/querit.md
+++ b/docs/querit.md
@ -0,0 +1,42 @@
+---
+summary: "Querit API setup for web_search"
+read_when:
+  - You want to use Querit for web_search
+  - You need a QUERIT_API_KEY or plan details
+---
+
+# Querit
+
+Moltbot supports Querit as an alternative provider for `web_search`.
+
+## Get an API key
+
+1) Create a Querit account at https://querit.ai/
+2) Generate an API key in your account dashboard.
+3) Store the key in config (recommended) or set `QUERIT_API_KEY` in the Gateway environment.
+
+## Config example
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "querit",
+        querit: {
+          apiKey: "QUERIT_API_KEY_HERE"
+        },
+        maxResults: 5,
+        timeoutSeconds: 30
+      }
+    }
+  }
+}
+```
+
+## Notes
+
+- Querit provides fast web search with structured results (title, URL, snippet).
+- Check the Querit API portal for current limits and pricing.
+
+See [Web tools](/tools/web) for full web_search configuration.
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@ -205,14 +205,14 @@ Notes:
 - `process` is scoped per agent; sessions from other agents are not visible.

 ### `web_search`
-Search the web using Brave Search API.
+Search the web using Brave Search API (default), Perplexity Sonar, or [Querit](https://www.querit.ai).

 Core parameters:
 - `query` (required)
 - `count` (1–10; default from `tools.web.search.maxResults`)

 Notes:
- Requires a Brave API key (recommended: `moltbot configure --section web`, or set `BRAVE_API_KEY`).
+- Requires an API key for your chosen provider (recommended: `moltbot configure --section web`, or set `BRAVE_API_KEY` / `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` / `QUERIT_API_KEY`).
 - Enable via `tools.web.search.enabled`.
 - Responses are cached (default 15 min).
 - See [Web tools](/tools/web) for setup.
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@ -1,16 +1,17 @@
 ---
-summary: "Web search + fetch tools (Brave Search API, Perplexity direct/OpenRouter)"
+summary: "Web search + fetch tools (Brave Search API, Perplexity direct/OpenRouter, Querit)"
 read_when:
  - You want to enable web_search or web_fetch
  - You need Brave Search API key setup
  - You want to use Perplexity Sonar for web search
+  - You want to use Querit for web search
 ---

 # Web tools

 Moltbot ships two lightweight web tools:

- `web_search` — Search the web via Brave Search API (default) or Perplexity Sonar (direct or via OpenRouter).
+- `web_search` — Search the web via Brave Search API (default), Perplexity Sonar (direct or via OpenRouter), or [Querit](https://www.querit.ai).
 - `web_fetch` — HTTP fetch + readable extraction (HTML → markdown/text).

 These are **not** browser automation. For JS-heavy sites or logins, use the
@ -21,6 +22,7 @@ These are **not** browser automation. For JS-heavy sites or logins, use the
 - `web_search` calls your configured provider and returns results.
  - **Brave** (default): returns structured results (title, URL, snippet).
  - **Perplexity**: returns AI-synthesized answers with citations from real-time web search.
+  - **Querit**: returns structured results (title, URL, snippet).
 - Results are cached by query for 15 minutes (configurable).
 - `web_fetch` does a plain HTTP GET and extracts readable content
  (HTML → markdown/text). It does **not** execute JavaScript.
@ -32,8 +34,9 @@ These are **not** browser automation. For JS-heavy sites or logins, use the
 |----------|------|------|---------|
 | **Brave** (default) | Fast, structured results, free tier | Traditional search results | `BRAVE_API_KEY` |
 | **Perplexity** | AI-synthesized answers, citations, real-time | Requires Perplexity or OpenRouter access | `OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY` |
+| **Querit** | Fast, structured results | Traditional search results | `QUERIT_API_KEY` |

-See [Brave Search setup](/brave-search) and [Perplexity Sonar](/perplexity) for provider-specific details.
+See [Brave Search setup](/brave-search), [Perplexity Sonar](/perplexity), and [Querit](/querit) for provider-specific details.

 Set the provider in config:

@ -42,7 +45,7 @@ Set the provider in config:
  tools: {
    web: {
      search: {
-        provider: "brave"  // or "perplexity"
+        provider: "brave"  // or "perplexity" or "querit"
      }
    }
  }
@ -138,6 +141,34 @@ If no base URL is set, Moltbot chooses a default based on the API key source:
 | `perplexity/sonar-pro` (default) | Multi-step reasoning with web search | Complex questions |
 | `perplexity/sonar-reasoning-pro` | Chain-of-thought analysis | Deep research |

+## Using Querit
+
+Querit provides fast web search with structured results.
+
+### Getting a Querit API key
+
+1) Create an account at https://www.querit.ai/
+2) Generate an API key in your account settings.
+
+### Setting up Querit search
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "querit",
+        querit: {
+          apiKey: "QUERIT_API_KEY_HERE"
+        }
+      }
+    }
+  }
+}
+```
+
+**Environment alternative:** set `QUERIT_API_KEY` in the Gateway environment. For a gateway install, put it in `~/.clawdbot/.env`.
+
 ## web_search

 Search the web using your configured provider.
@ -148,6 +179,7 @@ Search the web using your configured provider.
 - API key for your chosen provider:
  - **Brave**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
  - **Perplexity**: `OPENROUTER_API_KEY`, `PERPLEXITY_API_KEY`, or `tools.web.search.perplexity.apiKey`
+  - **Querit**: `QUERIT_API_KEY` or `tools.web.search.querit.apiKey`

 ### Config

--- a/src/agents/tools/web-search.ts
+++ b/src/agents/tools/web-search.ts
@ -17,11 +17,12 @@ import {
  writeCache,
 } from "./web-shared.js";

-const SEARCH_PROVIDERS = ["brave", "perplexity"] as const;
+const SEARCH_PROVIDERS = ["brave", "perplexity", "querit"] as const;
 const DEFAULT_SEARCH_COUNT = 5;
 const MAX_SEARCH_COUNT = 10;

 const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+const QUERIT_SEARCH_ENDPOINT = "https://api.querit.ai/v1/search";
 const DEFAULT_PERPLEXITY_BASE_URL = "https://openrouter.ai/api/v1";
 const PERPLEXITY_DIRECT_BASE_URL = "https://api.perplexity.ai";
 const DEFAULT_PERPLEXITY_MODEL = "perplexity/sonar-pro";
@ -103,6 +104,21 @@ type PerplexitySearchResponse = {

 type PerplexityBaseUrlHint = "direct" | "openrouter";

+type QueritSearchResult = {
+  title?: string;
+  url?: string;
+  snippet?: string;
+  site_name?: string;
+};
+
+type QueritSearchResponse = {
+  error_code?: number;
+  error?: string;
+  results?: {
+    result?: QueritSearchResult[];
+  };
+};
+
 function resolveSearchConfig(cfg?: MoltbotConfig): WebSearchConfig {
  const search = cfg?.tools?.web?.search;
  if (!search || typeof search !== "object") return undefined;
@ -131,6 +147,13 @@ function missingSearchKeyPayload(provider: (typeof SEARCH_PROVIDERS)[number]) {
      docs: "https://docs.molt.bot/tools/web",
    };
  }
+  if (provider === "querit") {
+    return {
+      error: "missing_querit_api_key",
+      message: `web_search (querit) needs an API key. Run \`${formatCliCommand("moltbot configure --section web")}\` to store it, or set QUERIT_API_KEY in the Gateway environment.`,
+      docs: "https://docs.molt.bot/tools/web",
+    };
+  }
  return {
    error: "missing_brave_api_key",
    message: `web_search needs a Brave Search API key. Run \`${formatCliCommand("moltbot configure --section web")}\` to store it, or set BRAVE_API_KEY in the Gateway environment.`,
@ -144,6 +167,7 @@ function resolveSearchProvider(search?: WebSearchConfig): (typeof SEARCH_PROVIDE
      ? search.provider.trim().toLowerCase()
      : "";
  if (raw === "perplexity") return "perplexity";
+  if (raw === "querit") return "querit";
  if (raw === "brave") return "brave";
  return "brave";
 }
@ -193,6 +217,16 @@ function inferPerplexityBaseUrlFromApiKey(apiKey?: string): PerplexityBaseUrlHin
  return undefined;
 }

+function resolveQueritApiKey(search?: WebSearchConfig): string | undefined {
+  if (!search || typeof search !== "object") return undefined;
+  const querit = "querit" in search ? search.querit : undefined;
+  if (!querit || typeof querit !== "object") return undefined;
+  const fromConfig =
+    "apiKey" in querit && typeof querit.apiKey === "string" ? querit.apiKey.trim() : "";
+  const fromEnv = (process.env.QUERIT_API_KEY ?? "").trim();
+  return fromConfig || fromEnv || undefined;
+}
+
 function resolvePerplexityBaseUrl(
  perplexity?: PerplexityConfig,
  apiKeySource: PerplexityApiKeySource = "none",
@ -306,6 +340,44 @@ async function runPerplexitySearch(params: {
  return { content, citations };
 }

+async function runQueritSearch(params: {
+  query: string;
+  apiKey: string;
+  timeoutSeconds: number;
+}): Promise<Array<{ title: string; url: string; snippet: string; siteName: string }>> {
+  const res = await fetch(QUERIT_SEARCH_ENDPOINT, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${params.apiKey}`,
+    },
+    body: JSON.stringify({ query: params.query }),
+    signal: withTimeout(undefined, params.timeoutSeconds * 1000),
+  });
+
+  if (!res.ok) {
+    const detail = await readResponseText(res);
+    throw new Error(`Querit API error (${res.status}): ${detail || res.statusText}`);
+  }
+
+  const data = (await res.json()) as QueritSearchResponse;
+
+  if (data.error_code && data.error_code !== 200) {
+    throw new Error(`Querit API error (${data.error_code}): ${data.error ?? "Unknown error"}`);
+  }
+
+  if (!data.results?.result || !Array.isArray(data.results.result)) {
+    return [];
+  }
+
+  return data.results.result.map((entry) => ({
+    title: entry.title ?? "",
+    url: entry.url ?? "",
+    snippet: entry.snippet ?? "",
+    siteName: entry.site_name ?? resolveSiteName(entry.url) ?? "",
+  }));
+}
+
 async function runWebSearch(params: {
  query: string;
  count: number;
@ -351,6 +423,31 @@ async function runWebSearch(params: {
    return payload;
  }

+  if (params.provider === "querit") {
+    const results = await runQueritSearch({
+      query: params.query,
+      apiKey: params.apiKey,
+      timeoutSeconds: params.timeoutSeconds,
+    });
+
+    const mapped = results.slice(0, params.count).map((entry) => ({
+      title: entry.title,
+      url: entry.url,
+      description: entry.snippet,
+      siteName: entry.siteName,
+    }));
+
+    const payload = {
+      query: params.query,
+      provider: params.provider,
+      count: mapped.length,
+      tookMs: Date.now() - start,
+      results: mapped,
+    };
+    writeCache(SEARCH_CACHE, cacheKey, payload, params.cacheTtlMs);
+    return payload;
+  }
+
  if (params.provider !== "brave") {
    throw new Error("Unsupported web search provider.");
  }
@ -419,7 +516,9 @@ export function createWebSearchTool(options?: {
  const description =
    provider === "perplexity"
      ? "Search the web using Perplexity Sonar (direct or via OpenRouter). Returns AI-synthesized answers with citations from real-time web search."
-      : "Search the web using Brave Search API. Supports region-specific and localized search via country and language parameters. Returns titles, URLs, and snippets for fast research.";
+      : provider === "querit"
+        ? "Search the web using Querit search API. Returns titles, URLs, and snippets for fast research."
+        : "Search the web using Brave Search API. Supports region-specific and localized search via country and language parameters. Returns titles, URLs, and snippets for fast research.";

  return {
    label: "Web Search",
@ -430,7 +529,11 @@ export function createWebSearchTool(options?: {
      const perplexityAuth =
        provider === "perplexity" ? resolvePerplexityApiKey(perplexityConfig) : undefined;
      const apiKey =
-        provider === "perplexity" ? perplexityAuth?.apiKey : resolveSearchApiKey(search);
+        provider === "perplexity"
+          ? perplexityAuth?.apiKey
+          : provider === "querit"
+            ? resolveQueritApiKey(search)
+            : resolveSearchApiKey(search);

      if (!apiKey) {
        return jsonResult(missingSearchKeyPayload(provider));
--- a/src/config/schema.ts
+++ b/src/config/schema.ts
@ -435,7 +435,7 @@ const FIELD_HELP: Record<string, string> = {
    'Text suffix for cross-context markers (supports "{channel}").',
  "tools.message.broadcast.enabled": "Enable broadcast action (default: true).",
  "tools.web.search.enabled": "Enable the web_search tool (requires a provider API key).",
-  "tools.web.search.provider": 'Search provider ("brave" or "perplexity").',
+  "tools.web.search.provider": 'Search provider ("brave", "perplexity", or "querit").',
  "tools.web.search.apiKey": "Brave Search API key (fallback: BRAVE_API_KEY env var).",
  "tools.web.search.maxResults": "Default number of results to return (1-10).",
  "tools.web.search.timeoutSeconds": "Timeout in seconds for web_search requests.",
@ -446,6 +446,7 @@ const FIELD_HELP: Record<string, string> = {
    "Perplexity base URL override (default: https://openrouter.ai/api/v1 or https://api.perplexity.ai).",
  "tools.web.search.perplexity.model":
    'Perplexity model override (default: "perplexity/sonar-pro").',
+  "tools.web.search.querit.apiKey": "Querit API key (fallback: QUERIT_API_KEY env var).",
  "tools.web.fetch.enabled": "Enable the web_fetch tool (lightweight HTTP fetch).",
  "tools.web.fetch.maxChars": "Max characters returned by web_fetch (truncated).",
  "tools.web.fetch.timeoutSeconds": "Timeout in seconds for web_fetch requests.",
--- a/src/config/types.tools.ts
+++ b/src/config/types.tools.ts
@ -336,8 +336,8 @@ export type ToolsConfig = {
    search?: {
      /** Enable web search tool (default: true when API key is present). */
      enabled?: boolean;
-      /** Search provider ("brave" or "perplexity"). */
-      provider?: "brave" | "perplexity";
+      /** Search provider ("brave", "perplexity", or "querit"). */
+      provider?: "brave" | "perplexity" | "querit";
      /** Brave Search API key (optional; defaults to BRAVE_API_KEY env var). */
      apiKey?: string;
      /** Default search results count (1-10). */
@ -355,6 +355,11 @@ export type ToolsConfig = {
        /** Model to use (defaults to "perplexity/sonar-pro"). */
        model?: string;
      };
+      /** Querit-specific configuration (used when provider="querit"). */
+      querit?: {
+        /** API key for Querit (defaults to QUERIT_API_KEY env var). */
+        apiKey?: string;
+      };
    };
    fetch?: {
      /** Enable web fetch tool (default: true). */
--- a/src/config/zod-schema.agent-runtime.ts
+++ b/src/config/zod-schema.agent-runtime.ts
@ -165,7 +165,9 @@ export const ToolPolicySchema = ToolPolicyBaseSchema.superRefine((value, ctx) =>
 export const ToolsWebSearchSchema = z
  .object({
    enabled: z.boolean().optional(),
-    provider: z.union([z.literal("brave"), z.literal("perplexity")]).optional(),
+    provider: z
+      .union([z.literal("brave"), z.literal("perplexity"), z.literal("querit")])
+      .optional(),
    apiKey: z.string().optional(),
    maxResults: z.number().int().positive().optional(),
    timeoutSeconds: z.number().int().positive().optional(),
@ -178,6 +180,12 @@ export const ToolsWebSearchSchema = z
      })
      .strict()
      .optional(),
+    querit: z
+      .object({
+        apiKey: z.string().optional(),
+      })
+      .strict()
+      .optional(),
  })
  .strict()
  .optional();