> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# NAMING

# Naming conventions for `core/`

A small, enforceable vocabulary so file and type names say what they are. The
goal is that a reader can tell a data type from a process, a mutable state from
a frozen view, and a package's purpose from its name alone.

## Glossary (one meaning per term)

| Term                         | Means                                                        | Example                             |
| ---------------------------- | ------------------------------------------------------------ | ----------------------------------- |
| **State**                    | Mutable investigation/session facts that evolve during a run | `AgentState`, `InvestigationState`  |
| **Snapshot**                 | A frozen view captured at a boundary (turn start, run start) | `TurnSnapshot`                      |
| **RunInput** / **RunResult** | The input to and output from one `Agent.run()` boundary      | `AgentRunInput`, `AgentRunResult`   |
| **Slice**                    | A typed segment of a state dict                              | `DiagnosisSlice`, `AlertInputSlice` |
| **Resources**                | Handles passed into tool executors for one call              | `ToolCallResources`                 |
| **Budget**                   | An LLM token/window policy — not application state           | `enforce_token_budget`              |
| **Host**                     | The callback contract an algorithm drives (a `Protocol`)     | `LoopHost`                          |

## Module naming: `{domain}_{role}.py`

Name a file for the concept it holds, not with a generic bucket word.

```
core/agent/
  agent.py          # the Agent facade
  react_loop.py     # ReactLoop + run_react_loop  (the algorithm)
  loop_host.py      # LoopHost                    (the callback contract)
  run_io.py         # AgentRunInput, AgentRunResult (the run boundary's I/O)
  mixins.py         # the reusable *Mixin behaviors
  provider_hooks.py # ProviderHookDelegate
```

## Type naming

* **Mixins** carry a `Mixin` suffix — they cannot stand alone (they assume
  fields/methods the host provides). `EventEmitterMixin`, `ToolFilterMixin`,
  `SteeringMixin`.
* **Protocols** are named by their role, not with a `Protocol` suffix — matches
  the stdlib (`Iterable`, `SupportsRead`) and `agent_harness/ports.py`
  (`OutputSink`, `SessionStore`). `LoopHost`, not `LoopHostProtocol`.
* **Do not prefix a type with its own package name.** Inside `core/agent/`, a
  class is `EventEmitterMixin`, not `AgentEventEmitter` — the namespace already
  says "agent."

## Anti-patterns (do not add in new code)

* `context.py` at `core/` or `core/agent/` root — "context" is overloaded across
  the repo. Name the concept (`run_io.py`, `turn_snapshot.py`).
* `models.py` when the file holds only run I/O — too vague. Say what the models
  are (`run_io.py`).
* `*Context` without a domain prefix when another `*Context` already exists.
* A package whose only child is a single sub-package — collapse the wrapper.

## Imports

Use fully qualified paths in code; keep short mental labels for docs.

| Mental label           | Import                                                             |
| ---------------------- | ------------------------------------------------------------------ |
| ReAct run I/O          | `from core.agent.run_io import AgentRunInput, AgentRunResult`      |
| ReAct loop             | `from core.agent.react_loop import run_react_loop`                 |
| Loop callback contract | `from core.agent.loop_host import LoopHost`                        |
| The agent primitive    | `from core.agent import Agent`                                     |
| Harness turn snapshot  | `from core.agent_harness.models.turn_snapshot import TurnSnapshot` |

Re-export from a package `__init__.py` only for its single canonical symbol
(`Agent`), not everything — avoid `from core.agent import *`-style ambiguity.