​

Naming conventions for core/

​

Glossary (one meaning per term)

​

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

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