standpoint 0.2.0__tar.gz

standpoint-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Warith Harchaoui.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

standpoint-0.2.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: standpoint
+Version: 0.2.0
+Summary: Know where each option stands: a labelled 2D positioning map from any comparison table.
+Author: Warith Harchaoui
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, Warith Harchaoui.
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Homepage, https://github.com/warith-harchaoui/standingpoint
+Project-URL: Author, https://www.linkedin.com/in/warith-harchaoui
+Keywords: pca,positioning map,perceptual map,quadrant,vega-lite
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: vl-convert-python>=1.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: langdetect>=1.0.9
+Requires-Dist: ollama>=0.3
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Provides-Extra: eval
+Requires-Dist: deepeval>=1.0; extra == "eval"
+Dynamic: license-file
+
+# Standpoint
+
+[🇫🇷](https://github.com/warith-harchaoui/standingpoint/blob/main/LISEZMOI.md) · [🇬🇧](https://github.com/warith-harchaoui/standingpoint/blob/main/README.md)
+
+[![CI](https://github.com/warith-harchaoui/standingpoint/actions/workflows/ci.yml/badge.svg)](https://github.com/warith-harchaoui/standingpoint/actions/workflows/ci.yml) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/warith-harchaoui/standingpoint/blob/main/LICENSE) [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](#) [![Local-first](https://img.shields.io/badge/local--first-Ollama%20%2B%20Vega--Lite-brightgreen.svg)](#the-promise)
+
+`Standpoint` belongs to a collection of libraries called `AI Helpers` developed for building Artificial Intelligence.
+
+[🌍 AI Helpers](https://harchaoui.org/warith/ai-helpers)
+
+[![Standpoint logo](https://raw.githubusercontent.com/warith-harchaoui/standingpoint/main/assets/logo.png)](https://harchaoui.org/warith/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`](https://github.com/vega/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](https://ollama.com) 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](https://harchaoui.org/warith/ai-helpers/docs/standingpoint-doc/)
+
+[🗺️ Landscape](https://github.com/warith-harchaoui/standingpoint/blob/main/LANDSCAPE.md)
+
+[📋 Examples](https://github.com/warith-harchaoui/standingpoint/blob/main/EXAMPLES.md)
+
+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,
+
+![Programming languages positioning map](https://raw.githubusercontent.com/warith-harchaoui/standingpoint/main/examples/programming_languages.png)
+
+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](https://brew.sh)): `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](https://ollama.com) 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](https://ollama.com/download), then `ollama pull qwen2.5vl:7b`
+
+We recommend a Python environment. If you're new to that, see [🥸 Tech tips](https://harchaoui.org/warith/4ml/#install).
+
+### From PyPI (recommended)
+
+```bash
+pip install standpoint
+```
+
+### From source
+
+```bash
+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`):
+
+```bash
+pip install "git+https://github.com/warith-harchaoui/standingpoint.git@v0.2.0"
+```
+
+## Usage
+
+```bash
+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:
+
+```python
+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):
+
+```bash
+standpoint my_table.csv --no-llm
+standpoint my_table.csv --model qwen3:8b
+```
+
+More in [EXAMPLES.md](https://github.com/warith-harchaoui/standingpoint/blob/main/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.
+
+![Electric cars, French input gives a French title and French axis names](https://raw.githubusercontent.com/warith-harchaoui/standingpoint/main/examples/voitures_electriques.png)
+
+## 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
+
+```bash
+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](https://github.com/warith-harchaoui/standingpoint/blob/main/CODING.md);
+the contribution and versioning policy is in [CONTRIBUTING.md](https://github.com/warith-harchaoui/standingpoint/blob/main/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"](https://harchaoui.org/warith/colors/) palette.
+Figures are rendered by [`vl-convert`](https://github.com/vega/vl-convert) over
+[Vega-Lite](https://vega.github.io/vega-lite/).
+
+## Author
+
+[Warith Harchaoui](https://www.linkedin.com/in/warith-harchaoui)
+
+## License
+
+BSD 3-Clause, the same license as scikit-learn. See
+[`LICENSE`](https://github.com/warith-harchaoui/standingpoint/blob/main/LICENSE).

standpoint-0.2.0/README.md

@@ -0,0 +1,246 @@
+# Standpoint
+
+[🇫🇷](https://github.com/warith-harchaoui/standingpoint/blob/main/LISEZMOI.md) · [🇬🇧](https://github.com/warith-harchaoui/standingpoint/blob/main/README.md)
+
+[![CI](https://github.com/warith-harchaoui/standingpoint/actions/workflows/ci.yml/badge.svg)](https://github.com/warith-harchaoui/standingpoint/actions/workflows/ci.yml) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/warith-harchaoui/standingpoint/blob/main/LICENSE) [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](#) [![Local-first](https://img.shields.io/badge/local--first-Ollama%20%2B%20Vega--Lite-brightgreen.svg)](#the-promise)
+
+`Standpoint` belongs to a collection of libraries called `AI Helpers` developed for building Artificial Intelligence.
+
+[🌍 AI Helpers](https://harchaoui.org/warith/ai-helpers)
+
+[![Standpoint logo](https://raw.githubusercontent.com/warith-harchaoui/standingpoint/main/assets/logo.png)](https://harchaoui.org/warith/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`](https://github.com/vega/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](https://ollama.com) 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](https://harchaoui.org/warith/ai-helpers/docs/standingpoint-doc/)
+
+[🗺️ Landscape](https://github.com/warith-harchaoui/standingpoint/blob/main/LANDSCAPE.md)
+
+[📋 Examples](https://github.com/warith-harchaoui/standingpoint/blob/main/EXAMPLES.md)
+
+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,
+
+![Programming languages positioning map](https://raw.githubusercontent.com/warith-harchaoui/standingpoint/main/examples/programming_languages.png)
+
+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](https://brew.sh)): `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](https://ollama.com) 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](https://ollama.com/download), then `ollama pull qwen2.5vl:7b`
+
+We recommend a Python environment. If you're new to that, see [🥸 Tech tips](https://harchaoui.org/warith/4ml/#install).
+
+### From PyPI (recommended)
+
+```bash
+pip install standpoint
+```
+
+### From source
+
+```bash
+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`):
+
+```bash
+pip install "git+https://github.com/warith-harchaoui/standingpoint.git@v0.2.0"
+```
+
+## Usage
+
+```bash
+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:
+
+```python
+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):
+
+```bash
+standpoint my_table.csv --no-llm
+standpoint my_table.csv --model qwen3:8b
+```
+
+More in [EXAMPLES.md](https://github.com/warith-harchaoui/standingpoint/blob/main/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.
+
+![Electric cars, French input gives a French title and French axis names](https://raw.githubusercontent.com/warith-harchaoui/standingpoint/main/examples/voitures_electriques.png)
+
+## 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
+
+```bash
+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](https://github.com/warith-harchaoui/standingpoint/blob/main/CODING.md);
+the contribution and versioning policy is in [CONTRIBUTING.md](https://github.com/warith-harchaoui/standingpoint/blob/main/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"](https://harchaoui.org/warith/colors/) palette.
+Figures are rendered by [`vl-convert`](https://github.com/vega/vl-convert) over
+[Vega-Lite](https://vega.github.io/vega-lite/).
+
+## Author
+
+[Warith Harchaoui](https://www.linkedin.com/in/warith-harchaoui)
+
+## License
+
+BSD 3-Clause, the same license as scikit-learn. See
+[`LICENSE`](https://github.com/warith-harchaoui/standingpoint/blob/main/LICENSE).

standpoint-0.2.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "standpoint"
+description = "Know where each option stands: a labelled 2D positioning map from any comparison table."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Warith Harchaoui" }]
+keywords = ["pca", "positioning map", "perceptual map", "quadrant", "vega-lite"]
+dynamic = ["version"]
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "scikit-learn>=1.3",
+    "vl-convert-python>=1.0",
+    "PyYAML>=6.0",
+    "langdetect>=1.0.9",
+    "ollama>=0.3",
+    "click>=8.1",
+]
+classifiers = [
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.optional-dependencies]
+# Testing + linting kept light so CI installs fast.
+dev = ["pytest>=7.0", "ruff>=0.5"]
+# `deepeval` powers the optional pole-naming evaluation in tests/test_eval.py. It is
+# a separate, heavier extra: the eval is skipped unless both deepeval and a local
+# Ollama model are available, so it runs on a workstation, not in the default CI job.
+eval = ["deepeval>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/warith-harchaoui/standingpoint"
+Author = "https://www.linkedin.com/in/warith-harchaoui"
+
+[project.scripts]
+standpoint = "standpoint:main"
+standpoint-click = "standpoint.click_cli:main_click"
+
+[tool.setuptools]
+packages = ["standpoint"]
+
+[tool.setuptools.dynamic]
+version = { attr = "standpoint.__version__" }
+
+[tool.setuptools.package-data]
+standpoint = ["i18n.yaml"]
+
+[tool.ruff]
+# One source of truth for lint + format (Rule 17). 100 cols matches the prose-heavy
+# docstrings; target the oldest supported interpreter so no newer syntax slips in.
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+# Conservative, high-signal set: pyflakes (F), pycodestyle errors/warnings (E/W),
+# isort (I), bugbear (B), comprehensions (C4), pyupgrade (UP), simplify (SIM).
+select = ["E", "F", "W", "I", "B", "C4", "UP", "SIM"]
+ignore = [
+    "E501",   # line length is enforced by the formatter, not the linter
+    "SIM108", # ternary-over-if/else sometimes hurts readability
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]  # `assert False` is idiomatic in pytest

standpoint-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+