# API (page 1 of 2)
Pages: [API.md](API.md), [API_p2.md](API_p2.md)

## app.py
Depends on: `topogpt3/__init__.py`
- `run_inference` (function) `app.py:46` `def run_inference(prompt, checkpoint_dir, checkpoint_name, max_new_tokens, temperature, top_k, repetition_penalty...` -- Run the standard sampler and return the generated completion text.
- `run_inference_hrm` (function) `app.py:71` `def run_inference_hrm(prompt, checkpoint_dir, checkpoint_name, max_new_tokens, temperature, top_k...` -- Run the hierarchical recursive sampler and return the completion.
- `run_training` (function) `app.py:105` `def run_training(scale, start_tier, device, prepare_data)` -- Run the full TopoGPT3 curriculum trainer.
- `main` (function) `app.py:159` `def main(argv)` -- Entry point invoked when the file is executed as a script.

## eval/analyze.py
- `pass_at_k` (function) `eval/analyze.py:21` `def pass_at_k(n, c, k)` -- Unbiased estimator from the HumanEval paper.
- `classify_error` (function) `eval/analyze.py:32` `def classify_error(msg, candidate_src)` -- Heuristic single-label error classifier.
- `load_jsonl` (function) `eval/analyze.py:56` `def load_jsonl(path)`
- `summarize` (function) `eval/analyze.py:61` `def summarize(paths)`
- `main` (function) `eval/analyze.py:103` `def main()`

## eval/analyze_results.py
- `load_records` (function) `eval/analyze_results.py:26` `def load_records(path)`
- `summarize` (function) `eval/analyze_results.py:31` `def summarize(records)`
- `show_failures` (function) `eval/analyze_results.py:44` `def show_failures(records, task_id)`
- `main` (function) `eval/analyze_results.py:82` `def main()`

## eval/diag_static.py
Depends on: `topogpt3/__init__.py`, `topogpt3/model.py`, `topogpt3/train.py`
- `phase_discretization` (function) `eval/diag_static.py:49` `def phase_discretization(K, n_samples, seed)` -- Muestrea n_samples overlaps aleatorios <u_i | u_j> sobre los vectores singulares de K y mide cuanto se aleja su fase...
- `synthetic_winding` (function) `eval/diag_static.py:95` `def synthetic_winding(K, n_windows, window_size)` -- Como el checkpoint es estatico, no hay trayectoria temporal.
- `static_kappa` (function) `eval/diag_static.py:144` `def static_kappa(K)`
- `context_length_diagnostic` (function) `eval/diag_static.py:171` `def context_length_diagnostic(model, tracker, device, lengths)`
- `main` (function) `eval/diag_static.py:248` `def main()`

## eval/governor.py
Imported by: `eval/governor_smoke.py`
- `TokenStream.__init__` (method) `eval/governor.py:56` `def __init__(self)`
- `TokenStream.put` (method) `eval/governor.py:62` `def put(self, tok)`
- `TokenStream.mark_done` (method) `eval/governor.py:67` `def mark_done(self)`
- `TokenStream.drain` (method) `eval/governor.py:72` `def drain(self)` -- Return all tokens emitted so far, atomic snapshot.
- `TokenStream.wait_for_new` (method) `eval/governor.py:77` `def wait_for_new(self, timeout)` -- Block up to `timeout` seconds for a new token.
- `TokenStream.is_closed` (method) `eval/governor.py:86` `def is_closed(self)`
- `GenerationGovernor.__init__` (method) `eval/governor.py:156` `def __init__(self, model, ctx, stream, max_new_tokens, temperature, top_k, repetition_penalty, max_seq_len)`
- `GenerationGovernor.cancel` (method) `eval/governor.py:177` `def cancel(self)` -- Asynchronously stop the generation.
- `GenerationGovernor.run` (method) `eval/governor.py:185` `def run(self, stop_hooks)` -- Execute the generation loop.
- `GenerationGovernor.make_loop_detector` (method) `eval/governor.py:285` `def make_loop_detector(window, min_repeats)` -- Return True if the last `window` tokens contain a sub-sequence of length >= `min_repeats` that repeats consecutively.
- `GenerationGovernor.hook` (method) `eval/governor.py:292` `def hook(generated)`
- `GenerationGovernor.make_timeout_hook` (method) `eval/governor.py:314` `def make_timeout_hook(per_token_s)` -- Return True if the per-token wall time exceeds `per_token_s`.
- `GenerationGovernor.hook` (method) `eval/governor.py:320` `def hook(generated)`

## eval/governor_smoke.py
Depends on: `eval/governor.py`, `topogpt3/__init__.py`
- `load_model` (function) `eval/governor_smoke.py:30` `def load_model()`
- `test_tokenstream_threadsafety` (function) `eval/governor_smoke.py:49` `def test_tokenstream_threadsafety()`
- `producer` (function) `eval/governor_smoke.py:53` `def producer()`
- `consumer` (function) `eval/governor_smoke.py:59` `def consumer()`
- `test_governor_basic` (function) `eval/governor_smoke.py:79` `def test_governor_basic()`
- `test_loop_detector` (function) `eval/governor_smoke.py:98` `def test_loop_detector()`
- `test_cancel` (function) `eval/governor_smoke.py:118` `def test_cancel()`

## eval/harness.py
Depends on: `eval/samplers.py`, `eval/sandbox.py`, `topogpt3/__init__.py`
Imported by: `eval/integration_smoke.py`, `eval/noise_sweep.py`, `eval/temp_sweep.py`
- `load_humaneval` (function) `eval/harness.py:59` `def load_humaneval(cache_dir)`
- `build_prompt` (function) `eval/harness.py:75` `def build_prompt(problem)` -- Return the exact prompt text fed to the model.
- `extract_candidate` (function) `eval/harness.py:100` `def extract_candidate(prompt, completion)` -- Combine prompt + completion into a single Python source string.
- `run_one_test` (function) `eval/harness.py:150` `def run_one_test(problem, candidate_src, timeout)` -- Execute the candidate against the hidden test.
- `run_one_test_sandboxed` (function) `eval/harness.py:172` `def run_one_test_sandboxed(problem, candidate_src, timeout, sandbox_cfg)` -- Sandboxed variant of `run_one_test`.
- `make_sampler` (function) `eval/harness.py:195` `def make_sampler(mode, settings_kwargs)` -- Backwards-compatible shim.
- `completion_for_problem` (function) `eval/harness.py:204` `def completion_for_problem(sampler, prompt)` -- Run a single completion and return (raw_output_text, metrics_dict).
- `ModelLoader.__init__` (method) `eval/harness.py:220` `def __init__(self, ckpt_dir, ckpt_name, device)`
- `ModelLoader.generate` (method) `eval/harness.py:246` `def generate(self, prompt, max_new_tokens, temperature, top_k, repetition_penalty)`
- `ModelLoader.evaluate_problem` (method) `eval/harness.py:272` `def evaluate_problem(problem, loader, args, sample_idx)`
- `ModelLoader.main` (method) `eval/harness.py:315` `def main()`

## eval/hodge_cm_ablation.py
Depends on: `topogpt3/hodge_cm.py`, `topogpt3/model.py`
- `resolve_device` (function) `eval/hodge_cm_ablation.py:28` `def resolve_device(req)`
- `mat_stats` (function) `eval/hodge_cm_ablation.py:48` `def mat_stats(kr, ki, r)`
- `heat_smooth` (function) `eval/hodge_cm_ablation.py:64` `def heat_smooth(kr, ki, t, device)`
- `sm` (function) `eval/hodge_cm_ablation.py:70` `def sm(x)`
- `main` (function) `eval/hodge_cm_ablation.py:74` `def main()`
- `mean` (function) `eval/hodge_cm_ablation.py:141` `def mean(k, m)`

## eval/integration_smoke.py
Depends on: `eval/harness.py`
- `main` (function) `eval/integration_smoke.py:18` `def main()`

## eval/noise_analysis.py
- `consistency_across_runs` (function) `eval/noise_analysis.py:47` `def consistency_across_runs(per_run)` -- Para cada problema, mira si pasa consistentemente a traves de los 4 niveles de ruido.
- `main` (function) `eval/noise_analysis.py:83` `def main()`

## eval/noise_sweep.py
Depends on: `eval/harness.py`, `topogpt3/__init__.py`, `topogpt3/model.py`
Imported by: `eval/temp_sweep.py`
- `inject_noise` (function) `eval/noise_sweep.py:46` `def inject_noise(model, sigma, seed)` -- Anade N(0, sigma) a TODOS los kernels espectrales (kr_*, ki_*).
- `load_model` (function) `eval/noise_sweep.py:74` `def load_model(ckpt_dir, ckpt_name, device)` -- Reconstruye TopoGPT2 alineado con el checkpoint, sin acceso a harness.ModelLoader (queremos un loader limpio que no...
- `generate_one` (function) `eval/noise_sweep.py:99` `def generate_one(model, tok, prompt, max_new_tokens, device)`
- `main` (function) `eval/noise_sweep.py:117` `def main()`

## eval/repair.py
Depends on: `topogpt3/__init__.py`
- `extract_candidate` (function) `eval/repair.py:49` `def extract_candidate(prompt, completion)`
- `run_test` (function) `eval/repair.py:75` `def run_test(problem, candidate_src)`
- `build_repair_prompt` (function) `eval/repair.py:89` `def build_repair_prompt(prompt, candidate, err, entry_point)`
- `gen` (function) `eval/repair.py:104` `def gen(model, tok, text, max_new_tokens, temperature, top_k, rep_penalty)`
- `main` (function) `eval/repair.py:119` `def main()`

## eval/report.py
- `pass_at_k` (function) `eval/report.py:25` `def pass_at_k(n, c, k)`
- `classify_error` (function) `eval/report.py:31` `def classify_error(msg)`
- `load_jsonl` (function) `eval/report.py:52` `def load_jsonl(p)`
- `summarize_run` (function) `eval/report.py:56` `def summarize_run(p)`
- `repair_summary` (function) `eval/report.py:90` `def repair_summary(repair_path, baseline_path)`
- `main` (function) `eval/report.py:117` `def main()`

## eval/samplers.py
Depends on: `topogpt3/__init__.py`
Imported by: `eval/harness.py`
- `register_sampler` (function) `eval/samplers.py:36` `def register_sampler(name)` -- Decorator.
- `deco` (function) `eval/samplers.py:42` `def deco(fn)`
- `list_samplers` (function) `eval/samplers.py:86` `def list_samplers()`
- `build_sampler` (function) `eval/samplers.py:90` `def build_sampler(mode, settings_kwargs)` -- Construct a sampler.

## eval/sandbox.py
Imported by: `eval/harness.py`, `eval/sandbox_smoke.py`
- `SandboxConfig.d` (method) `eval/sandbox.py:125` `def d(node, cur)`
- `SandboxConfig.check_safety` (method) `eval/sandbox.py:133` `def check_safety(source, cfg)` -- Return (ok, reason).
- `SandboxConfig.safe_exec` (method) `eval/sandbox.py:270` `def safe_exec(program_src, cfg, extra_globals)` -- Execute `program_src` in a sandboxed child process.
- `SandboxConfig.describe_policy` (method) `eval/sandbox.py:373` `def describe_policy(cfg)`

## eval/sandbox_smoke.py
Depends on: `eval/sandbox.py`
- `main` (function) `eval/sandbox_smoke.py:15` `def main()`

## eval/smoke.py
Depends on: `topogpt3/__init__.py`
- `run_standard` (function) `eval/smoke.py:17` `def run_standard()`
- `run_hrm` (function) `eval/smoke.py:36` `def run_hrm()`

## eval/temp_sweep.py
Depends on: `eval/harness.py`, `eval/noise_sweep.py`
- `generate_one` (function) `eval/temp_sweep.py:39` `def generate_one(model, tok, prompt, max_new_tokens, temperature, top_k, device, seed_offset)`
- `evaluate_problems` (function) `eval/temp_sweep.py:58` `def evaluate_problems(model, tok, problems, max_new_tokens, temperature, top_k, n_samples, device)`
- `pass_at_k_unbiased` (function) `eval/temp_sweep.py:88` `def pass_at_k_unbiased(n, c, k)`
- `summarize` (function) `eval/temp_sweep.py:96` `def summarize(results, n_samples)`
- `main` (function) `eval/temp_sweep.py:116` `def main()`

## infer_exploitgym.py
Depends on: `topogpt3/model.py`, `topogpt3/train.py`
- `load_task_ids` (function) `infer_exploitgym.py:41` `def load_task_ids()`
- `load_task` (function) `infer_exploitgym.py:49` `def load_task(task_id)` -- Return a dict with keys: task_id, family, name, description, patch, pov.
- `build_prompt` (function) `infer_exploitgym.py:122` `def build_prompt(task_info, tier)`
- `load_model` (function) `infer_exploitgym.py:136` `def load_model(ckpt_dir, ckpt_name, device)` -- Load tokenizer, build TopoGPT-2, apply Gauss patch, load weights.
- `generate` (function) `infer_exploitgym.py:177` `def generate(model, tokenizer, prompt)` -- Autoregressive generation with streaming + n-gram repetition blocking.
- `sample` (function) `infer_exploitgym.py:205` `def sample(logits, seen_ids)`
- `run_single_prompt` (function) `infer_exploitgym.py:257` `def run_single_prompt(args, model, tokenizer)`
- `run_eval_holdout` (function) `infer_exploitgym.py:274` `def run_eval_holdout(args, model, tokenizer)`
- `run_interactive` (function) `infer_exploitgym.py:331` `def run_interactive(args, model, tokenizer)`
- `parse_args` (function) `infer_exploitgym.py:380` `def parse_args()`
- `main` (function) `infer_exploitgym.py:420` `def main()`

## run_exploitgym_v2.sh
- `banner` (function) `run_exploitgym_v2.sh:24`
- `train_v2` (function) `run_exploitgym_v2.sh:32`
- `eval_v2` (function) `run_exploitgym_v2.sh:45`
- `infer_v2` (function) `run_exploitgym_v2.sh:54`

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

## synthetic_dataset.py
Imported by: `topogpt3/model.py`
- `LLMBackend.generate` (method) `synthetic_dataset.py:64` `def generate(self, prompt)`
- `LLMBackend.name` (method) `synthetic_dataset.py:67` `def name(self)`
- `GroqBackend.__init__` (method) `synthetic_dataset.py:78` `def __init__(self, model, api_key, max_tokens, temperature, timeout)`
- `GroqBackend.name` (method) `synthetic_dataset.py:95` `def name(self)`
- `GroqBackend.generate` (method) `synthetic_dataset.py:98` `def generate(self, prompt)`
- `OpenRouterBackend.__init__` (method) `synthetic_dataset.py:132` `def __init__(self, model, api_key, max_tokens, temperature, timeout)`
- `OpenRouterBackend.name` (method) `synthetic_dataset.py:151` `def name(self)`
- `OpenRouterBackend.generate` (method) `synthetic_dataset.py:154` `def generate(self, prompt)`
- `OllamaBackend.__init__` (method) `synthetic_dataset.py:184` `def __init__(self, model, host, max_tokens, temperature, timeout)`
- `OllamaBackend.name` (method) `synthetic_dataset.py:198` `def name(self)`
- `OllamaBackend.generate` (method) `synthetic_dataset.py:201` `def generate(self, prompt)`
- `OllamaBackend.build_backend` (method) `synthetic_dataset.py:227` `def build_backend(provider, model)` -- Factory for LLM backends.
- `OllamaBackend.validate_sample` (method) `synthetic_dataset.py:330` `def validate_sample(sample)` -- Validate that a generated sample meets quality bar.
- `ProcessedManifest.load` (method) `synthetic_dataset.py:374` `def load(path)`
- `ProcessedManifest.save` (method) `synthetic_dataset.py:387` `def save(self, path)`
- `SyntheticDatasetGenerator.__init__` (method) `synthetic_dataset.py:418` `def __init__(self, backend, output_path, manifest_path, logger, max_workers, max_file_chars)`
- `SyntheticDatasetGenerator.process_file` (method) `synthetic_dataset.py:533` `def process_file(self, path)` -- Process a single file.
- `SyntheticDatasetGenerator.process_batch` (method) `synthetic_dataset.py:568` `def process_batch(self, paths)` -- Process a batch of files in parallel using thread pool.
- `SyntheticDatasetGenerator.finish` (method) `synthetic_dataset.py:590` `def finish(self)` -- Signal end of processing and flush writer.
- `SyntheticDatasetGenerator.build_logger` (method) `synthetic_dataset.py:614` `def build_logger(level)`
- `SyntheticDatasetGenerator.parse_args` (method) `synthetic_dataset.py:625` `def parse_args()`
- `SyntheticDatasetGenerator.load_paths` (method) `synthetic_dataset.py:652` `def load_paths(paths_arg, paths_file, max_files)` -- Load file paths from CLI args or file.
- `SyntheticDatasetGenerator.main` (method) `synthetic_dataset.py:667` `def main()`

## topogpt3/__main__.py
Depends on: `topogpt3/api_server.py`, `topogpt3/inference.py`, `topogpt3/inference_hrm.py`, `topogpt3/jlens.py`, `topogpt3/lens_model.py`, `topogpt3/train.py`
- `main` (function) `topogpt3/__main__.py:6` `def main()` -- TopoGPT3 entry point.

## topogpt3/api_server.py
Depends on: `topogpt3/continuation.py`, `topogpt3/model.py`
Imported by: `topogpt3/__main__.py`
- `AuthState.validate` (method) `topogpt3/api_server.py:148` `def validate(self, raw)`
- `TokenBucket.consume` (method) `topogpt3/api_server.py:208` `def consume(self, n)`
- `RateLimiter.__init__` (method) `topogpt3/api_server.py:220` `def __init__(self, user_rps, admin_rps, capacity)`
- `RateLimiter.allow` (method) `topogpt3/api_server.py:233` `def allow(self, key, role)`
- `IpBanner.__init__` (method) `topogpt3/api_server.py:251` `def __init__(self, max_failures, window)`
- `IpBanner.record_failure` (method) `topogpt3/api_server.py:257` `def record_failure(self, ip)`
- `IpBanner.is_banned` (method) `topogpt3/api_server.py:265` `def is_banned(self, ip)`
- `ServerModel.complete` (method) `topogpt3/api_server.py:348` `def complete(self, prompt)`
- `ServerModel.stream_complete` (method) `topogpt3/api_server.py:393` `def stream_complete(self, prompt)`
- `ServerModel.load_model` (method) `topogpt3/api_server.py:553` `def load_model(checkpoint, device)`
- `ServerModel.lifespan` (method) `topogpt3/api_server.py:577` `def lifespan(app)`
- `ServerModel.health` (method) `topogpt3/api_server.py:712` `def health(request)`
- `ServerModel.list_models` (method) `topogpt3/api_server.py:719` `def list_models(request)`
- `ServerModel.completions` (method) `topogpt3/api_server.py:736` `def completions(req, request)`
- `ServerModel.chat_completions` (method) `topogpt3/api_server.py:792` `def chat_completions(req, request)`
- `ServerModel.main` (method) `topogpt3/api_server.py:953` `def main()`

## topogpt3/continuation.py
Imported by: `topogpt3/api_server.py`, `topogpt3/inference_hrm.py`, `topogpt3/model.py`
- `is_response_complete` (function) `topogpt3/continuation.py:45` `def is_response_complete(text, min_chars)` -- Heuristic to decide whether a model response looks finished.
- `extract_tail_for_continuation` (function) `topogpt3/continuation.py:75` `def extract_tail_for_continuation(text, tail_lines, tail_chars)` -- Return the last N lines (or up to tail_chars) of `text` as a continuation prefix to feed back into the model.
- `split_at_last_newline` (function) `topogpt3/continuation.py:105` `def split_at_last_newline(text)` -- Split `text` at the last newline.

## topogpt3/ewc.py
Imported by: `topogpt3/train.py`
- `EWCRegularizer.__init__` (method) `topogpt3/ewc.py:45` `def __init__(self, model, lambda_ewc, fisher_num_samples)` -- Args: model: The model to regularize. lambda_ewc: Penalty strength scaling the Fisher-weighted parameter deviation...
- `EWCRegularizer.compute_fisher` (method) `topogpt3/ewc.py:68` `def compute_fisher(self, dataloader, vocab_size, device, max_batches)` -- Compute the diagonal Fisher information matrix and snapshot the current parameters as the reference point for the...
- `EWCRegularizer.penalty` (method) `topogpt3/ewc.py:168` `def penalty(self, model)` -- Compute the EWC regularization loss.
- `EWCRegularizer.save_state` (method) `topogpt3/ewc.py:186` `def save_state(self, path)` -- Persist the Fisher information matrix and old parameter snapshots to a single ``.pt`` file.
- `EWCRegularizer.load_state` (method) `topogpt3/ewc.py:203` `def load_state(self, path)` -- Load a previously saved EWC state.
- `ReplayBuffer.__init__` (method) `topogpt3/ewc.py:241` `def __init__(self, max_tiers, replay_ratio)` -- Args: max_tiers: Maximum number of previous tiers to remember.
- `ReplayBuffer.add_tier` (method) `topogpt3/ewc.py:259` `def add_tier(self, tier_index, dataloader)` -- Register a tier's training dataloader for future replay.
- `ReplayBuffer.sample_batch` (method) `topogpt3/ewc.py:312` `def sample_batch(self, current_batch_size)` -- Sample a mixed replay batch from ALL stored previous tiers.

## topogpt3/exploitgym_config.py
Depends on: `topogpt3/exploitgym_loader.py`, `topogpt3/model.py`
Imported by: `topogpt3/train.py`
- `TopoExploitConfig.build_topogpt2_config` (method) `topogpt3/exploitgym_config.py:100` `def build_topogpt2_config(self, max_seq_len, attn_window)`
- `TopoExploitConfig.build_loader_config` (method) `topogpt3/exploitgym_config.py:122` `def build_loader_config(self)`

## topogpt3/exploitgym_loader.py
Depends on: `topogpt3/model.py`
Imported by: `topogpt3/exploitgym_config.py`, `topogpt3/merged_config.py`, `topogpt3/train.py`
- `ExploitGymLoaderConfig.ensure_repo` (method) `topogpt3/exploitgym_loader.py:54` `def ensure_repo(repo_cache, logger)`
- `ExploitGymLoaderConfig.parse_task` (method) `topogpt3/exploitgym_loader.py:101` `def parse_task(task_dir, task_id, max_chars)`
- `ExploitGymDataLoader.__init__` (method) `topogpt3/exploitgym_loader.py:201` `def __init__(self, config, tokenizer, logger)`
- `ExploitGymDataLoader.prepare_tier` (method) `topogpt3/exploitgym_loader.py:264` `def prepare_tier(self, tier_index, force)`
- `ExploitGymDataLoader.stratum_key` (method) `topogpt3/exploitgym_loader.py:288` `def stratum_key(task)`
- `ExploitGymDataLoader.flush` (method) `topogpt3/exploitgym_loader.py:343` `def flush(split)`
- `ExploitGymDataLoader.open_memmap` (method) `topogpt3/exploitgym_loader.py:411` `def open_memmap(self, tier, split)`

## topogpt3/hodge_cm.py
Imported by: `eval/hodge_cm_ablation.py`
- `CMPhaseQuantSTE.forward` (method) `topogpt3/hodge_cm.py:15` `def forward(ctx, phase, m, beta)`
- `CMPhaseQuantSTE.backward` (method) `topogpt3/hodge_cm.py:21` `def backward(ctx, grad_out)`
- `CMPhaseQuantSTE.cm_phase_loss` (method) `topogpt3/hodge_cm.py:25` `def cm_phase_loss(kr, ki, m)` -- E_Q: distancia cuadratica media a raices m-esimas. kr,ki reales misma forma.
- `CMPhaseQuantSTE.apply_cm_soft` (method) `topogpt3/hodge_cm.py:34` `def apply_cm_soft(kr, ki, m, beta)` -- Cuantizacion suave de fase con STE.
- `CMPhaseQuantSTE.freq_grid_laplacian` (method) `topogpt3/hodge_cm.py:49` `def freq_grid_laplacian(fh, fw, device, dtype)`
- `CMPhaseQuantSTE.idx` (method) `topogpt3/hodge_cm.py:53` `def idx(h, w)`
- `CMPhaseQuantSTE.hodge_heat_residue` (method) `topogpt3/hodge_cm.py:66` `def hodge_heat_residue(kr, ki, t)` -- ||K - e^{-tL} K||_F^2 sobre grid freq. kr,ki: [...,Fh,Fw].
- `CMPhaseQuantSTE.harmonic_ratio` (method) `topogpt3/hodge_cm.py:81` `def harmonic_ratio(kr, ki, t)`
- `CMPhaseQuantSTE.fisher_hinge` (method) `topogpt3/hodge_cm.py:96` `def fisher_hinge(singulars, r, margin)`
- `CMPhaseQuantSTE.langevin_refine` (method) `topogpt3/hodge_cm.py:105` `def langevin_refine(param, energy_fn, steps, eta, temp, seed)` -- ULA offline: theta <- theta - eta grad E + sqrt(2 eta T) xi.
- `CMPhaseQuantSTE.gibbs_cluster_assign` (method) `topogpt3/hodge_cm.py:123` `def gibbs_cluster_assign(feats, n_clusters, iters, seed)` -- Clustering blando por fase para nodos/frecuencias. feats: [N,D] complejo o real.
- `HeckeScalePool.__init__` (method) `topogpt3/hodge_cm.py:151` `def __init__(self, modes)`
- `HeckeScalePool.forward` (method) `topogpt3/hodge_cm.py:155` `def forward(self, Kfreq)`

## topogpt3/inference.py
Imported by: `topogpt3/__init__.py`, `topogpt3/__main__.py`
- `InferenceSettings.scale_presets` (method) `topogpt3/inference.py:103` `def scale_presets()` -- Return the architecture preset table indexed by scale name.
- `InferenceSettings.preset` (method) `topogpt3/inference.py:118` `def preset(self)` -- Return the resolved preset for the configured model scale.
- `InferenceSettings.validate` (method) `topogpt3/inference.py:128` `def validate(self)` -- Raise ValueError if any setting falls outside its safety bounds.
- `InferenceLoggerFactory.build` (method) `topogpt3/inference.py:164` `def build(settings)` -- Return a configured Logger with a single deduplicated stdout handler.
- `SecurePathResolver.resolve_under` (method) `topogpt3/inference.py:184` `def resolve_under(root)` -- Join `parts` under `root` and return the canonical resolved path.
- `SecurePathResolver.require_existing_file` (method) `topogpt3/inference.py:200` `def require_existing_file(path, expected_suffix)` -- Validate `path` points to an existing regular file with the expected suffix.
- `SourceModuleLoader.__init__` (method) `topogpt3/inference.py:217` `def __init__(self, settings, logger)`
- `SourceModuleLoader.load` (method) `topogpt3/inference.py:221` `def load(self)` -- Return the topogpt3.train module which re-exports model symbols.
- `CheckpointPaths.__init__` (method) `topogpt3/inference.py:233` `def __init__(self, settings)`
- `CheckpointPaths.slot_dir` (method) `topogpt3/inference.py:241` `def slot_dir(self)` -- Directory holding the active checkpoint slot.
- `CheckpointPaths.model_file` (method) `topogpt3/inference.py:245` `def model_file(self)` -- Resolved path to the safetensors weights file inside the slot.
- `CheckpointPaths.state_file` (method) `topogpt3/inference.py:251` `def state_file(self)` -- Resolved path to the JSON training-state file inside the slot.
- `CheckpointPaths.assert_ready` (method) `topogpt3/inference.py:257` `def assert_ready(self)` -- Verify weights exist and the on-disk size lies within safety bounds.
- `WeightShapeProbe.__init__` (method) `topogpt3/inference.py:279` `def __init__(self, settings, logger)`
- `WeightShapeProbe.detect_n_kv_heads` (method) `topogpt3/inference.py:283` `def detect_n_kv_heads(self, weights_path, d_model, n_heads)` -- Recover N_KV_HEADS used at training by inspecting the k_proj shape.
- `TopoGPT2ConfigAligner.__init__` (method) `topogpt3/inference.py:323` `def __init__(self, settings, source_module, logger)`
- `TopoGPT2ConfigAligner.build` (method) `topogpt3/inference.py:329` `def build(self, n_kv_heads, vocab_size)` -- Return a TopoGPT2Config dataclass ready to instantiate the model.
- `TokenizerFactory.__init__` (method) `topogpt3/inference.py:354` `def __init__(self, settings, source_module)`
- `TokenizerFactory.build` (method) `topogpt3/inference.py:358` `def build(self)` -- Return an instance of BPETokenizer bound to the configured encoding.
- `GaussPatchApplier.__init__` (method) `topogpt3/inference.py:367` `def __init__(self, settings, source_module, logger)`
- `GaussPatchApplier.apply_if_enabled` (method) `topogpt3/inference.py:373` `def apply_if_enabled(self)` -- Patch QuaternionSpectralLayer to use the 3-multiply Gauss contract.
- `ModelAssembler.__init__` (method) `topogpt3/inference.py:385` `def __init__(self, settings, source_module, logger)`
- `ModelAssembler.assemble` (method) `topogpt3/inference.py:391` `def assemble(self, aligned_cfg, paths)` -- Build the TopoGPT2 graph, load weights into it, and return it in eval mode.
- `SeedSynchronizer.__init__` (method) `topogpt3/inference.py:422` `def __init__(self, settings, source_module, logger)`
- `SeedSynchronizer.apply` (method) `topogpt3/inference.py:428` `def apply(self)` -- Seed all relevant RNGs using the model package helper when available.
- `SamplingPolicy.from_settings` (method) `topogpt3/inference.py:452` `def from_settings(cls, settings)` -- Construct a SamplingPolicy from inference settings.
- `GenerationReport.tokens_per_second` (method) `topogpt3/inference.py:472` `def tokens_per_second(self, elapsed_floor)` -- Return throughput in tokens/sec, clamped to avoid divide-by-zero.
- `GenerationEngine.__init__` (method) `topogpt3/inference.py:480` `def __init__(self, settings, logger)`
- `GenerationEngine.run` (method) `topogpt3/inference.py:485` `def run(self, model, tokenizer, prompt, policy)` -- Generate a completion for `prompt` and return a GenerationReport.
- `ResultRenderer.__init__` (method) `topogpt3/inference.py:538` `def __init__(self, settings, logger)`
- `ResultRenderer.render` (method) `topogpt3/inference.py:542` `def render(self, report)` -- Emit a banner with prompt and completion, plus a throughput log line.
- `InferencePipeline.__init__` (method) `topogpt3/inference.py:567` `def __init__(self, settings, logger)`
- `InferencePipeline.execute` (method) `topogpt3/inference.py:573` `def execute(self)` -- Run the full inference pipeline end-to-end and return the report.
- `CliArgumentParser.build_parser` (method) `topogpt3/inference.py:621` `def build_parser()` -- Return the configured argparse.ArgumentParser.
- `CliArgumentParser.parse` (method) `topogpt3/inference.py:700` `def parse(argv)` -- Parse `argv` (or sys.argv) and return a populated InferenceSettings.
- `CliArgumentParser.main` (method) `topogpt3/inference.py:723` `def main(argv)` -- CLI entry point.

## topogpt3/inference_hrm.py
Depends on: `topogpt3/continuation.py`
Imported by: `topogpt3/__init__.py`, `topogpt3/__main__.py`
- `HRMInferenceSettings.scale_presets` (method) `topogpt3/inference_hrm.py:221` `def scale_presets()` -- Return the architecture preset table indexed by scale name.
- `HRMInferenceSettings.preset` (method) `topogpt3/inference_hrm.py:234` `def preset(self)` -- Return the resolved preset for the configured model scale.
- `HRMInferenceSettings.validate` (method) `topogpt3/inference_hrm.py:244` `def validate(self)` -- Raise ValueError if any setting falls outside its safety bounds.
- `HRMLoggerFactory.build` (method) `topogpt3/inference_hrm.py:347` `def build(settings)` -- Return a configured Logger with a single deduplicated stdout handler.
- `SecurePathResolver.resolve_under` (method) `topogpt3/inference_hrm.py:367` `def resolve_under(root)` -- Join parts under root and return the canonical resolved path.
- `SecurePathResolver.require_existing_file` (method) `topogpt3/inference_hrm.py:383` `def require_existing_file(path, expected_suffix)` -- Validate path points to an existing regular file with the expected suffix.
- `SourceModuleLoader.__init__` (method) `topogpt3/inference_hrm.py:400` `def __init__(self, settings, logger)`
- `SourceModuleLoader.load` (method) `topogpt3/inference_hrm.py:404` `def load(self)` -- Return the topogpt3.train module which re-exports model symbols.
- `CheckpointPaths.__init__` (method) `topogpt3/inference_hrm.py:416` `def __init__(self, settings)`
- `CheckpointPaths.slot_dir` (method) `topogpt3/inference_hrm.py:424` `def slot_dir(self)` -- Directory holding the active checkpoint slot.
- `CheckpointPaths.model_file` (method) `topogpt3/inference_hrm.py:428` `def model_file(self)` -- Resolved path to the safetensors weights file inside the slot.
- `CheckpointPaths.state_file` (method) `topogpt3/inference_hrm.py:434` `def state_file(self)` -- Resolved path to the JSON training-state file inside the slot.
- `CheckpointPaths.assert_ready` (method) `topogpt3/inference_hrm.py:440` `def assert_ready(self)` -- Verify weights exist and the on-disk size lies within safety bounds.
- `WeightShapeProbe.__init__` (method) `topogpt3/inference_hrm.py:462` `def __init__(self, settings, logger)`
- `WeightShapeProbe.detect_n_kv_heads` (method) `topogpt3/inference_hrm.py:466` `def detect_n_kv_heads(self, weights_path, d_model, n_heads)` -- Recover N_KV_HEADS used at training by inspecting the k_proj shape.
- `TopoGPT2ConfigAligner.__init__` (method) `topogpt3/inference_hrm.py:505` `def __init__(self, settings, source_module, logger)`
- `TopoGPT2ConfigAligner.build` (method) `topogpt3/inference_hrm.py:511` `def build(self, n_kv_heads, vocab_size)` -- Return a TopoGPT2Config dataclass ready to instantiate the model.
- `TokenizerFactory.__init__` (method) `topogpt3/inference_hrm.py:536` `def __init__(self, settings, source_module)`
- `TokenizerFactory.build` (method) `topogpt3/inference_hrm.py:540` `def build(self)` -- Return an instance of BPETokenizer bound to the configured encoding.
- `GaussPatchApplier.__init__` (method) `topogpt3/inference_hrm.py:549` `def __init__(self, settings, source_module, logger)`
- `GaussPatchApplier.apply_if_enabled` (method) `topogpt3/inference_hrm.py:555` `def apply_if_enabled(self)` -- Patch QuaternionSpectralLayer to use the 3-multiply Gauss contract.
- `ModelAssembler.__init__` (method) `topogpt3/inference_hrm.py:567` `def __init__(self, settings, source_module, logger)`
- `ModelAssembler.assemble` (method) `topogpt3/inference_hrm.py:573` `def assemble(self, aligned_cfg, paths)` -- Build the TopoGPT2 graph, load weights into it, and return it in eval mode.
- `SeedSynchronizer.__init__` (method) `topogpt3/inference_hrm.py:604` `def __init__(self, settings, source_module, logger)`
- `SeedSynchronizer.apply` (method) `topogpt3/inference_hrm.py:610` `def apply(self)` -- Seed all relevant RNGs using the model package helper when available.
- `LatentChangeMetric.__init__` (method) `topogpt3/inference_hrm.py:627` `def __init__(self, epsilon_floor)`
- `LatentChangeMetric.relative_change` (method) `topogpt3/inference_hrm.py:632` `def relative_change(self, current, previous)` -- Return ||current - previous|| / max(||previous||, epsilon_floor).
- `GenerationReasoningSummary.absorb` (method) `topogpt3/inference_hrm.py:671` `def absorb(self, sample)` -- Fold a per-token sample into the running totals.
- `SparseHighLevelStateCache.__init__` (method) `topogpt3/inference_hrm.py:693` `def __init__(self, persist_tokens)`
- `SparseHighLevelStateCache.get_or_init` (method) `topogpt3/inference_hrm.py:700` `def get_or_init(self, reference)` -- Return the cached high-level state or a zeroed one when stale.
- `SparseHighLevelStateCache.commit` (method) `topogpt3/inference_hrm.py:716` `def commit(self, new_state)` -- Store a fresh high-level state and increment the cache age.
- `SparseHighLevelStateCache.invalidate` (method) `topogpt3/inference_hrm.py:721` `def invalidate(self)` -- Drop any cached state and reset the age counter.
- `HierarchicalRecursiveReasoner.__init__` (method) `topogpt3/inference_hrm.py:768` `def __init__(self, layers, final_norm, reasoning_config, logger)`
- `HierarchicalRecursiveReasoner.num_layers` (method) `topogpt3/inference_hrm.py:789` `def num_layers(self)` -- Return the number of trained transformer layers.
- `HierarchicalRecursiveReasoner.reason` (method) `topogpt3/inference_hrm.py:827` `def reason(self, z_initial, base_kvs, cached_refinement)` -- Run hierarchical recursive thinking for a single emission step.
- `LogitsSampler.__init__` (method) `topogpt3/inference_hrm.py:938` `def __init__(self, logger)`
- `LogitsSampler.sample` (method) `topogpt3/inference_hrm.py:941` `def sample(self, logits, token_history, temperature, top_k, repetition_penalty)` -- Return a sampled token id tensor of shape [B, 1] from raw logits [B, V].
- `SamplingPolicy.from_settings` (method) `topogpt3/inference_hrm.py:973` `def from_settings(cls, settings)` -- Construct a SamplingPolicy from inference settings.
- `GenerationReport.tokens_per_second` (method) `topogpt3/inference_hrm.py:995` `def tokens_per_second(self, elapsed_floor)` -- Return throughput in tokens/sec, clamped to avoid divide-by-zero.
- `HRMGenerationEngine.__init__` (method) `topogpt3/inference_hrm.py:1011` `def __init__(self, settings, logger)`
- `HRMGenerationEngine.run` (method) `topogpt3/inference_hrm.py:1048` `def run(self, model, tokenizer, prompt, policy)` -- Generate a completion for prompt and return a GenerationReport.
- `ResultRenderer.__init__` (method) `topogpt3/inference_hrm.py:1192` `def __init__(self, settings, logger)`
- `ResultRenderer.render` (method) `topogpt3/inference_hrm.py:1196` `def render(self, report)` -- Emit a banner with prompt, completion, throughput and reasoning stats.
- `HRMInferencePipeline.__init__` (method) `topogpt3/inference_hrm.py:1233` `def __init__(self, settings, logger)`
- `HRMInferencePipeline.execute` (method) `topogpt3/inference_hrm.py:1239` `def execute(self)` -- Run the full inference pipeline end-to-end and return the report.
- `CliArgumentParser.build_parser` (method) `topogpt3/inference_hrm.py:1287` `def build_parser()` -- Return the configured argparse.ArgumentParser.
- `CliArgumentParser.parse` (method) `topogpt3/inference_hrm.py:1448` `def parse(argv)` -- Parse argv (or sys.argv) and return a populated HRMInferenceSettings.
- `CliArgumentParser.main` (method) `topogpt3/inference_hrm.py:1494` `def main(argv)` -- CLI entry point.

## topogpt3/jlens.py
Depends on: `topogpt3/lens_model.py`
Imported by: `tests/test_jlens.py`, `tests/test_lens_model.py`, `topogpt3/__init__.py`, `topogpt3/__main__.py`
- `ActivationRecorder.__init__` (method) `topogpt3/jlens.py:87` `def __init__(self, blocks, at)`
- `ActivationRecorder.hook` (method) `topogpt3/jlens.py:105` `def hook(module, inputs, output)`
- `ActivationRecorder.valid_position_mask` (method) `topogpt3/jlens.py:132` `def valid_position_mask(seq_len)` -- Boolean mask over sequence positions to include in the Jacobian average.
- `ActivationRecorder.jacobian_for_prompt` (method) `topogpt3/jlens.py:187` `def jacobian_for_prompt(model, prompt, source_layers)` -- Compute the per-layer Jacobian estimator ``J_l`` for one prompt.
- `ActivationRecorder.fit` (method) `topogpt3/jlens.py:291` `def fit(model, prompts)` -- Fit ``J_l`` over a list of prompts and return a JacobianLens.
- `ActivationRecorder.write_checkpoint` (method) `topogpt3/jlens.py:378` `def write_checkpoint()`
- `JacobianLens.__init__` (method) `topogpt3/jlens.py:470` `def __init__(self, jacobians)`
- `JacobianLens.save` (method) `topogpt3/jlens.py:489` `def save(self, path)` -- Save to ``path``.
- `JacobianLens.load` (method) `topogpt3/jlens.py:504` `def load(cls, path)` -- Load a lens previously written by ``save``.
- `JacobianLens.from_pretrained` (method) `topogpt3/jlens.py:519` `def from_pretrained(cls, name_or_path)` -- Load a lens from a local file, a local directory, or a HuggingFace Hub ``repo_id``.
- `JacobianLens.merge` (method) `topogpt3/jlens.py:543` `def merge(cls, lenses)` -- Combine lenses fitted on disjoint prompt subsets into one (``n_prompts``-weighted mean of the inputs).
- `JacobianLens.transport` (method) `topogpt3/jlens.py:574` `def transport(self, residual, layer)` -- Map a residual at ``layer`` into the final-layer basis: ``J_l @ h``.
- `JacobianLens.apply` (method) `topogpt3/jlens.py:585` `def apply(self, model, prompt)` -- Run ``model`` on ``prompt`` and return lens logits at ``positions``.
- `JacobianLens.select` (method) `topogpt3/jlens.py:646` `def select(layer)`
- `SliceData.compute_slice` (method) `topogpt3/jlens.py:705` `def compute_slice(model, lens, prompt)` -- Compute a position x layer slice of top-K token predictions.
- `SliceData.text_slice` (method) `topogpt3/jlens.py:789` `def text_slice(slice_data, tokenizer, n_cols)` -- Render a SliceData as a readable text table showing decoded words.

## topogpt3/lens_model.py
Depends on: `topogpt3/model.py`
Imported by: `tests/test_jlens.py`, `tests/test_lens_model.py`, `topogpt3/__init__.py`, `topogpt3/__main__.py`, `topogpt3/jlens.py`
- `LensModel.encode` (method) `topogpt3/lens_model.py:40` `def encode(self, text)` -- Tokenize ``text`` to ``input_ids`` of shape ``[1, seq_len]`` on the model's input device.
- `LensModel.forward` (method) `topogpt3/lens_model.py:45` `def forward(self, input_ids)` -- Run the residual stack on ``input_ids`` (no LM head).
- `LensModel.unembed` (method) `topogpt3/lens_model.py:52` `def unembed(self, residual)` -- Map a residual-stream tensor ``[..., d_model]`` to logits ``[..., vocab_size]`` (final norm + LM head).
- `TopoGPT3LensConfig.from_topogpt2_config` (method) `topogpt3/lens_model.py:84` `def from_topogpt2_config(cls, cfg)` -- Construct a lens config from a TopoGPT2Config dataclass.
- `TopoGPT3LensConfig.probe_checkpoint` (method) `topogpt3/lens_model.py:104` `def probe_checkpoint(cls, checkpoint_dir)` -- Probe a checkpoint directory and infer lens config from state.json.
- `_TopoGPT3ResidualForward.__init__` (method) `topogpt3/lens_model.py:150` `def __init__(self, model)`
- `_TopoGPT3ResidualForward.forward` (method) `topogpt3/lens_model.py:154` `def forward(self, input_ids)`
- `TopoGPT3LensModel.__init__` (method) `topogpt3/lens_model.py:172` `def __init__(self, model, tokenizer)`
- `TopoGPT3LensModel.n_layers` (method) `topogpt3/lens_model.py:184` `def n_layers(self)`
- `TopoGPT3LensModel.d_model` (method) `topogpt3/lens_model.py:188` `def d_model(self)`
- `TopoGPT3LensModel.layers` (method) `topogpt3/lens_model.py:192` `def layers(self)`
- `TopoGPT3LensModel.tokenizer` (method) `topogpt3/lens_model.py:196` `def tokenizer(self)`
- `TopoGPT3LensModel.tokenizer` (method) `topogpt3/lens_model.py:200` `def tokenizer(self, tok)`
- `TopoGPT3LensModel.input_device` (method) `topogpt3/lens_model.py:204` `def input_device(self)`
- `TopoGPT3LensModel.input_device` (method) `topogpt3/lens_model.py:210` `def input_device(self, device)`
- `TopoGPT3LensModel.encode` (method) `topogpt3/lens_model.py:213` `def encode(self, text)` -- Tokenize text to input_ids of shape ``[1, seq_len]``.
- `TopoGPT3LensModel.forward` (method) `topogpt3/lens_model.py:228` `def forward(self, input_ids)` -- Run the residual stack on ``input_ids``.
- `TopoGPT3LensModel.unembed` (method) `topogpt3/lens_model.py:237` `def unembed(self, residual)` -- Map residual ``[..., d_model]`` to logits ``[..., vocab_size]``.
- `TopoGPT3LensModel.from_checkpoint` (method) `topogpt3/lens_model.py:246` `def from_checkpoint(cls, checkpoint_dir)` -- Build a TopoGPT3LensModel from a checkpoint directory.
- `TinyDecoder.__init__` (method) `topogpt3/lens_model.py:315` `def __init__(self, n_layers, d_model, vocab_size, seed)`
- `TinyDecoder.forward` (method) `topogpt3/lens_model.py:344` `def forward(self, token_ids, past_kvs)`
- `_ResidualBlock.__init__` (method) `topogpt3/lens_model.py:360` `def __init__(self, d_model)`
- `_ResidualBlock.forward` (method) `topogpt3/lens_model.py:366` `def forward(self, x, past_kv)`

## topogpt3/merged_config.py
Depends on: `topogpt3/exploitgym_loader.py`, `topogpt3/model.py`
Imported by: `topogpt3/__init__.py`, `topogpt3/train.py`
- `TopoMergedConfig.build_topogpt2_config` (method) `topogpt3/merged_config.py:139` `def build_topogpt2_config(self, max_seq_len, attn_window)`
- `TopoMergedConfig.build_exploit_loader_config` (method) `topogpt3/merged_config.py:161` `def build_exploit_loader_config(self)`
- `TopoMergedConfig.is_code_tier` (method) `topogpt3/merged_config.py:175` `def is_code_tier(self, tier_index)` -- Returns True if the tier uses TopoGPT3 (HuggingFace) data.
- `TopoMergedConfig.is_exploit_tier` (method) `topogpt3/merged_config.py:179` `def is_exploit_tier(self, tier_index)` -- Returns True if the tier uses ExploitGym data.
- `TopoMergedConfig.exploit_tier_index` (method) `topogpt3/merged_config.py:183` `def exploit_tier_index(self, tier_index)` -- Convert global tier index to exploitgym-local index (0-2).


Next: [API_p2.md](API_p2.md)