# Subsystem: root

## app.py
- Doc: Drop-in entry point that demonstrates how to use the topogpt3 package.
- Layer: utility
- Language: py
- Symbols:
  - `run_inference` (function, line 46) `def run_inference(prompt, checkpoint_dir, checkpoint_name, max_new_tokens, temperature, top_k, repetition_penalty...`
  - `run_inference_hrm` (function, line 71) `def run_inference_hrm(prompt, checkpoint_dir, checkpoint_name, max_new_tokens, temperature, top_k...`
  - `run_training` (function, line 105) `def run_training(scale, start_tier, device, prepare_data)`
  - `_build_parser` (function, line 121) `def _build_parser()`
  - `main` (function, line 159) `def main(argv)`
- Depends on: `topogpt3/__init__.py`

## infer_exploitgym.py
- Doc: Standalone inference script for TopoExploit.
- Layer: utility
- Language: py
- Symbols:
  - `load_task_ids` (function, line 41) `def load_task_ids()`
  - `load_task` (function, line 49) `def load_task(task_id)`
  - `build_prompt` (function, line 122) `def build_prompt(task_info, tier)`
  - `load_model` (function, line 136) `def load_model(ckpt_dir, ckpt_name, device)`
  - `generate` (function, line 177) `def generate(model, tokenizer, prompt)`
  - `run_single_prompt` (function, line 257) `def run_single_prompt(args, model, tokenizer)`
  - `run_eval_holdout` (function, line 274) `def run_eval_holdout(args, model, tokenizer)`
  - `run_interactive` (function, line 331) `def run_interactive(args, model, tokenizer)`
  - `parse_args` (function, line 380) `def parse_args()`
  - `main` (function, line 420) `def main()`
  - `sample` (function, line 205) `def sample(logits, seen_ids)`
- Depends on: `topogpt3/model.py`, `topogpt3/train.py`

## install.sh
- Layer: utility
- Language: sh

## run_exploitgym.sh
- Doc: TopoExploit: 125M params trained on ExploitGym  Usage: ./run_exploitgym.sh prepare     -- clone...
- Layer: utility
- Language: sh

## run_exploitgym_v2.sh
- Layer: utility
- Language: sh
- Symbols:
  - `banner` (function, line 24)
  - `train_v2` (function, line 32)
  - `eval_v2` (function, line 45)
  - `infer_v2` (function, line 54)

## run_hodge_cm_ablation.sh
- Doc: Hodge-CM offline ablation runner (GPU si el build torch lo permite, si no CPU).
- Layer: utility
- Language: sh

## run_merged.sh
- Layer: utility
- Language: sh
- Symbols:
  - `kill_gpu_processes` (function, line 33)
  - `restore_gpu_processes` (function, line 63)
  - `banner` (function, line 84)
  - `prepare_data` (function, line 93)
  - `train_merged` (function, line 107)
  - `eval_merged` (function, line 119)
  - `infer_merged` (function, line 128)

## synthetic_dataset.py
- Doc: Synthetic Dataset Generator for TopoGPT2.
- Layer: data_access
- Language: py
- Symbols:
  - `LLMBackend` (class, line 61) `class LLMBackend`
  - `GroqBackend` (class, line 71) `class GroqBackend(LLMBackend)`
  - `OpenRouterBackend` (class, line 121) `class OpenRouterBackend(LLMBackend)`
  - `OllamaBackend` (class, line 177) `class OllamaBackend(LLMBackend)`
  - `build_backend` (method, line 227) `def build_backend(provider, model)`
  - `validate_sample` (method, line 330) `def validate_sample(sample)`
  - `ProcessedManifest` (class, line 364) `class ProcessedManifest`
  - `SyntheticDatasetGenerator` (class, line 399) `class SyntheticDatasetGenerator`
  - `build_logger` (method, line 614) `def build_logger(level)`
  - `parse_args` (method, line 625) `def parse_args()`
  - `load_paths` (method, line 652) `def load_paths(paths_arg, paths_file, max_files)`
  - `main` (method, line 667) `def main()`
  - `generate` (method, line 64) `def generate(self, prompt)`
  - `name` (method, line 67) `def name(self)`
  - `__init__` (method, line 78) `def __init__(self, model, api_key, max_tokens, temperature, timeout)`
  - `name` (method, line 95) `def name(self)`
  - `generate` (method, line 98) `def generate(self, prompt)`
  - `__init__` (method, line 132) `def __init__(self, model, api_key, max_tokens, temperature, timeout)`
  - `name` (method, line 151) `def name(self)`
  - `generate` (method, line 154) `def generate(self, prompt)`
  - `__init__` (method, line 184) `def __init__(self, model, host, max_tokens, temperature, timeout)`
  - `name` (method, line 198) `def name(self)`
  - `generate` (method, line 201) `def generate(self, prompt)`
  - `load` (method, line 374) `def load(path)`
  - `save` (method, line 387) `def save(self, path)`
  - `__init__` (method, line 418) `def __init__(self, backend, output_path, manifest_path, logger, max_workers, max_file_chars)`
  - `_jsonl_writer` (method, line 447) `def _jsonl_writer(self)`
  - `_enqueue_sample` (method, line 465) `def _enqueue_sample(self, sample)`
  - `_flush_writer` (method, line 468) `def _flush_writer(self)`
  - `_read_file` (method, line 477) `def _read_file(self, path)`
  - `_build_prompt` (method, line 490) `def _build_prompt(self, content, lang)`
  - `_generate_sample` (method, line 496) `def _generate_sample(self, content, lang)`
  - `process_file` (method, line 533) `def process_file(self, path)`
  - `process_batch` (method, line 568) `def process_batch(self, paths)`
  - `finish` (method, line 590) `def finish(self)`
- Imported by: `topogpt3/model.py`

## transfer_weights.py
- Doc: Transfer weights from a smaller TopoGPT model to a larger one.
- Layer: utility
- Language: py
- Symbols:
  - `transfer_weights` (function, line 31) `def transfer_weights(state_small, model_large, logger)`
  - `_copy_with_padding` (function, line 135) `def _copy_with_padding(small, large)`
  - `main` (function, line 147) `def main()`
- Depends on: `topogpt3/model.py`