# TraceVox Research — Practical Guide

This guide covers exploring published research (works for anyone, nothing to
install) and running your own research (runner/CLI: `pip install tracevox-ai`;
backend self-hosted).

## 1. Explore published research (no installation)

Open https://tracevox.ai/research and pick an experiment. A public experiment
page provides:
- aggregate results per evaluation run (success rate, mean return, safety
  failure rate), each labeled SEEN IN TRAINING or HELD OUT relative to the
  policy's training corruption;
- recorded episode replays: step-by-step ground truth, the clean observation,
  the corrupted observation actually delivered to the policy, the full action
  probability distribution, value estimate, reward, and outcome;
- the provenance manifest (package versions, seeds, checkpoints, commits);
- citation metadata (BibTeX / plain text; stable URL, no invented DOI).

Machine access: fetch the same data as JSON from
/public-research/index.json and
/public-research/experiments/{slug}/{experiment,manifest,citation}.json and
/public-research/experiments/{slug}/episodes/{episode_id}.json.

Exploring evidence never requires the private Research API, a runner, or an
account.

## 2. Run your own research — fully local/offline, NO ACCOUNT

Three usage modes, never confused: TraceVox Cloud (hosted control plane at
tracevox.ai — account required, experiments still run on YOUR compute);
Local/Offline (below — no account, no cloud, offline-capable); Explore
Published Research (tracevox.ai/research — no account, no install).

The one-command local environment (backend + persistent storage + UI):

    pip install "tracevox-ai[rl]"
    tracevox local start
    # browser opens http://127.0.0.1:8321/lab — Compute → Generate pairing
    # code (local) → tracevox connect --server http://127.0.0.1:8321 --code X
    # → tracevox runner start. No TraceVox account, no internet needed;
    # research data stays in ~/.tracevox/research_data.

From the source repository instead (identical semantics):

    # backend — persistent local storage in ./research_data (SQLite + JSONL)
    TRACEVOX_LOCAL_RESEARCH=1 uvicorn main:app --port 8000

    # frontend (dev) — or serve the built bundle
    cd frontend && npm install && npm run dev

    # research runner — isolated Python >= 3.10 env (torch/gymnasium/minigrid)
    python -m tracevox_research create-gate-experiment
    python -m tracevox_research import-tensorboard --experiment-id EXP_ID
    python -m tracevox_research run-eval --experiment-id EXP_ID \
        --arm-name "Clean PPO" --checkpoint ppo_minigrid_lavagapS7_clean_seed1.pt \
        --episodes 20 --seed 1 --corruption-mode mask --corruption-prob 0.5
    # fresh training from zero (managed, equivalence-gated PPO derivative;
    # periodic checkpoints enable Learning Replay)
    python -m tracevox_research run-training --experiment-id EXP_ID \
        --arm-name "Clean PPO" --seed 1 --total-timesteps 1000000 \
        --checkpoint-interval 100000
    # fixed diagnostic evaluation across that run's checkpoints
    python -m tracevox_research run-diagnostics --experiment-id EXP_ID \
        --training-run-id RRUN_ID --corruption-mode mask --corruption-prob 0.5

Research data never leaves the machine in local mode. Never set
TRACEVOX_LOCAL_RESEARCH=1 on a shared/deployed instance.

The packaged runner is on PyPI:

    pip install "tracevox-ai[rl]"
    tracevox doctor
    tracevox connect --server http://localhost:8000 --code <code>
    tracevox runner start

Pairing codes come from the Compute page in the TraceVox UI. Scientific
execution also needs the pilot artifacts available locally
(TRACEVOX_PILOT_DIR=/path/to/trust-calibrated-rl).

## 3. Publish research (explicit and granular)

Publication is never automatic. From a self-hosted instance:

    POST /api/research/experiments/{id}/publish
    { "episode_ids": ["ep_..."], "include_manifest": true,
      "include_aggregates": true, "include_training": true }

This marks the experiment public, records exactly what was selected, and
returns tracevox.public.bundle.v1 files you can place on any static host,
object storage, or serve from your own backend's /api/public routes.
Checkpoints, raw datasets, and full training traces are not publishable in
bundle v1. Everything else stays private.

## 4. Replay terminology

- Recorded Replay: exact reconstruction of persisted evidence (always available
  for recorded episodes).
- Computational Rerun: executing again; bit-identity is never promised where
  determinism cannot be guaranteed.
- Reproduction: recreating a result from its manifest/configuration as a new
  experiment lineage (originals are never overwritten).

## 5. Extending

Environments plug in via the EnvironmentAdapter interface
(reset / step / get_ground_truth_state / get_agent_observation /
get_render_state / get_attack_state / get_metrics / serialize_state /
action_labels / classify_termination). MiniGrid + CleanRL-style PPO is the
reference implementation. See /llms-full.txt for schemas and protocols.