Smoke-train deployment update

CODEBASE_STRUCTURE_MAIN_V5.md

@@ -0,0 +1,1564 @@
+# ADAPT Codebase Structure (LLM Working Map)
+
+## Scope And Assumption
+
+This document was generated from the repository rooted at `/Users/dishagoyal/Documents/meta-rl-dsa-solver`.
+
+Important assumption:
+- There is no literal `main-v5/` directory in this workspace.
+- This document therefore treats the current repository as the codebase you meant by "main-v5".
+
+Goal of this document:
+- give an LLM enough structure to navigate, modify, and extend the codebase safely
+- explain not just file names, but runtime flow, ownership boundaries, data models, and cross-module dependencies
+- surface invariants and hidden coupling points that matter when changing the code
+
+Repository size snapshot:
+- Python/source/documentation lines inspected: about 6,981 lines across the main tracked source files
+- Core subsystems: `env`, `verifier`, `training`, `server`, top-level client/inference/test entrypoints, and `scripts`
+- Empty or currently unused directories: `rewards/`, `outputs/` in this snapshot
+
+## One-Screen Summary
+
+This repo implements **ADAPT**, an adversarial DSA tutoring environment for reinforcement learning and evaluation of code-generating models.
+
+The system is organized around one central loop:
+
+1. A problem family is chosen by the generator.
+2. The environment exposes only the public statement plus two visible examples.
+3. A model submits Python code.
+4. The verifier statically checks the code, runs it in a subprocess sandbox, scores visible and hidden tests, and computes correctness/efficiency signals.
+5. The environment converts those signals into repair-oriented feedback and an episode reward.
+6. Training uses this environment as a reward source inside a GRPO loop.
+7. The server layer exposes reset/step/state plus training/model management endpoints.
+
+The three most important files in the repo are:
+- `env/adapt_env.py`: the runtime environment and episode state machine
+- `env/generator.py`: the full problem-family registry plus deterministic problem generation
+- `training/train_grpo.py`: prompt construction, curriculum logic, reward hookup, evaluation, and GRPO training
+
+## High-Level Architecture
+
+```text
+Problem Generator -> AdaptEnvironment -> Verifier -> Reward/Feedback
+       |                    |                |             |
+       |                    |                |             |
+       v                    v                v             v
+  Problem family      Session state     Complexity +   Repair-aware
+  sampling + cases    + observation     sandboxing     training signal
+
+                Server API / Space Runtime
+                         |
+                         v
+           Training jobs, model loading, code generation
+```
+
+## Top-Level Files And Directories
+
+### Root
+
+- `README.md`
+  Project narrative, architecture overview, run instructions, and problem-family summary.
+
+- `pyproject.toml`
+  Main packaging and dependency definition.
+  Registers the installable packages: `env`, `server`, `training`, `verifier`.
+  Exposes script entrypoint `server = "server.app:main"`.
+
+- `requirements.txt`
+  Inference/server/runtime dependencies only.
+
+- `openenv.yaml`
+  OpenEnv metadata:
+  - runtime: `fastapi`
+  - app: `server.app:app`
+  - port: `7860`
+
+- `Dockerfile`
+  Python 3.11 slim image, installs package with training extras, runs `uvicorn server.app:app`.
+
+- `app.py`
+  Thin re-export of `server.app`.
+
+- `client.py`
+  Local Python HTTP client for the environment and training endpoints.
+
+- `models.py`
+  Pydantic schemas for actions, observations, and state.
+
+- `inference.py`
+  Benchmark/evaluation runner that loops through tasks, calls an OpenAI-compatible API, and logs standardized `[START]/[STEP]/[END]` traces.
+
+- `test.py`
+  Repository smoke-test aggregator; calls several script-level tests plus a verifier check.
+
+### `env/`
+
+Owns problem generation, environment state, subprocess execution, and the local Gradio demo.
+
+- `env/adapt_env.py`
+- `env/generator.py`
+- `env/executor.py`
+- `env/test_cases.py`
+- `env/app.py`
+
+### `verifier/`
+
+Owns submission validation, execution scoring, reward metrics, and lightweight complexity analysis.
+
+- `verifier/verifier.py`
+- `verifier/sandbox.py`
+- `verifier/metrics.py`
+- `verifier/complexity.py`
+
+### `training/`
+
+Owns prompt formatting, curriculum and generator control, GRPO training, evaluation, trace artifacts, and plotting.
+
+- `training/train_grpo.py`
+- `training/trace_logging.py`
+- `training/plot_results.py`
+
+### `server/`
+
+Owns the FastAPI service layer and Hugging Face Space runtime/training orchestration.
+
+- `server/app.py`
+- `server/runtime.py`
+- `server/requirements.txt`
+
+### `scripts/`
+
+Operational and smoke-test scripts.
+
+- `scripts/deploy_and_smoke_train.py`
+- `scripts/test_env.py`
+- `scripts/test_space_api.py`
+- `scripts/test_trace_logging.py`
+- `scripts/test_training_config.py`
+- `scripts/test_verifier.py`
+
+### Other
+
+- `notebooks/colab_kaggle_smoke_train.ipynb`
+  Notebook-based smoke training support.
+
+- `Qwen2.5_(3B)-GRPO.ipynb`
+  Large notebook artifact related to GRPO experimentation.
+
+- `rewards/`
+  Present but empty in this snapshot.
+
+- `outputs/`
+  Present but empty in this snapshot.
+
+## Core Runtime Concepts
+
+### 1. Problem
+
+A generated problem is a dictionary produced mainly by `GeneratorAgent.generate_problem(...)` in `env/generator.py`.
+
+Expected keys:
+- `problem_id`
+- `problem_type`
+- `difficulty`
+- `difficulty_label`
+- `problem`
+- `input_format`
+- `constraints`
+- `test_cases`
+- `visible_problem`
+- `generation_mode`
+- `validity_bonus`
+
+Important split:
+- `test_cases` contains both visible and hidden tests
+- `visible_problem` is the sanitized public-facing subset
+- hidden tests must never leak into the observation payload
+
+### 2. Episode
+
+An episode is one problem solved over up to `MAX_STEPS_PER_EPISODE = 3` attempts.
+
+Attempt flow:
+- attempt 1: initial submission
+- attempt 2/3: repair attempt based on feedback
+- episode ends early when hidden correctness reaches 1.0 and efficiency target is met, or after step 3
+
+### 3. Reward
+
+There are two related reward layers:
+
+- verifier-level reward in `verifier.metrics.compute_pass_rate(...)`
+  Used as raw execution-derived correctness reward.
+
+- environment episode reward in `verifier.metrics.compute_episode_reward(...)`
+  This is the more important repair-aware reward used by `AdaptEnvironment`.
+  It accounts for:
+  - hidden pass rate
+  - step discount
+  - improvement over previous attempt
+  - efficiency score
+  - optimization completion target
+
+### 4. Generator Reward Signal
+
+`env.generator.generator_reward(...)` measures how educational a generated problem is, targeting pass rates near 0.5.
+
+This signal is used by training-side reward-aware family sampling:
+- productive families become more likely to be sampled
+- implemented by `GeneratorController.family_productivity`
+
+## Shared Schemas (`models.py`)
+
+### `AdaptAction`
+
+Fields:
+- `session_id`
+- `code`
+
+Meaning:
+- server-routed step requests require a session id
+- local environment calls may omit it because the environment can self-bootstrap
+
+### `AdaptObservation`
+
+This is the main environment-facing payload.
+
+Key fields:
+- identity/context:
+  - `session_id`
+  - `problem_id`
+  - `problem_type`
+  - `difficulty`
+- episode progress:
+  - `attempt_number`
+  - `max_steps`
+  - `done`
+- public task content:
+  - `problem`
+  - `input_format`
+  - `constraints`
+  - `feedback`
+- evaluation signals:
+  - `pass_rate`
+  - `visible_pass_rate`
+  - `hidden_pass_rate`
+  - `syntax_valid`
+  - `execution_status`
+  - `timeout_count`
+  - `runtime_error_count`
+  - `invalid_output_count`
+  - `wrong_answer_count`
+  - `format_compliance`
+  - `reward_components`
+  - `generator_reward_signal`
+  - `reward`
+
+### `AdaptState`
+
+Server/state snapshot object; broader than the observation.
+
+Important fields:
+- active problem metadata
+- generator mode
+- generated public problem
+- last reward / pass rate / feedback / execution status
+- attempt history
+- recent metrics
+- generator reward signal
+
+## Subsystem 1: Environment (`env/`)
+
+### `env/adapt_env.py`
+
+This is the environment state machine and the single most important runtime module.
+
+#### Main class: `AdaptEnvironment`
+
+Inheritance:
+- attempts to inherit from `openenv.core.env_server.interfaces.Environment`
+- falls back to a local generic stub if OpenEnv is unavailable
+
+Important constants:
+- `MAX_STEPS_PER_EPISODE = 3`
+- `TARGET_EFFICIENCY_SCORE = 0.95`
+
+Internal mutable state:
+- `self.generator`
+- `self.generator_mode`
+- `self.session_id`
+- `self.problem`
+- `self.test_cases`
+- `self.last_results`
+- `self.history`
+- `self.attempt_history`
+- `self.previous_execution_status`
+- `self.episode_done`
+- `self._state` (`AdaptState`)
+
+#### `reset(...)`
+
+Responsibilities:
+- optionally update session id / generator mode / difficulty
+- choose or load a problem
+- copy test cases into the environment
+- clear prior attempt/results state
+- initialize `AdaptState`
+- return an initial observation with public problem text and instructions
+
+Supports:
+- forced `problem_id`
+- forced `difficulty`
+- externally injected `generated_problem`
+- family weighting via `family_weights`
+
+#### `step(action, ...)`
+
+Responsibilities:
+- lazy-reset if no problem is loaded
+- return terminal "call reset" observation if episode already ended
+- increment attempt number
+- call `_verify_submission`
+- compute hidden/visible pass rates and execution status
+- compute repair-aware reward via `compute_episode_reward`
+- build human-readable feedback
+- record metrics/state
+- finalize the episode if terminal
+
+Terminal conditions:
+- hidden pass rate is 1.0 and efficiency score >= 0.95
+- or step number reaches 3
+
+Important nuance:
+- a fully correct but less efficient solution may produce `pass_rate == 1.0` but `done == False`
+- the agent is then nudged to optimize further
+
+#### `_verify_submission(...)`
+
+Delegates to `verifier.verify(...)`.
+
+Then augments the verifier metadata with:
+- diversity bonus
+- validity bonus
+- generator reward signal
+
+#### `_format_feedback(...)`
+
+Produces repair-facing natural language feedback.
+
+Behavior depends on status:
+- syntax/safety violations get short static feedback
+- other cases get:
+  - attempt number
+  - previous status
+  - current status
+  - hidden and visible pass rates
+  - efficiency score
+  - failed test summaries
+  - optional optimization hints
+
+#### `_public_problem_view(...)`
+
+Critical leakage-control function.
+
+It uses:
+- `visible_problem`
+- formatted visible examples from `_format_examples()`
+
+This is what gets surfaced to the agent.
+Hidden tests stay internal.
+
+#### History and curriculum-relevant state
+
+`AdaptEnvironment` tracks:
+- recent pass rates
+- recent problem families
+- generator rewards
+- problem signatures
+- episode index
+
+This history influences future generation diversity and can be used by higher-level curriculum logic.
+
+### `env/generator.py`
+
+This file is the full problem bank, generator, case synthesis engine, and reference-solver library.
+It is the largest single file in the repo.
+
+#### Core constants
+
+- `VISIBLE_TEST_COUNT = 2`
+- `HIDDEN_TEST_COUNT = 8`
+- `TOTAL_TEST_CASES = 10`
+- `MIN_TEST_CASES = 10`
+
+#### `ProblemTemplate`
+
+Dataclass fields:
+- `problem_type`
+- `difficulty_tier`
+- `title`
+- `input_format`
+- `constraints`
+- `statement_builder`
+- `solver`
+- `case_builder`
+
+This is the canonical template unit from which all problems are built.
+
+#### `generator_reward(pass_rate, diversity_bonus, validity_bonus)`
+
+Educational-value reward:
+- highest when pass rate is near 0.5
+- clipped into `[0.0, 1.5]`
+- later used by the reward-aware family sampler in training
+
+#### `validate_problem(problem_dict)`
+
+Hard validation gate for generated problems.
+
+Checks:
+- required keys exist
+- public text fields are non-empty
+- scalar difficulty is between 0 and 1
+- exactly 10 test cases
+- visible/hidden ordering and flags are correct
+- test inputs are unique
+- output diversity is high enough to avoid degenerate problems
+
+This function is critical if changing generator behavior.
+
+#### `normalize_problem(problem_dict)`
+
+Normalizes string fields and shallow copies test cases / visible problem data.
+
+#### `GeneratorAgent`
+
+Dependency-free deterministic generator by default.
+
+Main behaviors:
+- `generate_problem(...)`
+- `generate(...)` thin alias
+- `_choose_template(...)`
+- `_rng_for(...)`
+- `_problem_signature(...)`
+- `_tier_to_scalar(...)`
+
+Determinism strategy:
+- hashes a seed material bundle containing difficulty, recent pass rates, recent problem types, episode index, and family weights
+- creates a `random.Random` instance from that hash
+
+This means generation is reproducible for the same history and settings.
+
+#### Template registry
+
+`_build_templates()` registers 20 problem families:
+
+Easy:
+- `sum_even_numbers`
+- `range_span`
+- `count_vowels`
+- `max_consecutive_ones`
+- `fizzbuzz_variant`
+- `running_total`
+
+Medium:
+- `count_local_peaks`
+- `longest_non_decreasing_run`
+- `two_sum_count`
+- `max_subarray_sum`
+- `group_anagrams_count`
+- `balanced_brackets`
+- `matrix_diagonal_sum`
+
+Hard:
+- `smallest_most_frequent`
+- `reverse_words`
+- `longest_common_subsequence`
+- `word_ladder_steps`
+- `merge_intervals`
+- `min_coins`
+- `rotate_matrix_90`
+
+For each family, the file contains:
+- statement text
+- input format
+- constraints
+- visible/hidden randomized case builders
+- a reference solver used to derive expected outputs
+
+#### Bottom half of the file
+
+The remainder of `env/generator.py` contains:
+- case factory helpers for each family
+- solver implementations for each family
+- parsers for input formats
+- random instance builders for bracket/path/word-ladder style tasks
+- formatting helpers for arrays, targets, intervals, matrices, coins, etc.
+
+Practical meaning:
+- if you add a new problem family, most of the work belongs here
+- the generator is intentionally self-contained; it does not depend on external datasets
+
+### `env/executor.py`
+
+Owns actual subprocess execution of user code.
+
+Execution strategy:
+- writes submission code to a temporary file under `.adapt_tmp` or `ADAPT_TMP_DIR`
+- runs `python -I -S submission.py`
+- feeds stdin
+- captures stdout/stderr
+- enforces timeout
+- truncates outputs to `OUTPUT_LIMIT_BYTES`
+
+Important constants:
+- timeout: `1.0s`
+- memory limit: `512 MB`
+- output limit: `256 KB`
+
+Linux-only hardening:
+- RLIMIT for address space, CPU, file size, and file descriptors
+
+Portable hardening:
+- isolated Python mode
+- stripped environment variables
+- temp HOME/TMP
+
+### `env/test_cases.py`
+
+Convenience layer over the generator.
+
+Main functions:
+- `load_problem_bank()`
+  Builds one representative problem per template for task listing.
+- `load_problem(problem_id=None, difficulty=None)`
+  Loads or samples a single problem.
+- `get_test_cases(...)`
+  Returns copied test cases.
+- `split_test_cases(...)`
+  Splits visible vs hidden tests.
+
+Server and inference logic depend on this file for task enumeration.
+
+### `env/app.py`
+
+Gradio demo app, separate from the FastAPI/OpenEnv server.
+
+Global state:
+- `TRAINING_MANAGER = SpaceTrainingManager()`
+- `SESSIONS: dict[str, AdaptEnvironment]`
+
+Main interactive functions:
+- `_get_env(...)`
+- `_problem_markdown(...)`
+- `sample_problem(...)`
+- `evaluate_submission(...)`
+- `model_attempt(...)`
+
+Use case:
+- manual exploration of sampled problems
+- manual verification of code
+- comparison against the current loaded model's generated code
+
+Notable design choice:
+- `model_attempt(...)` calls `TRAINING_MANAGER.generate_code(...)`, then immediately feeds that code back through `evaluate_submission(...)`
+- so the UI path uses the exact same verifier/environment loop as manual submissions
+
+## Subsystem 2: Verification (`verifier/`)
+
+### `verifier/verifier.py`
+
+Central verification orchestration.
+
+Function: `verify(code, test_cases, step_number=1)`
+
+Pipeline:
+1. `validate_code(code)` from `verifier.sandbox`
+2. `analyze_code_complexity(code)` from `verifier.complexity`
+3. If syntax/safety fails:
+   - compute status/reward with empty results
+   - return immediately
+4. Else execute against each test case via `verifier.sandbox.run_code(...)`
+5. Build per-test result records
+6. Compute pass-rate metrics with `compute_pass_rate(...)`
+7. Build hidden-facing feedback summary
+
+Per-test result record includes:
+- index
+- status
+- passed
+- format_ok
+- stdout/stderr
+- expected/input only for visible tests
+- timed_out
+- exit_code
+- duration_ms
+- sandbox metadata
+- visibility
+
+Security boundary:
+- visible tests expose expected/actual/input in the result metadata
+- hidden tests intentionally suppress those values
+
+### `verifier/sandbox.py`
+
+Static validation plus runtime delegation.
+
+Forbidden imports:
+- `ctypes`
+- `os`
+- `pathlib`
+- `resource`
+- `shutil`
+- `signal`
+- `socket`
+- `subprocess`
+
+Forbidden calls:
+- `__import__`
+- `breakpoint`
+- `compile`
+- `eval`
+- `exec`
+- `open`
+
+Main functions:
+- `validate_code(code)`
+- `run_code(code, stdin, timeout=1)`
+
+Important nuance:
+- runtime isolation is actually implemented in `env.executor.run_code`
+- this file adds AST-level policy checks before execution
+
+### `verifier/metrics.py`
+
+Owns reward math.
+
+Constants:
+- `STEP_DISCOUNTS = {1: 1.0, 2: 0.85, 3: 0.70}`
+- `TERMINAL_ZERO_STATUSES = {"syntax_error", "safety_violation", "timeout"}`
+
+Main functions:
+- `step_discount(...)`
+- `compute_reward(...)`
+- `compute_pass_rate(...)`
+- `compute_episode_reward(...)`
+
+#### `compute_pass_rate(...)`
+
+Produces:
+- pass counts
+- hidden/visible pass rates
+- execution status classification
+- format compliance
+- reward components
+- verifier components
+
+Execution status priority order:
+- syntax error
+- safety violation
+- precheck status
+- timeout
+- runtime error
+- invalid output format
+- wrong answer
+- completed
+
+#### `compute_episode_reward(...)`
+
+This is the repair-aware environment reward.
+
+Behavior:
+- syntax/safety/timeout => `0.0`
+- correct solution => discounted reward blended with efficiency score
+- incorrect but non-terminal and improved => small progress reward (`0.1 * delta`)
+- final failed attempt => `0.0`
+
+This function is one of the most behavior-critical points in the codebase.
+
+### `verifier/complexity.py`
+
+Static efficiency heuristic.
+
+Signals tracked:
+- nested loop depth
+- list/set/dict comprehensions
+- generator expressions
+- sorting calls
+- materialized builtin inputs
+
+Outputs:
+- `time_complexity_score`
+- `space_complexity_score`
+- `efficiency_score`
+- `optimization_hints`
+- `complexity_signals`
+
+Role in the system:
+- not a formal complexity analyzer
+- acts as a lightweight shaping mechanism for "correct but inefficient" solutions
+
+## Subsystem 3: Training (`training/`)
+
+### `training/train_grpo.py`
+
+This is the second-most important file after `env/generator.py`.
+It owns the full RL training path.
+
+#### Global constants
+
+- `SYSTEM_PROMPT`
+  Shared solver instruction string.
+
+- `CRITICAL_PROJECTION_NAMES`
+  Used during precision audits.
+
+- `SMOKE_PREFERRED_PRECISION = "fp16"`
+
+#### `TrainingConfig`
+
+Dataclass with the full trainable configuration surface.
+
+Important fields:
+- model/runtime:
+  - `model_name`
+  - `output_dir`
+  - `load_in_4bit`
+  - `gradient_checkpointing`
+  - `bf16`
+  - `save_merged_model`
+- data/training:
+  - `dataset_size`
+  - `max_steps`
+  - `batch_size`
+  - `gradient_accumulation_steps`
+  - `num_generations`
+  - `learning_rate`
+- token lengths:
+  - `max_seq_length`
+  - `max_prompt_length`
+  - `max_completion_length`
+- LoRA:
+  - `lora_rank`
+  - `lora_alpha`
+- evaluation:
+  - `baseline_eval`
+  - `evaluation_episodes`
+  - `eval_max_new_tokens`
+- logging/control:
+  - `disable_wandb`
+  - `wandb_project`
+  - `wandb_run_name`
+  - `generator_mode`
+  - `non_deterministic_generator`
+  - `trace_logging_enabled`
+  - `checkpoint_log_interval_steps`
+
+#### Training presets
+
+Defined in `TRAINING_PRESETS`:
+- `smoke`
+- `l4`
+- `default`
+
+`smoke`:
+- tiny, CPU/fallback-friendly
+- no 4-bit
+- no gradient checkpointing
+- short run
+
+`l4` and `default`:
+- intended for real LoRA + 4-bit training
+- default model: `Qwen/Qwen2.5-3B-Instruct`
+
+#### Prompt helpers
+
+- `extract_code(...)`
+- `format_examples(...)`
+- `build_solver_prompt(...)`
+- `build_prompt_from_problem(...)`
+
+Important prompt shape:
+- problem id/family/difficulty
+- attempt number
+- problem statement with examples
+- input format
+- constraints
+- feedback
+
+This exact shape is reused by training, evaluation, and server-side model generation.
+
+#### Config helpers
+
+- `build_training_config(...)`
+- `namespace_to_config(...)`
+
+These are used both by CLI and by the server runtime manager.
+
+#### `CurriculumManager`
+
+Adaptive difficulty controller.
+
+Defaults:
+- difficulties: `easy`, `medium`, `hard`
+- moving window: `10`
+- promote threshold: `0.70`
+- demote threshold: `0.30`
+
+Behavior:
+- tracks recent episode pass rates
+- promotes/demotes based on moving average
+- clears history after each level change
+
+#### `GeneratorController`
+
+Training-side wrapper over `GeneratorAgent`.
+
+Responsibilities:
+- sample problems for a target difficulty
+- register prompt -> problem mapping
+- compute reward-aware family weights
+- track family productivity EMA
+- update generator-side history after each episode
+
+Key feature:
+- in `reward_aware` mode, family selection is biased by a softmax over `family_productivity / temperature`
+
+#### `GeneratorRolloutDataset`
+
+Minimal dataset adapter used by GRPO.
+
+Each item:
+- samples a new problem at the current curriculum difficulty
+- returns a dict with only `{"prompt": prompt}`
+
+This means the dataset is not static; prompts are generated online.
+
+#### `TrainingLogger`
+
+Owns:
+- in-memory reward/event rows
+- optional Weights & Biases logging
+- optional trace artifacts through `TraceArtifactLogger`
+- CSV writing
+
+Every logged row includes:
+- phase
+- episode reward
+- pass rate
+- visible pass rate
+- difficulty
+- family
+- curriculum level
+- execution status
+- attempt number
+- family productivity columns
+- extra metadata like prompt/completion/code/feedback
+
+#### `build_reward_func(...)`
+
+This is the bridge between GRPOTrainer and the environment.
+
+For each `(prompt, completion)` pair:
+- resolve original problem from prompt registry
+- spin up `AdaptEnvironment`
+- reset with the exact generated problem
+- run one environment step using extracted code
+- record reward
+- update generator controller
+- update curriculum
+- log event
+- emit progress callback payload
+
+This function is the key glue layer for RL.
+
+#### `generate_completion(...)`
+
+Shared inference helper for local model objects.
+
+Responsibilities:
+- render chat template if tokenizer supports it
+- choose generation device from HF device map or model device
+- call `model.generate(...)`
+- decode only newly generated tokens
+
+Used by:
+- evaluation
+- server runtime generation
+
+#### `run_policy_evaluation(...)`
+
+Offline evaluator over a schedule of easy/medium/hard episodes.
+
+Loop:
+- sample a problem
+- run up to 3 repair attempts
+- log final result
+- aggregate pass rates by tier
+
+Outputs summary:
+- easy
+- medium
+- hard
+- overall
+
+#### Precision/runtime utilities
+
+- `get_runtime_versions(...)`
+- `validate_runtime_versions(...)`
+- `resolve_precision_policy(...)`
+- `normalize_model_precision(...)`
+- `audit_critical_module_precision(...)`
+
+These guardrails exist because the training path is tuned around Unsloth + GRPO + mixed precision.
+
+#### `run_training(...)`
+
+The full training entrypoint.
+
+Major stages:
+1. Normalize config
+2. Import `torch`, `trl`, `unsloth`, and transformers callback support
+3. Create output directory
+4. Patch Unsloth RL stack
+5. Resolve runtime versions and precision policy
+6. Load base model/tokenizer via `FastLanguageModel.from_pretrained`
+7. Apply LoRA with `FastLanguageModel.get_peft_model`
+8. Run precision audit(s)
+9. Create curriculum, generator controller, and logger
+10. Optionally run baseline evaluation
+11. Build `GRPOConfig`
+12. Build `GRPOTrainer` with online prompt dataset and environment reward function
+13. Train
+14. Save adapter or merged model
+15. Optionally run trained evaluation
+16. Write reward CSV and finalize trace artifacts
+17. Return a summary payload containing paths and metrics
+
+Output summary includes:
+- config
+- runtime versions
+- precision mode/policy/audits
+- `output_dir`
+- `reward_curve_csv`
+- trace artifact paths
+- baseline/trained summaries
+- completed steps
+
+#### CLI
+
+`build_parser()` exposes the training surface as a command-line interface.
+
+Entrypoint:
+- `python training/train_grpo.py ...`
+
+### `training/trace_logging.py`
+
+Structured artifact logger for Space/server integration and post-run analysis.
+
+Main class: `TraceArtifactLogger`
+
+Artifacts under `output_dir/logs/`:
+- `run_manifest.json`
+- `events.jsonl`
+- `latest_checkpoint.json`
+- `checkpoint_step_XXXXX.json`
+- `run_summary.json`
+
+Tracked rolling metrics:
+- average reward
+- average pass rate
+- average efficiency score
+
+Used by:
+- `TrainingLogger` in `training/train_grpo.py`
+- surfaced through `server.runtime.SpaceTrainingManager`
+
+### `training/plot_results.py`
+
+Offline plotting tool for `reward_curve.csv`.
+
+Outputs:
+- `reward_curve.png`
+- `pass_rate_by_difficulty.png`
+- `family_productivity.png`
+
+Important note:
+- `plot_pass_rate_by_difficulty(...)` groups rows by `difficulty_tier`
+- the function then iterates over `"easy"`, `"medium"`, `"hard"`
+- this assumes the CSV contains string difficulty labels, which it currently does
+
+## Subsystem 4: Server And Space Runtime (`server/`)
+
+### `server/app.py`
+
+FastAPI surface for OpenEnv plus training/model utilities.
+
+Global state:
+- `SESSIONS`
+- `SESSION_LAST_ACCESSED`
+- `TRAINING_MANAGER = SpaceTrainingManager()`
+- `TASKS` generated from `env.test_cases.load_problem_bank()`
+
+Session policy:
+- TTL: 30 minutes
+- unknown/expired sessions raise 404
+
+#### Request models
+
+- `ResetRequest`
+- `TrainRequest`
+- `RunTrainedPolicyRequest`
+- `GenerateCodeRequest`
+
+#### Informational endpoints
+
+- `GET /`
+  Root metadata plus training/model status and active session count
+- `GET /health`
+- `GET /metadata`
+- `GET /tasks`
+- `GET /schema`
+- `GET /train/status`
+- `GET /model/status`
+
+#### Environment endpoints
+
+- `POST /reset`
+  Creates a new `AdaptEnvironment`, stores it in `SESSIONS`, returns initial observation.
+
+- `POST /step`
+  Accepts either raw action JSON or `{ "action": ... }`.
+  Requires `session_id`.
+  Returns:
+  - `observation`
+  - `reward`
+  - `done`
+  - compact `info`
+
+- `GET /state`
+  Returns `AdaptState`.
+
+#### Model/training endpoints
+
+- `POST /train`
+  Starts async training via `SpaceTrainingManager.start_training(...)`
+
+- `POST /run-trained-policy`
+  Runs current model through a full 3-attempt environment episode
+
+- `POST /generate-code`
+  One-shot generation for a supplied problem payload
+
+#### MCP endpoint
+
+- `POST /mcp`
+  Stub only; always returns "not implemented"
+
+### `server/runtime.py`
+
+Owns asynchronous training and model-loading behavior for a Space-like deployment.
+
+This file has two major classes:
+- `SpaceModelRegistry`
+- `SpaceTrainingManager`
+
+It also defines two dataclasses used as persisted status:
+- `ModelState`
+- `TrainingJobState`
+
+#### `ModelState`
+
+Tracks:
+- whether a model is loaded
+- whether the active generation source is `trained`, `base`, or `unavailable`
+- repo id / local path / revision
+- base model name
+- load time
+- last error
+
+#### `TrainingJobState`
+
+Tracks:
+- job status and run id
+- config
+- timestamps
+- artifact paths
+- uploaded model revision
+- logs location
+- current phase and progress
+- precision/runtime audit metadata
+- last seen train metrics
+- baseline/trained summaries
+- error and traceback
+
+This is what backs `/train/status`.
+
+#### `SpaceModelRegistry`
+
+Primary responsibilities:
+- load base model when no trained model is available
+- load trained artifact from local disk or Hugging Face Hub
+- choose generation stack
+- fallback from trained model to base model if trained generation fails
+- run policy episodes and one-shot code generation
+
+Important methods:
+- `_require_runtime_dependencies(...)`
+- `load_base_model()`
+- `load_from_local(...)`
+- `load_latest_from_hub()`
+- `run_policy(...)`
+- `generate_code(...)`
+
+Environment variables it cares about:
+- `HF_MODEL_REPO_ID`
+- `HF_TOKEN`
+- `BASE_MODEL_NAME`
+- `MODEL_NAME`
+
+Fallback behavior:
+- if no trained model is loadable, base-model generation can still work
+- if trained-model generation errors, it can fall back to base generation and record the fallback reason
+
+#### `SpaceTrainingManager`
+
+Primary responsibilities:
+- persist training job state to disk
+- prevent concurrent training runs
+- build output directory for each run
+- spawn background training thread
+- upload artifacts to the Hub
+- delete local logs after upload
+- refresh active model after successful upload
+
+State files:
+- status persisted in `training_status.json` under `SPACE_OUTPUT_ROOT` or `/tmp/adapt-space`
+
+Key methods:
+- `_restore_status()`
+- `_persist_status()`
+- `_update_progress(...)`
+- `status_payload()`
+- `start_training(...)`
+- `_run_training_job(...)`
+- `_upload_artifacts(...)`
+- `_cleanup_local_logs(...)`
+- `load_latest_model()`
+- `run_trained_policy(...)`
+- `generate_code(...)`
+
+Background training behavior:
+- `start_training(...)` creates a `TrainingConfig` using `build_training_config(...)`
+- output dir is namespaced by `run_id`
+- training happens on a daemon thread
+- progress updates come from `run_training(..., progress_callback=...)`
+
+Successful completion path:
+1. run training
+2. upload artifacts to HF model repo
+3. delete local logs
+4. load latest trained model from Hub
+5. mark status as `succeeded`
+
+Failure path:
+- mark status as `failed`
+- persist traceback
+- optionally clean logs first
+
+## Top-Level Utility Entrypoints
+
+### `client.py`
+
+`AdaptEnvClient` wraps HTTP operations for:
+- `reset`
+- `step`
+- `state`
+- `train`
+- `train_status`
+- `model_status`
+- `run_trained_policy`
+- `generate_code`
+
+Useful for:
+- local automation
+- notebooks
+- scripted experimentation against the FastAPI app
+
+### `inference.py`
+
+OpenAI-compatible external inference runner.
+
+Key behaviors:
+- loads tasks from `env.test_cases.load_problem_bank()`
+- resets an `AdaptEnvironment` per task
+- builds a JSON user payload from the observation
+- calls `OpenAI(...).chat.completions.create(...)`
+- extracts code
+- runs up to 3 repair attempts
+- logs machine-readable stdout lines
+
+Important env vars:
+- `HF_TOKEN`
+- `API_BASE_URL` default `https://router.huggingface.co/v1`
+- `MODEL_NAME` default `openai/gpt-oss-120b`
+
+This file is separate from the local model runtime in `server/runtime.py`.
+It is for remote API-based evaluation, not local HF model objects.
+
+### `test.py`
+
+Simple "run several smokes in sequence" script.
+
+Calls:
+- `scripts.test_env.main`
+- `scripts.test_space_api.main`
+- `scripts.test_training_config.main`
+- `scripts.test_trace_logging.main`
+- then a direct verifier correctness check
+
+## Scripts (`scripts/`)
+
+### `scripts/deploy_and_smoke_train.py`
+
+Operational helper for pushing to a Space and smoke-running training remotely.
+
+Capabilities:
+- optionally auto-commit and push repo changes
+- wait for `/health`
+- start `/train`
+- poll `/train/status`
+- follow an already-running job if requested
+
+Key modes/flags:
+- `--skip-push`
+- `--skip-health-check`
+- `--trigger-only`
+- `--status-only`
+- `--follow-running`
+
+This is a deployment/ops script, not part of core runtime.
+
+### `scripts/test_env.py`
+
+Best environment behavior reference in the repo.
+
+It verifies:
+- public examples are exposed
+- hidden tests are not exposed
+- correct first-attempt solution gets full reward
+- repair trajectory produces discounted reward
+- correct-but-less-efficient solution remains open for optimization
+- syntax/runtime/timeout/safety states behave as expected
+
+If you need to understand intended environment semantics, start here after `adapt_env.py`.
+
+### `scripts/test_space_api.py`
+
+FastAPI smoke tests with patched training manager behavior.
+
+Verifies:
+- root/model/train status endpoints
+- reset/step/state flow
+- expected 409 when no trained model is available for policy run
+- generate-code path
+- training start and conflict handling
+
+### `scripts/test_trace_logging.py`
+
+Smoke tests trace artifact creation.
+
+Checks:
+- manifest creation
+- event JSONL writing
+- checkpoint writing
+- summary finalization
+
+### `scripts/test_training_config.py`
+
+Tests:
+- preset construction
+- precision policy resolution under fake torch/cuda conditions
+- reward behavior for fully correct but sub-target efficiency case
+
+### `scripts/test_verifier.py`
+
+Manual verification sanity suite over:
+- correct
+- wrong
+- less optimized
+- invalid output
+- timeout
+- runtime error
+- safety violation
+
+Also confirms the complexity/efficiency signal differentiates optimized from less-optimized code.
+
+## End-To-End Flows
+
+### Flow A: API Environment Interaction
+
+1. Client calls `POST /reset`
+2. `server.app.reset(...)` creates a new `AdaptEnvironment`
+3. `AdaptEnvironment.reset(...)` loads/generates a problem and returns public observation
+4. Client submits code via `POST /step`
+5. `server.app.step(...)` validates `AdaptAction`
+6. `AdaptEnvironment.step(...)` calls `verify(...)`
+7. `verify(...)` validates AST safety, runs sandboxed code on tests, computes metrics
+8. Environment converts metrics into feedback + reward + updated observation
+9. `GET /state` returns broader session state if needed
+
+### Flow B: Local Training
+
+1. CLI or server builds `TrainingConfig`
+2. `run_training(...)` loads base model and applies LoRA
+3. `GeneratorRolloutDataset` emits prompts for current curriculum difficulty
+4. GRPO generates completions
+5. `build_reward_func(...)` routes completions through `AdaptEnvironment`
+6. Environment returns reward
+7. `CurriculumManager` updates difficulty
+8. `GeneratorController` updates family productivity
+9. `TrainingLogger` writes CSV/events/checkpoints
+10. Model and tokenizer are saved
+11. Optional trained evaluation runs
+
+### Flow C: Server-Side Training On Space
+
+1. `POST /train`
+2. `SpaceTrainingManager.start_training(...)`
+3. Background thread calls `_run_training_job(...)`
+4. `run_training(...)` emits progress updates
+5. Status persisted to `training_status.json`
+6. Artifacts uploaded to HF repo
+7. Local logs optionally deleted
+8. Latest model reloaded from Hub
+9. `/train/status` and `/model/status` reflect final state
+
+### Flow D: Model-Powered Generation In Demo Or API
+
+1. A problem payload is turned into a solver prompt with `build_solver_prompt(...)`
+2. `SpaceModelRegistry.generate_code(...)` picks trained or base model
+3. `generate_completion(...)` runs local generation
+4. Returned completion is cleaned with `extract_code(...)`
+5. In Gradio demo, generated code is immediately evaluated in the same environment loop
+
+## Important Invariants And Hidden Couplings
+
+### Hidden tests must never leak
+
+Critical files:
+- `env/adapt_env.py`
+- `verifier/verifier.py`
+- `scripts/test_env.py`
+
+If you change observation formatting, server payloads, or debug output, verify that hidden tests are still suppressed.
+
+### Prompt text is reused across training, evaluation, and generation
+
+Critical file:
+- `training/train_grpo.py`
+
+If you change `SYSTEM_PROMPT`, `build_solver_prompt(...)`, or `extract_code(...)`, you affect:
+- GRPO training
+- baseline/trained evaluation
+- `server.runtime` generation
+- `env.app` model attempt path
+
+### Reward semantics are distributed
+
+Files:
+- `verifier/metrics.py`
+- `env/adapt_env.py`
+- `env/generator.py`
+
+There are three conceptually different signals:
+- verifier correctness reward
+- episode reward
+- generator reward signal
+
+Do not change one assuming it is the only reward in the system.
+
+### The generator is both data source and answer key
+
+`env/generator.py` does all of these:
+- defines task families
+- generates inputs
+- defines reference solvers
+- defines expected outputs
+
+If a reference solver is wrong, the entire environment silently becomes wrong.
+
+### Correctness is based on hidden tests, not visible tests
+
+Visible tests are for examples and repair feedback.
+Core reward/curriculum decisions are driven by hidden pass rate.
+
+### Efficiency can block episode completion
+
+An all-tests-passing answer can still have `done == False` if efficiency target is not met.
+This is intentional and affects reward, feedback, and repair behavior.
+
+### Space runtime is designed to degrade gracefully
+
+`server/runtime.py` allows:
+- base model use when trained model is unavailable
+- trained-to-base fallback on generation error
+
+This is useful operationally, but it means "generation works" does not always imply "trained model is active".
+
+## Change Impact Guide
+
+### If you want to add a new problem family
+
+Primary file:
+- `env/generator.py`
+
+You will usually need to add:
+- template entry in `_build_templates()`
+- case builder(s)
+- reference solver
+- any parser/helper utilities
+
+Then verify:
+- `validate_problem(...)` still passes
+- `load_problem_bank()` includes the new family
+- Gradio dropdown in `env/app.py` optionally includes it
+- README family list stays aligned
+
+### If you want to change reward behavior
+
+Primary files:
+- `verifier/metrics.py`
+- `env/adapt_env.py`
+- maybe `env/generator.py` if generator curriculum shaping should change
+
+Then re-check:
+- `scripts/test_env.py`
+- `scripts/test_training_config.py`
+- training summaries and trace logging assumptions
+
+### If you want to change prompt style or model behavior
+
+Primary file:
+- `training/train_grpo.py`
+
+Also impacts:
+- `server/runtime.py`
+- `inference.py`
+- `env/app.py`
+
+### If you want to harden execution/security
+
+Primary files:
+- `verifier/sandbox.py`
+- `env/executor.py`
+
+Be careful to preserve:
+- valid competitive-programming style solutions
+- output capture behavior
+- timeout and isolation semantics
+
+### If you want to modify server payloads or API
+
+Primary files:
+- `models.py`
+- `server/app.py`
+- `client.py`
+- possibly `scripts/test_space_api.py`
+
+## Recommended Reading Order For A New LLM
+
+1. `README.md`
+2. `models.py`
+3. `env/adapt_env.py`
+4. `verifier/verifier.py`
+5. `verifier/metrics.py`
+6. `env/generator.py`
+7. `training/train_grpo.py`
+8. `server/app.py`
+9. `server/runtime.py`
+10. `scripts/test_env.py`
+11. `scripts/test_space_api.py`
+
+Why this order:
+- it starts with conceptual context
+- then schemas
+- then the core environment loop
+- then generation and reward internals
+- then training and serving
+- then tests as executable specification
+
+## File-By-File Responsibility Index
+
+### Root
+
+- `README.md`: project rationale, architecture, usage docs
+- `pyproject.toml`: package/dependency metadata
+- `requirements.txt`: lighter runtime dependencies
+- `openenv.yaml`: OpenEnv deployment metadata
+- `Dockerfile`: container entrypoint
+- `app.py`: re-export server app
+- `client.py`: Python HTTP client wrapper
+- `models.py`: shared action/observation/state schemas
+- `inference.py`: remote API-based benchmark runner
+- `test.py`: combined smoke test launcher
+
+### `env/`
+
+- `env/__init__.py`: re-exports generator utilities
+- `env/adapt_env.py`: main environment state machine
+- `env/app.py`: Gradio demo app
+- `env/executor.py`: subprocess execution sandbox
+- `env/generator.py`: problem registry, generators, solvers, helpers
+- `env/test_cases.py`: problem bank and split helpers
+
+### `verifier/`
+
+- `verifier/__init__.py`: re-exports `verify`
+- `verifier/complexity.py`: static complexity heuristics
+- `verifier/metrics.py`: reward and scoring math
+- `verifier/sandbox.py`: AST safety checks and runtime bridge
+- `verifier/verifier.py`: verification orchestration
+
+### `training/`
+
+- `training/__init__.py`: package marker
+- `training/plot_results.py`: offline plotting utilities
+- `training/trace_logging.py`: structured logs/checkpoints/summary artifacts
+- `training/train_grpo.py`: training, evaluation, prompts, config, curriculum
+
+### `server/`
+
+- `server/__init__.py`: re-export app/main
+- `server/app.py`: FastAPI routes and session handling
+- `server/requirements.txt`: server/runtime dependency subset
+- `server/runtime.py`: model registry and training job manager
+
+### `scripts/`
+
+- `scripts/deploy_and_smoke_train.py`: deploy-and-train automation
+- `scripts/test_env.py`: environment smoke spec
+- `scripts/test_space_api.py`: API smoke spec
+- `scripts/test_trace_logging.py`: trace logger smoke spec
+- `scripts/test_training_config.py`: config/precision/reward smoke spec
+- `scripts/test_verifier.py`: verifier behavior sanity script
+
+## Known Gaps Or Non-Core Artifacts
+
+- No `main-v5/` directory exists in this workspace.
+- `rewards/` is empty in this snapshot.
+- `outputs/` is empty in this snapshot, so no completed run artifacts were available to inspect.
+- The notebook artifacts were not treated as the source of truth; the Python modules are the canonical implementation.
+
+## Bottom Line
+
+If another LLM needs to work effectively in this repo, it should think of the codebase as five tightly linked layers:
+
+1. `env/generator.py` defines what the tasks are.
+2. `verifier/*` defines how code is checked and scored.
+3. `env/adapt_env.py` turns scoring into an interactive repair environment.
+4. `training/train_grpo.py` plugs that environment into GRPO and curriculum learning.
+5. `server/*` makes the environment, model runtime, and training lifecycle available over HTTP and in a Hugging Face Space.
+
+That is the true structural spine of the repository.

env/adapt_env.py

@@ -33,10 +33,15 @@ class AdaptEnvironment(Environment[AdaptAction, AdaptObservation, AdaptState]):
         self,
         generator: GeneratorAgent | None = None,
         generator_mode: str = "heuristic",
+        use_dataset: bool = False,
+        dataset_kwargs: dict[str, Any] | None = None,
         session_id: str | None = None,
     ) -> None:
         super().__init__()
-        self.generator = generator or GeneratorAgent()
+        self.generator = generator or GeneratorAgent(
+            use_dataset=use_dataset,
+            dataset_kwargs=dataset_kwargs or {},
+        )
         self.generator_mode = generator_mode
         self.session_id = session_id or str(uuid4())
         self.problem: dict[str, Any] = {}

env/dataset_loader.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import hashlib
+import random
+import re
+from typing import Any
+
+from env.generator import HIDDEN_TEST_COUNT, TOTAL_TEST_CASES, VISIBLE_TEST_COUNT
+
+MAX_IO_CHARS = 4096
+DEFAULT_DATASET_NAME = "deepmind/code_contests"
+DEFAULT_SPLIT = "train"
+DEFAULT_MAX_PROBLEMS = 5000
+
+
+def _load_raw_dataset(
+    dataset_name: str,
+    split: str = DEFAULT_SPLIT,
+    max_problems: int = DEFAULT_MAX_PROBLEMS,
+) -> list[dict[str, Any]]:
+    from datasets import load_dataset
+
+    dataset = load_dataset(dataset_name, split=split, trust_remote_code=True)
+    rows: list[dict[str, Any]] = []
+    for raw_row in dataset:
+        row = dict(raw_row)
+        statement = str(row.get("description") or row.get("question") or "").strip()
+        if not statement:
+            continue
+        if not _extract_pairs(row.get("public_tests")):
+            continue
+        if not (_extract_pairs(row.get("private_tests")) or _extract_pairs(row.get("generated_tests"))):
+            continue
+        rows.append(row)
+        if len(rows) >= int(max_problems):
+            break
+    return rows
+
+
+def _normalise_row(raw_row: dict[str, Any], dataset_name: str) -> dict[str, Any] | None:
+    statement = _extract_problem_statement(raw_row)
+    if not statement:
+        return None
+
+    public_pairs = _extract_pairs(raw_row.get("public_tests"))
+    private_pairs = _extract_pairs(raw_row.get("private_tests"))
+    generated_pairs = _extract_pairs(raw_row.get("generated_tests"))
+    visible_pairs = public_pairs[:VISIBLE_TEST_COUNT]
+    hidden_pairs = (private_pairs + generated_pairs)[:HIDDEN_TEST_COUNT]
+    if len(visible_pairs) != VISIBLE_TEST_COUNT or len(hidden_pairs) != HIDDEN_TEST_COUNT:
+        return None
+
+    test_cases: list[dict[str, Any]] = []
+    seen_inputs: set[str] = set()
+    for index, (raw_input, raw_output) in enumerate(visible_pairs + hidden_pairs):
+        normalized_input = _normalize_io_text(raw_input, ensure_trailing_newline=True)
+        normalized_output = _normalize_io_text(raw_output, ensure_trailing_newline=False)
+        if not normalized_input or normalized_input in seen_inputs:
+            return None
+        seen_inputs.add(normalized_input)
+        test_cases.append(
+            {
+                "input": normalized_input,
+                "output": normalized_output,
+                "is_visible": index < VISIBLE_TEST_COUNT,
+            }
+        )
+
+    if len(test_cases) != TOTAL_TEST_CASES:
+        return None
+
+    difficulty_label, difficulty_value = _difficulty_fields(raw_row, dataset_name)
+    input_format = _extract_section(statement, "input") or "Read from stdin."
+    constraints = _extract_constraints(statement)
+    problem_type = _infer_problem_type(raw_row, statement)
+    problem_id = _problem_id(raw_row, dataset_name)
+
+    visible_examples = [dict(test_case) for test_case in test_cases[:VISIBLE_TEST_COUNT]]
+    return {
+        "problem_id": problem_id,
+        "problem_type": problem_type,
+        "difficulty": difficulty_value,
+        "difficulty_label": difficulty_label,
+        "problem": statement,
+        "input_format": input_format,
+        "constraints": constraints,
+        "test_cases": test_cases,
+        "visible_problem": {
+            "problem": statement,
+            "input_format": input_format,
+            "constraints": constraints,
+            "examples": visible_examples,
+        },
+        "generation_mode": "dataset",
+        "validity_bonus": 1.0,
+    }
+
+
+class DatasetProblemBank:
+    def __init__(
+        self,
+        dataset_name: str = DEFAULT_DATASET_NAME,
+        split: str = DEFAULT_SPLIT,
+        max_problems: int = DEFAULT_MAX_PROBLEMS,
+    ) -> None:
+        self.dataset_name = dataset_name
+        self.split = split
+        self.max_problems = int(max_problems)
+        self._by_difficulty: dict[str, list[dict[str, Any]]] = {
+            "easy": [],
+            "medium": [],
+            "hard": [],
+        }
+        self._by_id: dict[str, dict[str, Any]] = {}
+
+        raw_rows = _load_raw_dataset(dataset_name=dataset_name, split=split, max_problems=max_problems)
+        for raw_row in raw_rows:
+            normalized = _normalise_row(raw_row, dataset_name)
+            if normalized is None:
+                continue
+            problem_id = str(normalized["problem_id"])
+            if problem_id in self._by_id:
+                continue
+            difficulty = str(normalized.get("difficulty_label", "medium")).lower()
+            if difficulty not in self._by_difficulty:
+                difficulty = "medium"
+                normalized["difficulty_label"] = difficulty
+            stored = _copy_problem(normalized)
+            self._by_difficulty[difficulty].append(stored)
+            self._by_id[problem_id] = stored
+
+        if not self._by_id:
+            raise ValueError(
+                f"No usable problems were found in dataset `{dataset_name}` split `{split}` with max_problems={max_problems}."
+            )
+
+    def sample(self, difficulty: str, rng: random.Random, recent_types: list[str]) -> dict[str, Any] | None:
+        requested = str(difficulty).strip().lower()
+        candidates = list(self._by_difficulty.get(requested, []))
+        if not candidates:
+            candidates = [problem for bucket in self._by_difficulty.values() for problem in bucket]
+        if not candidates:
+            return None
+
+        recent = {problem_type for problem_type in recent_types[-3:] if problem_type}
+        diverse = [problem for problem in candidates if str(problem.get("problem_type", "")) not in recent]
+        pool = diverse or candidates
+        return _copy_problem(rng.choice(pool))
+
+    def all_problem_ids(self) -> list[str]:
+        return sorted(self._by_id)
+
+    def get_by_id(self, problem_id: str) -> dict[str, Any]:
+        return _copy_problem(self._by_id[str(problem_id)])
+
+    def problem_types_for_difficulty(self, difficulty: str) -> list[str]:
+        requested = str(difficulty).strip().lower()
+        candidates = self._by_difficulty.get(requested, [])
+        return sorted({str(problem.get("problem_type", "")) for problem in candidates if problem.get("problem_type")})
+
+
+_BANK: DatasetProblemBank | None = None
+_BANK_CONFIG: tuple[str, str, int] | None = None
+
+
+def get_problem_bank(**kwargs: Any) -> DatasetProblemBank:
+    global _BANK, _BANK_CONFIG
+
+    dataset_name = str(kwargs.get("dataset_name", DEFAULT_DATASET_NAME))
+    split = str(kwargs.get("split", DEFAULT_SPLIT))
+    max_problems = int(kwargs.get("max_problems", DEFAULT_MAX_PROBLEMS))
+    config = (dataset_name, split, max_problems)
+    if _BANK is None or _BANK_CONFIG != config:
+        _BANK = DatasetProblemBank(
+            dataset_name=dataset_name,
+            split=split,
+            max_problems=max_problems,
+        )
+        _BANK_CONFIG = config
+    return _BANK
+
+
+def _extract_problem_statement(raw_row: dict[str, Any]) -> str:
+    value = raw_row.get("description") or raw_row.get("question") or raw_row.get("problem")
+    return str(value or "").strip()
+
+
+def _extract_pairs(raw_value: Any) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    if raw_value is None:
+        return pairs
+
+    if isinstance(raw_value, dict):
+        inputs = raw_value.get("input") or raw_value.get("inputs") or raw_value.get("stdin") or []
+        outputs = raw_value.get("output") or raw_value.get("outputs") or raw_value.get("stdout") or []
+        if isinstance(inputs, str):
+            inputs = [inputs]
+        if isinstance(outputs, str):
+            outputs = [outputs]
+        for raw_input, raw_output in zip(list(inputs), list(outputs)):
+            pairs.append((str(raw_input), str(raw_output)))
+        return pairs
+
+    if isinstance(raw_value, list):
+        for item in raw_value:
+            if isinstance(item, dict):
+                raw_input = item.get("input") or item.get("stdin") or item.get("in")
+                raw_output = item.get("output") or item.get("stdout") or item.get("out")
+                if raw_input is None or raw_output is None:
+                    continue
+                pairs.append((str(raw_input), str(raw_output)))
+            elif isinstance(item, (list, tuple)) and len(item) >= 2:
+                pairs.append((str(item[0]), str(item[1])))
+        return pairs
+
+    return pairs
+
+
+def _normalize_io_text(value: Any, *, ensure_trailing_newline: bool) -> str:
+    text = str(value or "")[:MAX_IO_CHARS]
+    if ensure_trailing_newline:
+        text = text.rstrip("\n")
+        return f"{text}\n" if text else "\n"
+    return text.strip()
+
+
+def _difficulty_fields(raw_row: dict[str, Any], dataset_name: str) -> tuple[str, float]:
+    dataset_key = dataset_name.lower()
+    if "code_contests" in dataset_key or "code-contests" in dataset_key:
+        raw_difficulty = raw_row.get("difficulty")
+        try:
+            rating = float(raw_difficulty)
+        except (TypeError, ValueError):
+            return "medium", 0.5
+        normalized = max(0.0, min((rating - 800.0) / (3500.0 - 800.0), 1.0))
+        if rating <= 1200:
+            label = "easy"
+        elif rating <= 1800:
+            label = "medium"
+        else:
+            label = "hard"
+        return label, round(normalized, 4)
+
+    raw_difficulty = str(raw_row.get("difficulty") or "").strip().lower()
+    if raw_difficulty in {"easy", "medium", "hard"}:
+        return raw_difficulty, {"easy": 0.25, "medium": 0.5, "hard": 0.75}[raw_difficulty]
+    return "medium", 0.5
+
+
+def _problem_id(raw_row: dict[str, Any], dataset_name: str) -> str:
+    prefix = "cc" if "code_contests" in dataset_name.lower() else "ds"
+    for key in ("problem_id", "id", "name", "source"):
+        value = raw_row.get(key)
+        if value is not None and str(value).strip():
+            candidate = re.sub(r"[^a-zA-Z0-9_]+", "_", str(value).strip()).strip("_")
+            if candidate:
+                return f"{prefix}_{candidate}"
+    digest = hashlib.sha256(repr(sorted(raw_row.items())).encode("utf-8")).hexdigest()
+    return f"{prefix}_{digest[:12]}"
+
+
+def _extract_section(statement: str, heading: str) -> str:
+    pattern = re.compile(
+        rf"{heading}\s*:?[\r\n]+(.*?)(?=\n[A-Z][A-Za-z ]{{1,30}}:?[\r\n]|\Z)",
+        flags=re.IGNORECASE | re.DOTALL,
+    )
+    match = pattern.search(statement)
+    return match.group(1).strip() if match else ""
+
+
+def _extract_constraints(statement: str) -> str:
+    constraints = _extract_section(statement, "constraints")
+    return constraints or "See problem statement."
+
+
+def _infer_problem_type(raw_row: dict[str, Any], statement: str) -> str:
+    parts: list[str] = [statement]
+    tags = raw_row.get("tags")
+    if isinstance(tags, list):
+        parts.extend(str(tag) for tag in tags)
+    elif isinstance(tags, str):
+        parts.append(tags)
+    for key in ("source", "name"):
+        value = raw_row.get(key)
+        if value:
+            parts.append(str(value))
+    text = " ".join(parts).lower()
+
+    keyword_map = {
+        "graph": "graph",
+        "tree": "tree",
+        "dynamic programming": "dp",
+        " dp ": "dp",
+        "string": "string",
+        "array": "array",
+        "greedy": "greedy",
+        "math": "math",
+        "sort": "sorting",
+        "binary search": "search",
+    }
+    padded = f" {text} "
+    for needle, problem_type in keyword_map.items():
+        haystack = padded if needle.startswith(" ") and needle.endswith(" ") else text
+        if needle in haystack:
+            return problem_type
+    return "implementation"
+
+
+def _copy_problem(problem: dict[str, Any]) -> dict[str, Any]:
+    copied = dict(problem)
+    copied["test_cases"] = [dict(test_case) for test_case in problem.get("test_cases", [])]
+    copied["visible_problem"] = dict(problem.get("visible_problem", {}))
+    examples = copied["visible_problem"].get("examples")
+    if isinstance(examples, list):
+        copied["visible_problem"]["examples"] = [dict(example) for example in examples]
+    return copied

env/generator.py

@@ -109,17 +109,43 @@ def normalize_problem(problem_dict: dict[str, Any]) -> dict[str, Any]:
     normalized["problem"] = str(problem_dict.get("problem", "")).strip()
     normalized["input_format"] = str(problem_dict.get("input_format", "")).strip()
     normalized["constraints"] = str(problem_dict.get("constraints", "")).strip()
-    normalized["test_cases"] = [dict(test_case) for test_case in problem_dict.get("test_cases", [])]
-    normalized["visible_problem"] = dict(problem_dict.get("visible_problem", {}))
+    normalized_cases: list[dict[str, Any]] = []
+    for test_case in problem_dict.get("test_cases", []):
+        case = dict(test_case)
+        if "output" not in case and "expected_output" in case:
+            case["output"] = case.get("expected_output")
+        if "is_visible" not in case and "visible" in case:
+            case["is_visible"] = bool(case.get("visible"))
+        normalized_cases.append(case)
+    normalized["test_cases"] = normalized_cases
+    normalized_visible = dict(problem_dict.get("visible_problem", {}))
+    examples = normalized_visible.get("examples")
+    if isinstance(examples, list):
+        normalized_visible["examples"] = [dict(example) for example in examples]
+    normalized["visible_problem"] = normalized_visible
     return normalized
 
 
 class GeneratorAgent:
     """Deterministic, dependency-free generator for DSA-style problems."""
 
-    def __init__(self, deterministic: bool = True) -> None:
+    def __init__(
+        self,
+        deterministic: bool = True,
+        use_dataset: bool = False,
+        dataset_kwargs: dict[str, Any] | None = None,
+    ) -> None:
         self.deterministic = deterministic
+        self._use_dataset = use_dataset
+        self._dataset_kwargs = dict(dataset_kwargs or {})
         self.templates = _build_templates()
+        self._bank = None
+
+    def _ensure_bank(self) -> None:
+        if self._bank is None:
+            from env.dataset_loader import get_problem_bank
+
+            self._bank = get_problem_bank(**self._dataset_kwargs)
 
     def generate_problem(
         self,
@@ -130,6 +156,30 @@ class GeneratorAgent:
     ) -> dict[str, Any]:
         history = history or {}
         target_tier = _difficulty_to_tier(difficulty_level)
+
+        if self._use_dataset:
+            self._ensure_bank()
+            if problem_id:
+                try:
+                    problem = self._bank.get_by_id(problem_id)
+                except KeyError:
+                    problem = None
+                if problem is not None:
+                    normalized_problem = normalize_problem(problem)
+                    if validate_problem(normalized_problem):
+                        return normalized_problem
+
+            rng = self._rng_for(target_tier, history, problem_id, family_weights or {})
+            problem = self._bank.sample(
+                self._difficulty_to_label(self._tier_to_scalar(target_tier)),
+                rng,
+                list(history.get("problem_types", [])),
+            )
+            if problem is not None:
+                normalized_problem = normalize_problem(problem)
+                if validate_problem(normalized_problem):
+                    return normalized_problem
+
         rng = self._rng_for(target_tier, history, problem_id, family_weights or {})
         template = self._choose_template(
             target_tier,
@@ -250,6 +300,27 @@ class GeneratorAgent:
     def _tier_to_scalar(self, tier: int) -> float:
         return {1: 0.25, 2: 0.5, 3: 0.75}.get(tier, 0.5)
 
+    def _difficulty_to_label(self, difficulty: float) -> str:
+        if difficulty < 0.35:
+            return "easy"
+        if difficulty < 0.70:
+            return "medium"
+        return "hard"
+
+    def problem_types_for_difficulty(self, difficulty: str) -> list[str]:
+        if self._use_dataset:
+            self._ensure_bank()
+            return self._bank.problem_types_for_difficulty(difficulty)
+
+        normalized = str(difficulty).strip().lower()
+        return sorted(
+            {
+                template.problem_type
+                for template in self.templates
+                if DIFFICULTY_LABELS.get(template.difficulty_tier) == normalized
+            }
+        )
+
 
 def _difficulty_to_tier(difficulty_level: int | float | str) -> int:
     if isinstance(difficulty_level, str):

env/test_cases.py

@@ -5,7 +5,13 @@ from typing import Any
 from env.generator import DIFFICULTY_LABELS, GeneratorAgent, VISIBLE_TEST_COUNT
 
 
-def load_problem_bank() -> list[dict[str, Any]]:
+def load_problem_bank(use_dataset: bool = False) -> list[dict[str, Any]]:
+    if use_dataset:
+        from env.dataset_loader import get_problem_bank
+
+        bank = get_problem_bank()
+        return [bank.get_by_id(problem_id) for problem_id in bank.all_problem_ids()[:200]]
+
     generator = GeneratorAgent()
     bank = []
     for template in generator.templates:

pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "uvicorn>=0.24.0",
     "httpx>=0.28.0",
     "huggingface_hub>=0.34.0,<0.36",
+    "datasets>=2.18.0",
     "transformers>=4.51.3,<5.7",
     "peft>=0.18.0,<0.20",
 ]

requirements.txt

@@ -4,5 +4,6 @@ fastapi>=0.104.0
 uvicorn>=0.24.0
 pydantic>=2.0.0
 huggingface_hub>=0.34.0,<0.36
+datasets>=2.18.0
 transformers>=4.51.3,<5.7
 peft>=0.18.0,<0.20

scripts/test_dataset_mode.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from env import dataset_loader
+from env.adapt_env import AdaptEnvironment
+from env.generator import GeneratorAgent, validate_problem
+from env.test_cases import load_problem_bank
+from models import AdaptAction
+
+
+class FakeBank:
+    def __init__(self, problem: dict) -> None:
+        self.problem = problem
+
+    def sample(self, difficulty: str, rng, recent_types: list[str]) -> dict:
+        del difficulty, rng, recent_types
+        return _copy_problem(self.problem)
+
+    def all_problem_ids(self) -> list[str]:
+        return [self.problem["problem_id"]]
+
+    def get_by_id(self, problem_id: str) -> dict:
+        if problem_id != self.problem["problem_id"]:
+            raise KeyError(problem_id)
+        return _copy_problem(self.problem)
+
+    def problem_types_for_difficulty(self, difficulty: str) -> list[str]:
+        del difficulty
+        return [self.problem["problem_type"]]
+
+
+def _copy_problem(problem: dict) -> dict:
+    copied = dict(problem)
+    copied["test_cases"] = [dict(test_case) for test_case in problem.get("test_cases", [])]
+    copied["visible_problem"] = dict(problem.get("visible_problem", {}))
+    examples = copied["visible_problem"].get("examples")
+    if isinstance(examples, list):
+        copied["visible_problem"]["examples"] = [dict(example) for example in examples]
+    return copied
+
+
+def main() -> None:
+    template_problem = GeneratorAgent().generate_problem(1, {}, problem_id="sum_even_numbers")
+    dataset_problem = _copy_problem(template_problem)
+    dataset_problem["problem_id"] = "cc_stub_sum_even_numbers"
+    dataset_problem["generation_mode"] = "dataset"
+    dataset_problem["validity_bonus"] = 1.0
+
+    fake_bank = FakeBank(dataset_problem)
+    original_bank = dataset_loader._BANK
+    original_config = dataset_loader._BANK_CONFIG
+    dataset_loader._BANK = fake_bank
+    dataset_loader._BANK_CONFIG = ("deepmind/code_contests", "train", 5000)
+
+    try:
+        loaded_bank = load_problem_bank(use_dataset=True)
+        assert loaded_bank
+        assert validate_problem(loaded_bank[0])
+
+        generated = GeneratorAgent(use_dataset=True).generate_problem("easy", {})
+        assert generated["problem_id"] == dataset_problem["problem_id"]
+        assert generated["generation_mode"] == "dataset"
+        assert validate_problem(generated)
+
+        env = AdaptEnvironment(use_dataset=True)
+        observation = env.reset(difficulty="easy")
+        assert env.problem["generation_mode"] == "dataset"
+        assert observation.problem_type == "sum_even_numbers"
+
+        result = env.step(
+            AdaptAction(
+                code=(
+                    "n=int(input())\n"
+                    "nums=list(map(int,input().split()))\n"
+                    "print(sum(x for x in nums if x % 2 == 0))"
+                )
+            )
+        )
+        assert result.pass_rate == 1.0
+        print("Dataset mode smoke tests passed")
+    finally:
+        dataset_loader._BANK = original_bank
+        dataset_loader._BANK_CONFIG = original_config
+
+
+if __name__ == "__main__":
+    main()

scripts/test_verifier.py

@@ -18,6 +18,12 @@ test_cases = [
     {"input": "5\n8 8 8 8 8\n", "output": "40", "is_visible": False},
 ]
 
+empirical_test_cases = [
+    {"input": "10\n", "output": "45", "is_visible": False},
+    {"input": "200\n", "output": "19900", "is_visible": False},
+    {"input": "1000\n", "output": "499500", "is_visible": False},
+]
+
 correct_code = """
 n = int(input())
 nums = list(map(int, input().split()))
@@ -90,3 +96,19 @@ assert info_optimal["verifier_components"]["hidden_correctness"] == 1.0
 assert info_optimal["verifier_components"]["anti_cheat_compliance"] == 1.0
 assert reward_safety == 0.0
 assert info_safety["execution_status"] == "safety_violation"
+
+linear_code = "n = int(input()); print(sum(range(n)))"
+quadratic_code = "n = int(input()); print(sum(i*j for i in range(n) for j in range(n)))"
+_, linear_result = verify(linear_code, empirical_test_cases)
+_, quadratic_result = verify(quadratic_code, empirical_test_cases)
+assert linear_result["efficiency_score"] >= quadratic_result["efficiency_score"], (
+    "Empirical complexity: O(n) should score >= O(n^2)"
+)
+
+small_alloc = "n = int(input()); print(n)"
+large_alloc = "n = int(input()); x = [0] * (n * 10000); print(len(x))"
+_, small_result = verify(small_alloc, empirical_test_cases)
+_, large_result = verify(large_alloc, empirical_test_cases)
+assert small_result["efficiency_score"] >= large_result["efficiency_score"], (
+    "Empirical complexity: small allocation should score >= large allocation"
+)

server/app.py

@@ -59,6 +59,9 @@ class TrainRequest(BaseModel):
     evaluation_episodes: Optional[int] = None
     baseline_eval: Optional[bool] = None
     generator_mode: Optional[str] = None
+    use_dataset: bool = False
+    dataset_name: str = "deepmind/code_contests"
+    dataset_max_problems: int = 5000
     disable_wandb: Optional[bool] = None
     save_merged_model: Optional[bool] = None
 

test.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from scripts.test_dataset_mode import main as run_dataset_mode_smoke
 from scripts.test_env import main as run_env_smoke
 from scripts.test_space_api import main as run_space_api_smoke
 from scripts.test_training_config import main as run_training_config_smoke
@@ -9,6 +10,7 @@ from verifier.verifier import verify
 
 
 def main() -> None:
+    run_dataset_mode_smoke()
     run_env_smoke()
     run_space_api_smoke()
     run_training_config_smoke()

training/train_grpo.py

@@ -59,6 +59,9 @@ class TrainingConfig:
     wandb_run_name: str | None = None
     generator_mode: str = "reward_aware"
     non_deterministic_generator: bool = False
+    use_dataset: bool = False
+    dataset_name: str = "deepmind/code_contests"
+    dataset_max_problems: int = 5000
     trace_logging_enabled: bool = True
     checkpoint_log_interval_steps: int = 10
     save_merged_model: bool = False
@@ -207,6 +210,9 @@ def namespace_to_config(args: argparse.Namespace) -> TrainingConfig:
         wandb_run_name=args.wandb_run_name,
         generator_mode=args.generator_mode,
         non_deterministic_generator=args.non_deterministic_generator,
+        use_dataset=args.use_dataset,
+        dataset_name=args.dataset_name,
+        dataset_max_problems=args.dataset_max_problems,
         trace_logging_enabled=args.trace_logging_enabled,
         checkpoint_log_interval_steps=args.checkpoint_log_interval_steps,
         save_merged_model=getattr(args, "save_merged_model", False),
@@ -258,6 +264,8 @@ class GeneratorController:
     mode: str = "heuristic"
     deterministic: bool = True
     temperature: float = 0.5
+    use_dataset: bool = False
+    dataset_kwargs: dict[str, Any] = field(default_factory=dict)
     generator: GeneratorAgent = field(init=False)
     history: dict[str, Any] = field(
         default_factory=lambda: {
@@ -272,10 +280,14 @@ class GeneratorController:
     family_productivity: dict[str, float] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
-        self.generator = GeneratorAgent(deterministic=self.deterministic)
+        self.generator = GeneratorAgent(
+            deterministic=self.deterministic,
+            use_dataset=self.use_dataset,
+            dataset_kwargs=self.dataset_kwargs,
+        )
         if not self.family_productivity:
             self.family_productivity = {
-                template.problem_type: 0.0 for template in self.generator.templates
+                family: 0.0 for family in self._known_problem_families()
             }
 
     @property
@@ -306,11 +318,14 @@ class GeneratorController:
         if self.mode != "reward_aware":
             return None
 
-        eligible = [
-            template.problem_type
-            for template in self.generator.templates
-            if DIFFICULTY_LABELS[template.difficulty_tier] == difficulty
-        ]
+        if self.use_dataset:
+            eligible = self.generator.problem_types_for_difficulty(difficulty)
+        else:
+            eligible = [
+                template.problem_type
+                for template in self.generator.templates
+                if DIFFICULTY_LABELS[template.difficulty_tier] == difficulty
+            ]
         if not eligible:
             return None
 
@@ -319,6 +334,14 @@ class GeneratorController:
         exp_values = [math.exp(logit - max_logit) for logit in logits]
         return {family: value for family, value in zip(eligible, exp_values)}
 
+    def _known_problem_families(self) -> list[str]:
+        if self.use_dataset:
+            families: set[str] = set()
+            for difficulty in ("easy", "medium", "hard"):
+                families.update(self.generator.problem_types_for_difficulty(difficulty))
+            return sorted(families)
+        return sorted({template.problem_type for template in self.generator.templates})
+
     def update(
         self,
         problem: dict[str, Any],
@@ -695,6 +718,8 @@ def run_policy_evaluation(
     tokenizer: Any,
     generator_mode: str,
     deterministic_generator: bool,
+    use_dataset: bool,
+    dataset_kwargs: dict[str, Any],
     episodes: int,
     logger: TrainingLogger,
     phase: str,
@@ -703,6 +728,8 @@ def run_policy_evaluation(
     controller = GeneratorController(
         mode=generator_mode,
         deterministic=deterministic_generator,
+        use_dataset=use_dataset,
+        dataset_kwargs=dataset_kwargs,
     )
     schedule = ["easy"] * (episodes // 3 + (1 if episodes % 3 > 0 else 0))
     schedule += ["medium"] * (episodes // 3 + (1 if episodes % 3 > 1 else 0))
@@ -1050,6 +1077,11 @@ def run_training(
     controller = GeneratorController(
         mode="reward_aware" if config.generator_mode == "reward_aware" else "heuristic",
         deterministic=not config.non_deterministic_generator,
+        use_dataset=config.use_dataset,
+        dataset_kwargs={
+            "dataset_name": config.dataset_name,
+            "max_problems": config.dataset_max_problems,
+        },
     )
     logger = TrainingLogger(
         output_dir=output_dir,
@@ -1110,6 +1142,11 @@ def run_training(
             tokenizer=tokenizer,
             generator_mode=controller.mode,
             deterministic_generator=not config.non_deterministic_generator,
+            use_dataset=config.use_dataset,
+            dataset_kwargs={
+                "dataset_name": config.dataset_name,
+                "max_problems": config.dataset_max_problems,
+            },
             episodes=config.evaluation_episodes,
             logger=logger,
             phase="baseline_eval",
@@ -1206,6 +1243,11 @@ def run_training(
             tokenizer=tokenizer,
             generator_mode=controller.mode,
             deterministic_generator=not config.non_deterministic_generator,
+            use_dataset=config.use_dataset,
+            dataset_kwargs={
+                "dataset_name": config.dataset_name,
+                "max_problems": config.dataset_max_problems,
+            },
             episodes=config.evaluation_episodes,
             logger=logger,
             phase="trained_eval",
@@ -1290,6 +1332,9 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Disable deterministic fallback seeding for generator rollouts.",
     )
+    parser.add_argument("--use-dataset", action="store_true")
+    parser.add_argument("--dataset-name", default="deepmind/code_contests")
+    parser.add_argument("--dataset-max-problems", type=int, default=5000)
     return parser
 
 

verifier/complexity.py

@@ -1,9 +1,17 @@
 from __future__ import annotations
 
 import ast
+import math
+import os
+import re
 from dataclasses import dataclass
 from typing import Any
 
+from env.executor import run_code as execute_submission
+
+PROBE_TIMEOUT_SECONDS = 2.0
+METRICS_PATTERN = re.compile(r"ADAPT_METRICS:\s*time_ms=([0-9.]+)\s+peak_kb=([0-9.]+)")
+
 
 @dataclass
 class ComplexitySignals:
@@ -69,7 +77,109 @@ def _call_name(node: ast.AST) -> str:
     return ""
 
 
-def analyze_code_complexity(code: str) -> dict[str, Any]:
+def _probe_timeout() -> float:
+    raw_value = os.getenv("ADAPT_PROBE_TIMEOUT", str(PROBE_TIMEOUT_SECONDS))
+    try:
+        timeout = float(raw_value)
+    except ValueError:
+        return PROBE_TIMEOUT_SECONDS
+    return timeout if timeout > 0 else PROBE_TIMEOUT_SECONDS
+
+
+def _build_measurement_harness(code: str) -> str:
+    return f"""
+import sys as _adapt_sys
+import time as _adapt_time
+import tracemalloc as _adapt_tracemalloc
+
+_adapt_globals = {{"__name__": "__main__"}}
+_adapt_source = {code!r}
+_adapt_tracemalloc.start()
+_adapt_t0 = _adapt_time.perf_counter()
+exec(compile(_adapt_source, "<submission>", "exec"), _adapt_globals, _adapt_globals)
+_adapt_t1 = _adapt_time.perf_counter()
+_adapt_peak_kb = _adapt_tracemalloc.get_traced_memory()[1] / 1024
+_adapt_tracemalloc.stop()
+print(
+    f"ADAPT_METRICS: time_ms={{(_adapt_t1 - _adapt_t0) * 1000:.3f}} peak_kb={{_adapt_peak_kb:.1f}}",
+    file=_adapt_sys.stderr,
+)
+"""
+
+
+def _parse_harness_output(stderr: str) -> tuple[float, float]:
+    match = METRICS_PATTERN.search(str(stderr or ""))
+    if match is None:
+        return 0.0, 0.0
+    try:
+        return float(match.group(1)), float(match.group(2))
+    except ValueError:
+        return 0.0, 0.0
+
+
+def _fit_scaling_exponent(sizes: list[float], values: list[float]) -> float:
+    if len(sizes) < 2 or len(values) < 2:
+        return 1.0
+    log_n = [math.log(max(size, 1.0)) for size in sizes]
+    log_v = [math.log(max(value, 1e-6)) for value in values]
+    count = len(log_n)
+    mean_n = sum(log_n) / count
+    mean_v = sum(log_v) / count
+    numerator = sum((log_n[index] - mean_n) * (log_v[index] - mean_v) for index in range(count))
+    denominator = sum((log_n[index] - mean_n) ** 2 for index in range(count))
+    return numerator / denominator if denominator > 1e-9 else 1.0
+
+
+def _exponent_to_score(alpha: float) -> float:
+    if alpha < 0.1:
+        return 1.0
+    if alpha < 1.2:
+        return 0.85
+    if alpha < 1.6:
+        return 0.75
+    if alpha < 2.3:
+        return 0.50
+    if alpha < 3.2:
+        return 0.20
+    return 0.0
+
+
+def _memory_to_score(peak_kb: float) -> float:
+    mb = peak_kb / 1024.0
+    if mb < 1:
+        return 1.0
+    if mb < 10:
+        return 0.85
+    if mb < 50:
+        return 0.65
+    if mb < 256:
+        return 0.40
+    return 0.10
+
+
+def _hints_from_scores(time_score: float, space_score: float, time_alpha: float) -> list[str]:
+    hints: list[str] = []
+    if time_alpha >= 2.3:
+        hints.append("Reduce quadratic-or-worse work; measured runtime growth looks steep across larger inputs.")
+    elif time_score < 0.85:
+        hints.append("Consider a more scalable algorithm so runtime grows more gently with input size.")
+    if space_score < 0.85:
+        hints.append("Reduce peak memory usage by avoiding large intermediate containers when possible.")
+    return hints
+
+
+def _merge_hints(*hint_groups: list[str]) -> list[str]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for group in hint_groups:
+        for hint in group:
+            if hint and hint not in seen:
+                seen.add(hint)
+                merged.append(hint)
+    return merged
+
+
+def _heuristic_fallback(code: str) -> dict[str, Any]:
     try:
         tree = ast.parse(code)
     except SyntaxError:
@@ -78,7 +188,7 @@ def analyze_code_complexity(code: str) -> dict[str, Any]:
             "space_complexity_score": 0.0,
             "efficiency_score": 0.0,
             "optimization_hints": [],
-            "complexity_signals": {},
+            "complexity_signals": {"measurement_source": "heuristic"},
         }
 
     visitor = ComplexityVisitor()
@@ -126,5 +236,70 @@ def analyze_code_complexity(code: str) -> dict[str, Any]:
             "generator_expressions": signals.generator_expressions,
             "sorting_calls": signals.sorting_calls,
             "materialized_builtin_inputs": signals.materialized_builtin_inputs,
+            "measurement_source": "heuristic",
         },
     }
+
+
+def _empirical_complexity(code: str, probe_inputs: list[str]) -> dict[str, Any]:
+    heuristic = _heuristic_fallback(code)
+    if len(probe_inputs) < 3:
+        return heuristic
+
+    harness = _build_measurement_harness(code)
+    sizes: list[float] = []
+    times: list[float] = []
+    mem_peaks: list[float] = []
+    for probe_input in probe_inputs:
+        result = execute_submission(harness, probe_input, timeout_seconds=_probe_timeout())
+        if bool(result.get("timed_out")) or int(result.get("exit_code", 0)) != 0:
+            return heuristic
+        wall_ms, peak_kb = _parse_harness_output(str(result.get("stderr", "")))
+        if wall_ms <= 0.0 and peak_kb <= 0.0:
+            return heuristic
+        sizes.append(float(len(probe_input)))
+        times.append(float(wall_ms))
+        mem_peaks.append(float(peak_kb))
+
+    if len(sizes) < 3:
+        return heuristic
+
+    empirical_time_score = _exponent_to_score(_fit_scaling_exponent(sizes, times))
+    empirical_space_score = _memory_to_score(max(mem_peaks))
+    time_alpha = _fit_scaling_exponent(sizes, times)
+    space_alpha = _fit_scaling_exponent(sizes, mem_peaks)
+
+    time_score = min(empirical_time_score, float(heuristic["time_complexity_score"]))
+    space_score = min(empirical_space_score, float(heuristic["space_complexity_score"]))
+    efficiency_score = round(min(0.7 * time_score + 0.3 * space_score, float(heuristic["efficiency_score"])), 4)
+    optimization_hints = _merge_hints(
+        _hints_from_scores(time_score, space_score, time_alpha),
+        list(heuristic.get("optimization_hints", [])),
+    )
+
+    complexity_signals = dict(heuristic.get("complexity_signals", {}))
+    complexity_signals.update(
+        {
+            "time_exponent": round(time_alpha, 4),
+            "space_exponent": round(space_alpha, 4),
+            "peak_memory_kb": round(max(mem_peaks), 1),
+            "measurement_source": "empirical",
+        }
+    )
+
+    return {
+        "time_complexity_score": round(time_score, 4),
+        "space_complexity_score": round(space_score, 4),
+        "efficiency_score": efficiency_score,
+        "optimization_hints": optimization_hints,
+        "complexity_signals": complexity_signals,
+    }
+
+
+def analyze_code_complexity(code: str, probe_inputs: list[str] | None = None) -> dict[str, Any]:
+    if probe_inputs and len(probe_inputs) >= 3:
+        try:
+            return _empirical_complexity(code, probe_inputs)
+        except Exception:
+            pass
+    return _heuristic_fallback(code)

verifier/verifier.py

@@ -14,9 +14,9 @@ def verify(
     step_number: int = 1,
 ) -> tuple[float, dict[str, Any]]:
     precheck = validate_code(code)
-    complexity = analyze_code_complexity(code)
 
     if not precheck["syntax_ok"] or not precheck["safety_ok"]:
+        complexity = analyze_code_complexity(code)
         reward, metrics = compute_pass_rate(
             [],
             step_number=step_number,
@@ -33,6 +33,9 @@ def verify(
             "error": str(precheck["error"]),
         }
 
+    probe_inputs = _build_probe_inputs(test_cases)
+    complexity = analyze_code_complexity(code, probe_inputs=probe_inputs)
+
     results: list[dict[str, Any]] = []
     for index, test_case in enumerate(test_cases):
         if isinstance(test_case, dict):
@@ -91,6 +94,24 @@ def verify(
     }
 
 
+def _build_probe_inputs(test_cases: list[dict[str, Any]] | list[tuple[str, str]]) -> list[str]:
+    inputs: list[str] = []
+    for test_case in test_cases:
+        if isinstance(test_case, dict):
+            raw_input = test_case.get("input")
+        elif test_case:
+            raw_input = test_case[0]
+        else:
+            raw_input = None
+        if isinstance(raw_input, str):
+            inputs.append(raw_input)
+
+    inputs_sorted = sorted(set(inputs), key=len)
+    if len({len(item) for item in inputs_sorted}) < 3:
+        return []
+    return inputs_sorted
+
+
 def _build_feedback(metrics: dict[str, Any], *, error: str = "") -> str:
     execution_status = str(metrics.get("execution_status", "unknown"))
     if execution_status == "syntax_error":