elbow_helper.api module

FastAPI HTTP surface — the web-API door (optional [api] extra).

The third of elbow-helper’s surfaces exposes the pipeline over HTTP so a service can ask “where’s the knee in this curve?” without a Python import. FastAPI + uvicorn live behind the [api] extra, imported lazily here so the core package never pays for a web stack it does not use — the whole point of the package staying at numpy + os-helper for everyone who just wants the library. Every endpoint delegates to elbow_helper._core_cli, so the HTTP behaviour matches the CLI and library exactly.

Each route carries an explicit operation_id (knee/elbow/ diagnostics/locator) — not just OpenAPI hygiene: elbow_helper.mcp_server mounts fastapi-mcp on a copy of this same app and selects exactly these operation ids as the exposed MCP tools, so the id is the tool name an agent calls. Rename a route here and the MCP door renames with it, automatically.

Run it with:

pip install 'elbow-helper[api]'
uvicorn elbow_helper.api:app --reload   # or: python -m elbow_helper.api

Consumes: fastapi (optional), elbow_helper._core_cli. Produces: app (the ASGI application), create_app().

Author

Warith Harchaoui, <warith.harchaoui@deraison.ai>

class elbow_helper.api.CurveRequest(*, x, y=None, curve=None, direction=None, config_overrides=None)[source]

Bases: BaseModel

Request body for /knee and /diagnostics: a curve plus knobs.

y may be omitted, mirroring elbow_helper.robust_knee()’s shorthand where a single series is treated as y-values against an implicit 0, 1, ..., n-1 x axis.

Parameters:

x (list[float])
y (list[float] | None)
curve (str | None)
direction (str | None)
config_overrides (dict | None)

config_overrides: dict | None

curve: str | None

direction: str | None

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

x: list[float]

y: list[float] | None

class elbow_helper.api.DiagnosticsRequest(*, x, y=None, curve=None, direction=None, config_overrides=None, language='en')[source]

Bases: CurveRequest

Request body for /diagnostics: a curve plus the SVG’s language.

Parameters:

x (list[float])
y (list[float] | None)
curve (str | None)
direction (str | None)
config_overrides (dict | None)
language (str)

language: str

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elbow_helper.api.ElbowRequest(*, k, inertia, config_overrides=None)[source]

Bases: BaseModel

Request body for /elbow: an explicit x/y pair, both required.

Parameters:

k (list[float])
inertia (list[float])
config_overrides (dict | None)

config_overrides: dict | None

inertia: list[float]

k: list[float]

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elbow_helper.api.LocatorRequest(*, x, y, sensitivity=1.0, curve=None, direction=None, online=True)[source]

Bases: BaseModel

Request body for /locator: an explicit x/y pair, no config overrides.

Parameters:

x (list[float])
y (list[float])
sensitivity (float)
curve (str | None)
direction (str | None)
online (bool)

curve: str | None

direction: str | None

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

online: bool

sensitivity: float

x: list[float]

y: list[float]

elbow_helper.api.create_app()[source]

Build and return the FastAPI application.

Returns:: The ASGI app with the /knee, /elbow, /diagnostics and /locator routes wired to the shared core.
Return type:: FastAPI

Examples

>>> app = create_app()
>>> [r.path for r in app.routes]
['/openapi.json', '/docs', ..., '/knee', '/elbow', '/diagnostics', '/locator']