best_engine_ai_helper.api module

api — FastAPI HTTP surface for best-engine-ai-helper.

Exposes the two calls the GUI needs:

  • GET /api/system — detected hardware + compute profile + memory budget.

  • POST /api/recommend — a free-text task -> the same report recommend() produces for the CLI’s report command, as JSON, plus the best PAID model under "cloud" (reference only, on by default; see cli.py’s report --cloud).

A minimal single-page GUI is served at GET /gui (GET / redirects there): it shows the machine’s characteristics and lets you type a task description to get the best local engine(s) for it, alongside the best paid model for comparison. It is bilingual — French by default, English at GET /gui?lang=en — with a header link to switch between the two.

Run the app with any ASGI server:

uvicorn best_engine_ai_helper.api:app --port 8000
# or: best-engine-ai-helper gui

Author

Warith Harchaoui <warith.harchaoui@deraison.ai>

class best_engine_ai_helper.api.RecommendRequest(*, task=None, headroom=0.5, live=False, cloud=True, quality_vs_cost=0.7, cloud_provider=None)[source]

Bases: BaseModel

Body for POST /api/recommend.

Parameters:
cloud: bool
cloud_provider: str | None
headroom: float
live: bool
model_config = {}

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

quality_vs_cost: float
task: str | None
best_engine_ai_helper.api.activity()

Local activity/cost ledger summary (calls, cost, by user/model, errors).

Reads the ledger even when THIS process never called observe.enable() — e.g. a plain uvicorn best_engine_ai_helper.api:app that skips the CLI’s/MCP’s auto-enable — by opening the default-path database read-only in that case, same fallback cli.activity_cmd() uses. Never 404s or errors over “no data”: an unrecorded/empty ledger is a valid, common state.

Return type:

dict[str, Any]

best_engine_ai_helper.api.gui(lang='fr')

Serve the single-page GUI (?lang=en for English, French by default).

Parameters:

lang (str)

Return type:

str

best_engine_ai_helper.api.recommend(body)

Best local engine(s) for body.task on this machine’s hardware.

Also carries the best PAID model under "cloud" unless body.cloud is false — a reference ranking only (no API key, no network call), the same one the CLI’s report --cloud shows; see best_engine_ai_helper.recommend.cloud_recommend().

Parameters:

body (RecommendRequest)

Return type:

dict[str, Any]

best_engine_ai_helper.api.root()

Redirect the bare root path to the browser GUI.

Return type:

fastapi.responses.RedirectResponse

best_engine_ai_helper.api.system()

Detected hardware, compute profile, and usable memory budget.

Return type:

dict[str, Any]