Livrare LOT 1 - Didi

ai_platform/modules/cloak/INDEX.md

@@ -0,0 +1,56 @@
+# 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) — pending
+- `ai_platform/modules/web/src/web/orchestrator.py::_run_search_stage` — pending tier-3 hook
+
+Backend services (`agent-v3`, `didi-framework`, admin-dashboard) do NOT call
+this service directly.