plan.md

## Goal

Rebuild the Gradio `dashboard.py` as a browser-based inspector for the Explainer OpenEnv at `https://kgdrathan-explainer-env.hf.space`. No Python, no Gradio, no `config.yaml`, no environment/provider/model dropdowns. The dashboard runs episodes (reset → explore → generate → repair → done), shows everything, and supports single-step and auto-run.

## Runtime config (server-side only, no UI selectors)

Environment variables (read inside server functions, never in the browser bundle):

- `ENV_BASE_URL` — default `https://kgdrathan-explainer-env.hf.space`
- `API_BASE_URL` — default `https://router.huggingface.co/v1`
- `HF_TOKEN` — required, stored as a Lovable Cloud secret
- `MODEL_NAME` — default `Qwen/Qwen2.5-72B-Instruct`

The dashboard shows `ENV_BASE_URL` and `MODEL_NAME` as a small read-only metadata strip (not editable).

## Architecture

```text
Browser (React inspector)
        │  useServerFn
        ▼
TanStack server functions
  ├─ envReset({ seed?, episode_id? })
  ├─ envStep({ action })          ── proxies POST /step on ENV_BASE_URL
  ├─ envSchema()                  ── GET /schema (cached)
  └─ llmCall({ phase, obs, prior })── builds prompt, calls API_BASE_URL with HF_TOKEN,
                                       returns { raw, parsed action }
```

All env and LLM HTTP traffic goes through server functions. The browser never sees `HF_TOKEN`. CORS is irrelevant because calls are same-origin RPC.

## Explainer env contract (verified from `/schema`)

- POST `/reset` → `{ observation, done }` where `observation` is an `ExplainerObservation` (topic, content, tier, keywords, phase, feedback, search_results, top_chunks, explored_context, explore_steps_left, repair_attempts_left, last_errors, available_tools, metadata, reward).
- POST `/step` body: `{ action: ExplainerAction }`. Action shape:
  - `action_type`: `"explore" | "generate" | "repair"`
  - explore: `tool` (one of search_wikipedia / search_hf_papers / search_arxiv / search_scholar / fetch_docs / search_hf_hub), `query`, `intent`
  - generate / repair: `format` (`"marimo" | "manim"`), `code`, `narration`, `repair_notes` (repair only)
- GET `/metadata`, GET `/schema` for header info and tool list.

The episode is "done" when `observation.done === true` or `phase === "done"`.

## LLM logic (port of `inference.py` to TypeScript)

Reimplement as pure TS in `src/server/llm/`:

- `buildExplorePrompt(obs, accumulatedContext)`
- `buildGeneratePrompt(obs, accumulatedContext)`
- `buildRepairPrompt(obs, lastCode, lastErrors)`
- `parseExploreResponse(text)` → `{ tool, query, intent }` or `"SKIP"`
- `parseGenerateResponse(text)` → `{ format, code, narration }`
- `callLLM(messages)` → OpenAI-compatible `POST {API_BASE_URL}/chat/completions` with `Authorization: Bearer ${HF_TOKEN}` and `model: MODEL_NAME`.

Phase routing inside `runStep`:

- `phase === "explore"` → explore prompt; on `SKIP`, force a generate step instead.
- `phase === "generate"` → generate prompt; if env returns `phase === "repair"`, surface errors.
- `phase === "repair"` → repair prompt seeded with `last_errors` + previous code.

## Episode state (single React store, e.g. Zustand)

```text
{
  sessionId, episodeId,
  envUrl, modelName,
  obs,                   // latest ExplainerObservation
  phase, step, done, score, status,
  task: { topic, tier, difficulty, keywords, content, dataAvailable },
  research: { exploredContext, topChunks: [], lastSearchResults },
  generation: { lastFormat, lastCode, lastNarration, generatedRaw, parsedAction },
  rewards: [],           // per-step total
  rewardDetails: [],     // per-step component breakdown
  log: [],               // [START]/[LLM]/[STEP]/[END]/[WARN] entries
  autoRunning: false
}
```

A "session" reset just generates a new `episodeId` and calls `/reset` — there is no long-lived server-side handle, so each `envStep` call is stateless toward the env (the env tracks state internally per episode_id).

## Task bank

Port `ALL_TASKS` from the Python `task_bank` to a TS constant `TASKS = [{ topic, difficulty, tier }, ...]`. Dropdown shows `(random)` plus `topic [difficulty, tier]`. Picking a task passes `topic` to `/reset` via the action body if the env supports it; otherwise it's stored as a target hint and the env's own random topic is used (we'll detect from the schema at build time).

## UI (single page at `/`)

Inspector layout, dark theme, monospace accents — not a marketing page.

```text
┌─ Header ─────────────────────────────────────────────────────────┐
│ Topic · Tier/Difficulty · Phase badge · Step n · Score · Status  │
│ env=ENV_BASE_URL  model=MODEL_NAME                               │
├─ Controls ───────────────────────────────────────────────────────┤
│ [Task ▼ (random)…] [Reset Episode] [Next Step] [Auto Run ▶/■]  │
├─ Left column ─────────────────┬─ Right column ──────────────────┤
│ Observation                    │ LLM panel                       │
│  • topic / content (collapsed) │  • raw response                 │
│  • keywords, data_available    │  • parsed action (JSON)         │
│  • feedback (latest)           │  • generated code (syntax hl.)  │
│                                │                                 │
│ Research                       │ Rewards                         │
│  • last search_results         │  • per-step total summary       │
│  • Top 5 chunks table          │  • component breakdown table    │
│    (rank, source, title,       │                                 │
│     score, url, snippet)       │                                 │
├──────────────────────────────────────────────────────────────────┤
│ Timeline / log (scrollable, color-coded by tag)                  │
└──────────────────────────────────────────────────────────────────┘
```

Shadcn primitives only: Card, Table, Badge, Button, Select, ScrollArea, Tabs (for code/raw/parsed), Separator. Code blocks use a lightweight highlighter.

## Behavior

- **Reset Episode**: clears state, calls `envReset`, populates task fields from observation, logs `[START]`.
- **Next Step**: reads `phase`, calls `llmCall` for that phase, logs `[LLM]` with raw + parsed, calls `envStep`, merges observation, appends reward + components, logs `[STEP]`. Disabled when `done`.
- **Auto Run**: loops Next Step with a small delay until `done`, repair attempts exhausted, or user hits Stop. Logs `[END]` with success / score / rewards.
- Errors from the env or LLM go into the log as `[WARN]` / `[ERROR]` and surface as a toast; the run halts but state is preserved.

## Reward handling

Port the Python helpers:

- `rewardComponents(obsMetadata, feedback)` → filtered numeric components (uses the explore/generate/repair allow-lists).
- `parseRewardComponentsFromFeedback(feedback)` as a fallback for old observations.
- Total per phase: `explore_total | generate_total | repair_total` if present, else sum of visible components.
- Final episode score: `normalized_episode_score(rewards)` ported as a simple TS function (mean of generate+repair totals, clamped to [0,1]); `success = score >= SUCCESS_SCORE_THRESHOLD` (constant ported from `explainer_env/constants.py`, default 0.6 — confirmed during implementation).

## Technical details

- **Files added**:
  - `src/routes/index.tsx` — dashboard page, replaces placeholder.
  - `src/server/env.functions.ts` — `envReset`, `envStep`, `envMetadata`, `envSchema` server fns calling `${process.env.ENV_BASE_URL}`.
  - `src/server/llm/prompts.ts`, `src/server/llm/parse.ts`, `src/server/llm/client.ts` — port of inference.py prompt/parse/call.
  - `src/server/llm.functions.ts` — `runLlmStep({ phase, obs, prior })` server fn.
  - `src/server/config.functions.ts` — `getRuntimeConfig()` returning `{ envUrl, modelName }` (no secrets).
  - `src/lib/tasks.ts` — ported task bank.
  - `src/lib/rewards.ts` — reward parsing/normalization.
  - `src/lib/types.ts` — `ExplainerObservation`, `ExplainerAction`, etc.
  - `src/store/episode.ts` — Zustand store.
  - `src/components/inspector/*` — Header, Controls, ObservationPanel, LlmPanel, ResearchPanel, RewardsPanel, Log.
- **Secret**: `HF_TOKEN` added via Lovable Cloud secrets after plan approval. The user will be prompted to paste it.
- **Stack stays** TanStack Start + React + Tailwind + shadcn. No new heavy deps; add only `zustand` and a small syntax highlighter (`shiki` or `highlight.js`) — pick the smaller at implementation time.
- **Out of scope**: persistence across reloads, multi-user sessions, auth, charts. Pure single-tab inspector.

## Open items resolved during implementation

- Confirm whether `/reset` accepts a `topic` argument; if not, we still show the task picker but treat it as a display filter and surface a warning when the returned topic differs.
- Confirm exact `SUCCESS_SCORE_THRESHOLD` and `normalized_episode_score` formula from `explainer_env/constants.py` (you can paste it, otherwise default to mean-of-totals ≥ 0.6).