embeddings-cli 0.8.1__tar.gz → 0.9.0__tar.gz

{embeddings_cli-0.8.1 → embeddings_cli-0.9.0}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-11-13
+
+### Added
+
+- **`embeddings export`** — the producer step for the sibling embeddings-tumbler viewer. Turns a surveyed Atlas with its `vectors.npy` into the viewer's data contract (schema version 1): `<name>.json` plus a little-endian float32 block `<name>.f32` of exactly points x dimension x 4 bytes. Previews by default, writes only with `--apply`, refuses an existing `.json` or `.f32` without `--force`, writes each file atomically (under `--force` the old `.json` is removed first, then the block, then the new `.json`, so a failure never leaves a `.json` beside a block that is not its own), and refuses an Atlas with no vectors with a hint naming `embeddings survey`. Provenance copies the Atlas's model, seed, `limitations`, `uncertain` and `params`.
+- `--labels-only` leaves the corpus out: labels are the record ids, no metadata is written, and the file states `text_included: false`.
+- `--group-by <key>` writes each point's `group` from that metadata key (a non-empty string or an integer), so the viewer can colour and name points by group. Records without the key stay ungrouped; a key no record carries is refused; not combinable with `--labels-only`. Without the option no group is written.
+- `provenance.params.corpus` carries only the corpus file's name, never the local path the survey recorded.
+- Endpoint redaction also covers the bare host, `host:port` without credentials and a scheme-less address, ignores case, and no longer replaces a short host name inside a longer word.
+- Both files are staged in full, at their final mode, before anything is removed: a failed forced re-export keeps the old pair, and a failed first export leaves nothing behind.
+- Refused with a plain message instead of writing a file the viewer rejects: NaN or Infinity in metadata or parameters, a seed beyond 2^53 - 1, an empty or non-string record id, an empty model id, and a vector value that overflows float32.
+- `--rotate` is an exact orthogonal rotation onto the set's principal directions (every pairwise distance kept); `--top-k <k>` keeps the first k of them and records `source_dimension`, `directions_kept` and `variance_dropped`. Neither is on unless asked for.
+- `--endpoint-name <name>` writes a route name as `provenance.endpoint`. The Atlas's endpoint URL is never copied — the viewer never lets a gateway address reach a page — and the name must match the contract's allowlist `^[A-Za-z0-9][A-Za-z0-9 _-]{0,63}$` (no dots, colons or slashes, so no hostname, URL or port) or it is refused. Without the flag the field is omitted; an endpoint URL found inside copied provenance strings is replaced with `<embedding endpoint>`.
+- `provenance.source` is `atlas: <folder name>`, never the path as given, so no local absolute path reaches a page; both files get mode 0644 reduced by the umask (never group or other write) instead of `write_atomic`'s 0600, so a static web server running as another user can read them.
+- `tests/_viewer_contract.py` — an independent checker of the viewer's data contract, written in this repo from the contract document.
+
 ## [0.8.1] - 2026-07-20
 
 Review triage for PR #3 — Qodo and SonarCloud.

{embeddings_cli-0.8.1 → embeddings_cli-0.9.0}/CLAUDE.md

@@ -32,7 +32,15 @@ interpretation of the space, not the space itself.
 **The survey surface ships.** All seven verbs are implemented, registered, and
 callable — `survey`, `regions`, `neighbors`, `directions discover` /
 `directions overview`, `compare`, `gaps`, `map` — alongside the introspection
-verbs `whoami`, `learn`, `explain`, `overview`, `doctor`, `cli overview`. The
+verbs `whoami`, `learn`, `explain`, `overview`, `doctor`, `cli overview`.
+`export` is the producer step for the sibling
+[`embeddings-tumbler`](https://github.com/agentculture/embeddings-tumbler)
+viewer: it writes an Atlas with its vectors as the viewer's data contract
+(schema version 1, `<name>.json` + float32 `<name>.f32`). It never copies the
+Atlas's endpoint URL — `provenance.endpoint` is a route name from
+`--endpoint-name` or is omitted — and `tests/_viewer_contract.py` is an
+independent checker of that contract written in this repo, not imported from
+the viewer. The
 package persists an Atlas (`embeddings/atlas/`), talks to an embedding gateway
 (`embeddings/backends/`), and measures stability (`embeddings/measure/`).
 

{embeddings_cli-0.8.1 → embeddings_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: embeddings-cli
-Version: 0.8.1
+Version: 0.9.0
 Summary: Maps the geometry of meaning produced by embedding models — survey a corpus into a semantic landscape, then inspect its regions, neighborhoods, directions, and gaps, and compare models. Backs a Surveyor agent that runs measured experiments against the space and records an evidence-backed Atlas.
 Project-URL: Homepage, https://github.com/agentculture/embeddings-cli
 Project-URL: Issues, https://github.com/agentculture/embeddings-cli/issues
@@ -56,6 +56,7 @@ embeddings directions discover
 embeddings gaps
 embeddings compare model-a model-b
 embeddings map --html
+embeddings export --out view.json
 ```
 
 The goal is not to assign a human-readable meaning to every dimension. That is
@@ -166,6 +167,7 @@ Shipping today:
 | `compare` | Compare two atlases' k-NN overlap and rank agreement on a shared probe set — never by coordinates. |
 | `gaps` | Report corpus-coverage gaps, and (with `--probe`) what active probing shows about the model. |
 | `map` | PCA-project an atlas to 2-D; `--html` writes a self-contained map artifact. |
+| `export` | Write an atlas and its vectors as an [embeddings-tumbler](https://github.com/agentculture/embeddings-tumbler) viewer data file (`<name>.json` + float32 `<name>.f32`); `--labels-only` leaves the corpus text out, `--group-by <key>` writes each point's group from a metadata key (the viewer colours by group), `--rotate` / `--top-k <k>` rotate onto principal directions. The atlas's endpoint URL is never copied — `--endpoint-name` supplies a route name. Dry-run by default; `--apply` commits. |
 
 All originally planned survey-surface verbs are now implemented and listed
 above; nothing remains planned on this surface.

{embeddings_cli-0.8.1 → embeddings_cli-0.9.0}/README.md

@@ -38,6 +38,7 @@ embeddings directions discover
 embeddings gaps
 embeddings compare model-a model-b
 embeddings map --html
+embeddings export --out view.json
 ```
 
 The goal is not to assign a human-readable meaning to every dimension. That is
@@ -148,6 +149,7 @@ Shipping today:
 | `compare` | Compare two atlases' k-NN overlap and rank agreement on a shared probe set — never by coordinates. |
 | `gaps` | Report corpus-coverage gaps, and (with `--probe`) what active probing shows about the model. |
 | `map` | PCA-project an atlas to 2-D; `--html` writes a self-contained map artifact. |
+| `export` | Write an atlas and its vectors as an [embeddings-tumbler](https://github.com/agentculture/embeddings-tumbler) viewer data file (`<name>.json` + float32 `<name>.f32`); `--labels-only` leaves the corpus text out, `--group-by <key>` writes each point's group from a metadata key (the viewer colours by group), `--rotate` / `--top-k <k>` rotate onto principal directions. The atlas's endpoint URL is never copied — `--endpoint-name` supplies a route name. Dry-run by default; `--apply` commits. |
 
 All originally planned survey-surface verbs are now implemented and listed
 above; nothing remains planned on this surface.

{embeddings_cli-0.8.1 → embeddings_cli-0.9.0}/embeddings/cli/__init__.py

@@ -67,6 +67,7 @@ def _build_parser() -> argparse.ArgumentParser:
     from embeddings.cli._commands import directions as _directions_group
     from embeddings.cli._commands import doctor as _doctor_cmd
     from embeddings.cli._commands import explain as _explain_cmd
+    from embeddings.cli._commands import export as _export_cmd
     from embeddings.cli._commands import gaps as _gaps_cmd
     from embeddings.cli._commands import learn as _learn_cmd
     from embeddings.cli._commands import map as _map_cmd
@@ -107,6 +108,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _compare_cmd.register(sub)
     _gaps_cmd.register(sub)
     _map_cmd.register(sub)
+    _export_cmd.register(sub)
     # Register your own noun groups here:
     #   from embeddings.cli._commands import my_noun as _my_noun_group
     #   _my_noun_group.register(sub)