# eval: governor

*Community 2 | 6 files | cohesion 0.31*

## Definition

This community groups 6 file(s) rooted at `eval` with dominant language py (cohesion 0.31). Central symbols: `GenerationGovernor`, `GenerationResult`, `StopReason`, `TokenStream`, `__init__`, `__len__`, `__post_init__`, `_build_parser`. Core file: `eval/governor.py` (20 symbols). Documented purpose: Drop-in entry point that demonstrates how to use the topogpt3 package.  This file lives outside the package on purpose. Copy it (or its sections) into your own .

## Files

| File | Language | Layer | Symbols | Doc |
|------|----------|-------|---------|-----|
| `app.py` | py | utility | 5 | yes |
| `eval/governor.py` | py | utility | 20 | yes |
| `eval/governor_smoke.py` | py | utility | 7 | yes |
| `eval/repair.py` | py | utility | 6 | yes |
| `eval/smoke.py` | py | utility | 2 | yes |
| `topogpt3/__init__.py` | py | utility | 0 | yes |

## Key Symbols

- `run_inference` (function, `app.py:46`) `def run_inference(prompt, checkpoint_dir, checkpoint_name, max_new_tokens, tempe` - 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, t` - 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.
- `_build_parser` (function, `app.py:121`) `def _build_parser()` - Build the top-level CLI for this entry point script.
- `main` (function, `app.py:159`) `def main(argv)` - Entry point invoked when the file is executed as a script.
- `TokenStream` (class, `eval/governor.py:45`) `class TokenStream` - Thread-safe single-producer / single-consumer queue of token IDs.
- `__init__` (method, `eval/governor.py:56`) `def __init__(self)`
- `put` (method, `eval/governor.py:62`) `def put(self, tok)`
- `mark_done` (method, `eval/governor.py:67`) `def mark_done(self)`
- `drain` (method, `eval/governor.py:72`) `def drain(self)` - Return all tokens emitted so far, atomic snapshot.
- `wait_for_new` (method, `eval/governor.py:77`) `def wait_for_new(self, timeout)` - Block up to `timeout` seconds for a new token. Returns True
- `is_closed` (method, `eval/governor.py:86`) `def is_closed(self)`
- `__len__` (method, `eval/governor.py:90`) `def __len__(self)`
- `StopReason` (class, `eval/governor.py:99`) `class StopReason(str, Enum)`
- `GenerationResult` (class, `eval/governor.py:109`) `class GenerationResult` - Outcome of a governed generation.
- `__post_init__` (method, `eval/governor.py:117`) `def __post_init__(self)`
- `GenerationGovernor` (class, `eval/governor.py:134`) `class GenerationGovernor` - Run a model's autoregressive generation loop with optional stop
- `__init__` (method, `eval/governor.py:156`) `def __init__(self, model, ctx, stream, max_new_tokens, temperature, top_k, repet`
- `cancel` (method, `eval/governor.py:177`) `def cancel(self)` - Asynchronously stop the generation. Safe to call from any
- `_should_cancel` (method, `eval/governor.py:182`) `def _should_cancel(self)`
- `run` (method, `eval/governor.py:185`) `def run(self, stop_hooks)` - Execute the generation loop. Returns when the model emits
- `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
- `hook` (method, `eval/governor.py:292`) `def hook(generated)`
- `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`.
- `hook` (method, `eval/governor.py:320`) `def hook(generated)`
- `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()`

## Internal vs External Edges

- Internal resolved imports (EXTRACTED): 5
- Cross-boundary resolved imports (EXTRACTED): 11

## Connections

- [EXTRACTED] depends_on community 0 <-> 2 (strength 0.9): Extracted import edge crosses communities: eval/diag_static.py imports topogpt3/__init__.py.
- [EXTRACTED] depends_on community 1 <-> 2 (strength 0.9): Extracted import edge crosses communities: eval/harness.py imports topogpt3/__init__.py.
- [EXTRACTED] depends_on community 2 <-> 3 (strength 0.9): Extracted import edge crosses communities: topogpt3/__init__.py imports topogpt3/inference.py.
- [EXTRACTED] depends_on community 2 <-> 4 (strength 0.9): Extracted import edge crosses communities: topogpt3/__init__.py imports topogpt3/lens_model.py.
- [INFERRED] bridges community 2 <-> 1 (strength 0.5): Inferred cross-community bridge: eval/governor.py reaches eval/sandbox_smoke.py in 5 hops.
- [INFERRED] bridges community 2 <-> 0 (strength 0.5): Inferred cross-community bridge: eval/governor.py reaches topogpt3/hodge_cm.py in 5 hops.
- [INFERRED] shares_context community 2 <-> 5 (strength 0.5): Inferred shared context (language py and layer utility) with no import path between community 2 (eval: governor) and community 5 (orphans).

## Risks

- [taint critical] `eval/governor_smoke.py` -> `eval/governor_smoke.py` via `eval` (0 hops)
- [taint critical] `eval/governor_smoke.py` -> `eval/governor.py` via `eval` (1 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/__init__.py` via `eval` (1 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/merged_config.py` via `eval` (2 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/inference.py` via `eval` (2 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/train.py` via `eval` (2 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/jlens.py` via `eval` (2 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/lens_model.py` via `eval` (2 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/inference_hrm.py` via `eval` (2 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/model.py` via `eval` (2 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/exploitgym_loader.py` via `eval` (3 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/ewc.py` via `eval` (3 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/exploitgym_config.py` via `eval` (3 hops)
- [taint critical] `eval/governor_smoke.py` -> `topogpt3/continuation.py` via `eval` (3 hops)
- [taint critical] `eval/governor_smoke.py` -> `synthetic_dataset.py` via `eval` (3 hops)

## Open Questions

- Is the dangerous import `eval` in `eval/governor_smoke.py` still required, or can it be isolated?
- What would break if the most connected file in eval: governor changed?
- Should eval: governor be split, given cohesion 0.31?

## Sources

- `app.py`
- `eval/governor.py`
- `eval/governor_smoke.py`
- `eval/repair.py`
- `eval/smoke.py`
- `topogpt3/__init__.py`