standpoint.api module

FastAPI backend for the Standpoint browser GUI.

This is the thin server behind the single-page GUI: it turns an edited table into a positioning result the browser can render. The heavy lifting stays in the library: positioning() runs the PCA, orientation, colouring, LLM pole naming, and analysis; this module only exposes it over HTTP and serves the static page.

Endpoints

GET / redirect to the GUI. GET /gui the single-page editor + viewer (see webgui.GUI_HTML). GET /api/example a starter table (CSV text) to populate the grid. POST /api/position from an edited table, return the Vega-Lite spec + Markdown + YAML.

Run it with standpoint-gui (installed by the gui extra) or uvicorn standpoint.api:app. It is intentionally not imported by the core package, so the library and CLIs carry no web dependency.

class standpoint.api.PositionRequest(*, table, reference='0', lower='', model='qwen2.5vl:7b')[source]

Bases: BaseModel

Body of POST /api/position: one edited table plus a few options.

Parameters:

table (str)
reference (str)
lower (str)
model (str)

table

The edited comparison table as CSV text (first column = option names).

Type:: str

reference

Row index (as a string) or exact option name to place top-right.

Type:: str

lower

Comma-separated criteria where lower is better (e.g. "Price,Weight").

Type:: str

model

Ollama model used to name the axes and write the analysis.

Type:: str

lower: str

model: str

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

reference: str

table: str

class standpoint.api.PositionResponse(*, vega, markdown, yaml, axes, poles, reference, roles)[source]

Bases: BaseModel

What the browser needs to draw the quadrant and show the write-up.

Parameters:

vega (dict)
markdown (str)
yaml (str)
axes (dict[str, str])
poles (list[str])
reference (str)
roles (dict[str, str])

axes: dict[str, str]

markdown: str

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

poles: list[str]

reference: str

roles: dict[str, str]

vega: dict

yaml: str

class standpoint.api.TableText(*, table)[source]

Bases: BaseModel

A table as CSV text: the body of the XLSX download request.

Parameters:: table (str)

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

table: str

standpoint.api.download_xlsx(req)

Convert the edited table (CSV text) to an .xlsx file for download.

Parameters:: req (TableText) – The current grid serialized to CSV.
Returns:: The workbook bytes with an attachment disposition so the browser saves standpoint.xlsx.
Return type:: Response
Raises:: HTTPException – 400 if the CSV can’t be parsed into a table.

standpoint.api.example()

Return a starter table (CSV text) to populate an empty grid.

Prefer the tracked examples/programming_languages.csv so the GUI stays in sync with it; fall back to the small built-in table when the file isn’t present.

Return type:: str

standpoint.api.gui()

Serve the single-page table editor + quadrant viewer.

Return type:: str

standpoint.api.index()

Redirect the site root to the GUI page.

Return type:: fastapi.responses.RedirectResponse

standpoint.api.main_gui()[source]

Console entry point (standpoint-gui): serve the GUI on localhost:8000.

Return type:: None

standpoint.api.position(req)

Run the full positioning on an edited table and return everything to draw it.

Parameters:: req (PositionRequest) – The edited table and options from the browser.
Returns:: The Vega-Lite spec (rendered client-side by vega-embed), the Markdown interpretation, the YAML dump, and the axis names / poles / roles.
Return type:: PositionResponse
Raises:: HTTPException – 400 if the table is empty or degenerate, or the reference is unknown; the library’s ValueError message is passed straight through to the UI.

async standpoint.api.upload(file=fastapi.File)

Load an uploaded CSV or XLSX table and return it as CSV for the grid.

Parameters:: file (UploadFile) – The uploaded file; .xlsx / .xls are read with pandas (openpyxl), anything else is treated as CSV or Markdown via parse_table.
Returns:: The table as CSV text, ready to populate the editor grid.
Return type:: str
Raises:: HTTPException – 400 if the file can’t be read as a table.