Say what the include layer exports and what it reads from conf

2026-08-25 16:29:57 -04:00
parent 3fc14d16bf
commit 2c3c88d067
5 changed files with 59 additions and 4 deletions
@@ -43,6 +43,31 @@
 //
 //   Redacted before it is logged, like every other question in this subsystem.
 //
+// EXPORTS
+//   Settings   vv_ai_web_enabled(), vv_ai_web_provider(), vv_ai_web_results_max(),
+//              vv_ai_web_timeout(), vv_ai_web_searx_url(), vv_ai_web_degoog_url(),
+//              vv_ai_web_api_key(), vv_ai_web_ready()
+//              — every one reads conf; none of them reaches the network.
+//   Providers  vv_ai_web_degoog(), vv_ai_web_searxng(), vv_ai_web_brave(), vv_ai_web_tavily()
+//              — one per backend, each returning the same normalised shape.
+//   Transport  vv_ai_web_http(), vv_ai_web_normalise()
+//   Entry      vv_ai_web_search(), vv_ai_web_context()
+//              — what the rest of the subsystem calls. Everything above is reachable but only
+//              these two are meant to be: search() picks the provider, context() formats for
+//              the prompt.
+//
+// CONFIGURATION
+//   master.conf
+//     AI_WEB_SEARCH_ENABLED    master switch; anything but "true" disables the whole subsystem
+//     AI_WEB_SEARCH_PROVIDER   which backend vv_ai_web_search() dispatches to
+//     AI_WEB_SEARCH_RESULTS    result cap handed to the provider
+//     AI_WEB_SEARCH_TIMEOUT    per-request timeout, in seconds
+//
+//   host*.conf — per host, because the endpoint and the key are this machine's
+//     <HOST>_SEARXNG_URL         self-hosted SearXNG base URL
+//     <HOST>_DEGOOG_URL          self-hosted degoogle/Whoogle base URL
+//     <HOST>_WEB_SEARCH_API_KEY  Brave or Tavily key, whichever provider is selected
+//
 // DEPENDS ON
 //   include/ai.php   vv_ai_redact(), vv_conf_vars()
 // ═══════════════════════════════════════════════════════════════════════════════════════════════