Simulation: Embedding

Contrastive training forecast for embedding models. Audits pair/triplet geometry, predicts contrastive loss trajectory, and flags hard negatives without updating weights. Saved runs live under ~/.aquin/runs/ — list simulation for IDs, load simulation to reopen a card, compare simulation to diff two embed forecasts (geometry, margins, loss trajectory). Requires embedding mode.

Prerequisiteaquin session start --id my-run --model gte-small

6 commands

aquin pairs-generate

agent tool: embed_pairs_generate

Generates contrastive training data for a topic: pairs (anchor/positive), triplets (anchor/positive/negative), or SimCSE-style duplicates. Writes JSON to cwd.

Flag	Description
--topic*	Subject for generated examples.
--mode	pairs, triplet, or simcse (default: pairs).
--count	Number of examples (default: 8).
--output	Output filename.

example

aquin dataset-analyze

agent tool: analyze_embed_training_dataset

Pair quality report for contrastive data: margin violations, duplicate anchors, negative hardness, and mode-specific checks (triplet margin, SimCSE duplicate ratio).

Flag	Description
--pairs	Path to pairs/triplets JSON.
--mode	pairs, triplet, or simcse.
--margin / --temperature / --batch_size	Training hyperparameters for audit thresholds.

example

aquin simulate

agent tool: run_embed_simulation

Contrastive fine-tuning forecast: geometry audit, predicted loss trajectory, hard-negative analysis. Pass pairs file + config, or a full payload JSON. No weight updates.

Flag	Description
--pairs	Path to pairs/triplets JSON.
--config	YAML/JSON with mode, lr, epochs, margin, temperature.
--payload	Full simulate request JSON (alternative to pairs+flags).
--mode	pairs, triplet, or simcse.
--lr / --epochs / --batch_size / --margin / --temperature	Inline hyperparameters.

example

Use --payload for pre-built JSON fixtures (e.g. simulate-triplets.gte-small.json).

aquin list simulation

agent tool: list_simulation_runs

Lists saved embed simulation runs (same command as LLM, filtered by mode on disk).

example

Run IDs are printed at the end of aquin simulate and stored under ~/.aquin/runs/<id>/. Legacy alias: aquin list-runs.

aquin load simulation

agent tool: load_simulation_run

Load a saved embed simulation by run ID.

Flag	Description
--run_id*	Run ID.

example

Legacy alias: aquin load-run.

aquin compare simulation

agent tool: compare_simulations

Compare two embed simulation runs: loss trajectory, geometry metrics, triplet margin satisfaction.

Flag	Description
--run_id_a*	First run.
--run_id_b*	Second run.
--label_a / --label_b	Display labels.
--output json	Raw JSON stdout.

example

Legacy alias: aquin compare-runs.