56 lines
2.1 KiB
Markdown
56 lines
2.1 KiB
Markdown
# cloak — module index
|
||
|
||
## Purpose
|
||
|
||
HTTP wrapper around CloakBrowser. Scrapes Google / Bing / DDG SERPs and exposes
|
||
the parsed organic results as JSON. Used as the third-tier fallback for the AI
|
||
platform `web` module when SearXNG + paid rotation return thin results.
|
||
|
||
## Files
|
||
|
||
```
|
||
cloak/
|
||
├── pyproject.toml FastAPI + uvicorn + cloakbrowser deps
|
||
├── README.md User-facing docs
|
||
├── INDEX.md This file (module map)
|
||
├── src/cloak/
|
||
│ ├── __init__.py
|
||
│ ├── config.py Env-driven pydantic settings (CLOAK_* prefix)
|
||
│ ├── schemas.py Request/Response/Stats pydantic models
|
||
│ ├── scraper.py Per-engine HTML scrapers (google/bing/ddg)
|
||
│ ├── browser_pool.py Bounded async pool of CloakBrowser instances
|
||
│ └── server.py FastAPI app — POST /v1/search, GET /health
|
||
├── tests/ pytest test suite
|
||
└── deploy/
|
||
├── Dockerfile FROM cloakhq/cloakbrowser:latest + FastAPI
|
||
└── docker-compose.yml didiAI-cloak on didi-network, port 8770
|
||
```
|
||
|
||
## External contracts
|
||
|
||
| Surface | Path | Method |
|
||
|---|---|---|
|
||
| Search | `/v1/search` | POST |
|
||
| Health | `/health` | GET |
|
||
|
||
Both reachable inside the cluster at `http://didiAI-cloak:8770/`. Host-port
|
||
`127.0.0.1:8770` is exposed only for local debugging on didi12.
|
||
|
||
## State
|
||
|
||
Stateless. No database, no Redis. The browser pool is in-process memory.
|
||
Cold-start (warm 3 browsers) ≈ 8–12 s; from then on each search is 2–4 s
|
||
end-to-end.
|
||
|
||
## Dependencies
|
||
|
||
- `cloakhq/cloakbrowser:latest` Docker base image (bundles stealth Chromium + Xvfb)
|
||
- Outbound TCP to `google.com`, `bing.com`, `html.duckduckgo.com`
|
||
|
||
## Where it's consumed
|
||
|
||
- `ai_platform/modules/web/src/web/search/cloak.py` (CloakHTTPClient) — implemented
|
||
- `ai_platform/modules/web/src/web/orchestrator.py::_run_search_stage` — implemented (tier-3 fallback hook, orchestrator.py:564-599)
|
||
|
||
Backend services (`agent-v3`, `didi-framework`, admin-dashboard) do NOT call
|
||
this service directly.
|