web_search_helper.api module

FastAPI HTTP surface (optional [api] extra), and the /gui page.

The production server is search.php; this app is the suite’s HTTP door to the same engine, for agents, scripts and local testing without PHP. Every route has an explicit operation_id: web_search_helper.mcp_server exposes exactly those as MCP tools, so a route renamed here renames its tool.

  • POST /query speaks search.php’s protocol ({lang, q, v?}), so the page’s web-search.js can point at it; /gui does exactly that.

  • POST /search takes a plain question and embeds it server-side, for callers without a browser model.

  • GET /health answers without reading anything (the container’s probe); GET /indexes lists the indexes served; POST /calibrate measures thresholds (never writes); POST /check-online audits a deployed site.

Indexes are read from WSH_DATA_DIR (default ./search-data), one <lang>.php per language, as search.php reads them.

Run it with:

pip install 'web-search-helper[api,embed]'
WSH_DATA_DIR=site/search-data uvicorn web_search_helper.api:app --port 8040

Author: Warith Harchaoui <warithmetics@deraison.ai>

class web_search_helper.api.CalibrateRequest(*, lang, inside, outside)[source]

Bases: BaseModel

Parameters:
inside: list[str]
lang: str
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

outside: list[str]
class web_search_helper.api.CheckOnlineRequest(*, base_url, langs, question='test', data_dir='search-data')[source]

Bases: BaseModel

Parameters:
base_url: str
data_dir: str
langs: list[str]
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

question: str
class web_search_helper.api.QueryRequest(*, lang, q, v=None)[source]

Bases: BaseModel

Parameters:
lang: str
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

q: str
v: list[float] | None
class web_search_helper.api.SearchRequest(*, lang, question, words_only=False, explain=False)[source]

Bases: BaseModel

Parameters:
explain: bool
lang: str
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

question: str
words_only: bool
web_search_helper.api.create_app()[source]
Return type:

fastapi.FastAPI

web_search_helper.api.data_dir()[source]
Return type:

Path

web_search_helper.api.embedder_for(idx)[source]
Parameters:

idx (Index)

web_search_helper.api.get_index(lang)[source]
Parameters:

lang (str)

Return type:

Index

web_search_helper.api.main(argv=None)[source]

Console entry point (web-search-helper-api): serve the HTTP API and /gui.

A click command, so --help answers instead of starting the server. Loopback by default; --host 0.0.0.0 (or WSH_HOST) for a container. The port also reads PORT, as it did before the options existed.

Parameters:

argv (list[str] | None)

Return type:

None