Standpoint

🇫🇷 · 🇬🇧

Standpoint belongs to a collection of libraries called AI Helpers developed for building Artificial Intelligence.

🌍 AI Helpers

Know where each option actually stands.

Standpoint reads a comparison table (options as rows, criteria as columns, numbers in the cells) and produces a 2D positioning map, a short written analysis, and a YAML file with all the coordinates and coefficients. One command does it.

The method is ordinary PCA, which people have used for perceptual maps for a long time. What Standpoint adds is the work you would otherwise do by hand: it orients the map around a reference option, names the axes in plain words (in the language of your columns), colours and labels the points, and writes everything out.

The Promise

Standpoint is local-first by design. Three honest cases:

1. Guaranteed local. Parsing, PCA, orientation, colouring, and figure rendering (via vl-convert) all run on your machine. Your table is never uploaded. There is no telemetry, no account, no SaaS.
2. The one caveat: the local model. Axis names and the written analysis are produced by a local Ollama model on localhost. Ollama downloads the model weights once on first pull; after that it runs offline. Nothing leaves your machine.
3. Your decision. You never have to run the model at all: --no-llm gives you the full map deterministically, with axis names taken from the strongest column at each end and no written narrative.

Documentation

💻 Documentation

🗺️ Landscape

📋 Examples

Input: a table of options and their ratings.

Language	Performance	Ease of Learning	Ecosystem	Concurrency	Type Safety	Job Market	Tooling
Python	2	5	5	2	2	5	4
Rust	5	2	3	5	5	3	4
Go	4	4	4	5	4	4	4
JavaScript	3	4	5	3	2	5	3
…

Output: a positioning map,

plus a Markdown analysis (what the axes mean, where the reference wins, which options stand out, with the loadings and a ranking) and a YAML file with every option's coordinates, role, colour, and original values.

Features

• One command, three-fold deliverable: a figure (PNG + SVG + Vega-Lite JSON), a Markdown interpretation, and a YAML of coordinates + coefficients.
• Readable axes: PCA keeps the axes as weighted sums of your columns; a local model names the four poles as positive qualities, guarded against acronyms, negatives, and antonym pairs.
• Multilingual: axis names, the written analysis, and the figure title come out in the table's own language (English, French, or Spanish), auto-detected from the column names — a French table reads Voitures dans le quadrant.
• Reference-oriented: the option you care about is rotated to the top-right; an all-max reference is placed just past the best competitor rather than as an outlier.
• Four highlighted options: the leader, the weakest overall, and the two challengers that reach furthest toward the top and right poles.
• Polarity aware: mark a lower-is-better column with (↓) (or --lower) and Standpoint names the benefit (Affordable, Portable), never the drawback.
• Deterministic fallback: --no-llm needs no model and no network at all.
• Vision self-check: --check asks a local vision model whether the figure reads correctly (leader top-right, labels legible, legend visible).

Two surfaces, one toolkit — every operation is reachable as:

• Library: import standpoint as sp.
• CLI ×2: standpoint (argparse, always installed) and standpoint-click (click twin) with identical flags.

Installation

Prerequisites — Python 3.10–3.13 and git, cross-platform:

• 🍎 macOS (Homebrew): brew install python git
• 🐧 Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-pip git
• 🪟 Windows (PowerShell): winget install Python.Python.3.12 Git.Git

For axis names and the written analysis, install Ollama and pull the default model once (optional — skip it and use --no-llm):

• 🍎 macOS: brew install ollama — then ollama serve & and ollama pull qwen2.5vl:7b
• 🐧 Ubuntu/Debian: curl -fsSL https://ollama.com/install.sh | sh — then ollama pull qwen2.5vl:7b
• 🪟 Windows: install from ollama.com/download, then ollama pull qwen2.5vl:7b

We recommend a Python environment. If you're new to that, see 🥸 Tech tips.

From PyPI (recommended)

pip install standpoint

From source

git clone https://github.com/warith-harchaoui/standingpoint.git
cd standingpoint
pip install -e .          # or: pip install -r requirements.txt

Or install straight from GitHub (the import name is standpoint):

pip install "git+https://github.com/warith-harchaoui/standingpoint.git@v0.2.0"

Usage

standpoint examples/programming_languages.csv --outdir out
# without installing: python3 -m standpoint examples/programming_languages.csv --outdir out

Two equivalent CLIs are installed: standpoint (argparse) and standpoint-click.

As a library:

import standpoint as sp

pos = sp.positioning("examples/programming_languages.csv")
pos.export("out")                 # writes out/python.{png,svg,white.png,white.svg,vl.json,md,yaml}
print(pos.axes)
# {'x': 'Concurrency ↔ Ecosystem', 'y': 'Safety ↔ Learning'}

Skip the model for a fast, deterministic run (no Ollama needed):

standpoint my_table.csv --no-llm
standpoint my_table.csv --model qwen3:8b

More in EXAMPLES.md.

Input format

A CSV or Markdown table. The first column holds the option names; the rest are numeric criteria on any scale. Higher means better. Empty cells are filled with the column's minimum, so a missing rating never helps an option.

Language	Performance	Ease of Learning	Ecosystem	Type Safety	Job Market
Python	2	5	5	2	5
Rust	5	2	3	5	3
Go	4	4	4	4	4

The first row is the reference and goes to the top right. Change it with --reference "<name>". Mark a lower-is-better column with (↓), e.g. Price (↓), or list it in --lower.

How it works

1. Standardize each criterion to mean 0 and standard deviation 1. PCA is sensitive to scale, so this puts every criterion on equal footing.
2. Run PCA and keep two components. The axes stay as weighted sums of the original columns, so you can read them.
3. Rotate the map so the reference sits top right. If the reference scores top marks on everything, it is placed just past the best competitor on each axis rather than far off on its own.
4. Label it. The four highlighted options (leader, weakest, and the two challengers furthest toward the top and right poles) come straight from the map geometry. Each option takes its own colour from its position. A local model reads the loadings and names the four axis ends, as positive qualities, in your columns' language (English, French, or Spanish).

The figure keeps to a dotted cross for the axes, the pole words at the ends, labels only where they fit, and a legend for the rest.

Notes

• Axis names come from a local model. A guard keeps them positive, distinct, and free of acronyms; a larger --model helps, and --check asks the vision model whether the figure reads correctly.
• Higher is better by default. For a column where lower is better, mark its header with (↓) (Price (↓), Latency (↓)) or pass --lower Price,Latency. Standpoint negates it and names the pole for the benefit ("Affordable", "Portable"), never the drawback.
• Every figure is written twice: a transparent .png / .svg that drops onto any page, and a white-background .white.png / .white.svg for dark surfaces where the near-black labels would otherwise vanish on transparency.
• It is a 2D projection. The axes carry a stated fraction of the variance, so read it as a summary rather than the whole picture.

Examples

Tracked in examples/, input CSV and generated figures:

Table	Language	Leader
programming_languages.csv	en	Python
cloud_providers.csv	en	AWS
laptops.csv	en	MacBook Air (uses Price (↓) / Weight (↓))
voitures_electriques.csv	fr	Tesla Model 3

Development

pip install -r requirements-dev.txt   # or: pip install -e ".[dev]"
python3 -m pytest tests/ -q           # deterministic tests; model-backed ones auto-skip
python3 -m ruff check standpoint tests
python3 -m ruff format --check standpoint tests

The coding standard for this repository is CODING.md; the contribution and versioning policy is in CONTRIBUTING.md.

Credits

PCA perceptual maps are standard (factoextra and FactoMineR in R, prince and pca in Python); using a model to read the components is a newer idea. Colours come from the "Good Colors" palette. Figures are rendered by vl-convert over Vega-Lite.

Author

Warith Harchaoui

License

BSD 3-Clause, the same license as scikit-learn. See LICENSE.