Skip to main content

​
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)

TermMeansExample
StateMutable investigation/session facts that evolve during a runAgentState, InvestigationState
SnapshotA frozen view captured at a boundary (turn start, run start)TurnSnapshot
RunInput / RunResultThe input to and output from one Agent.run() boundaryAgentRunInput, AgentRunResult
SliceA typed segment of a state dictDiagnosisSlice, AlertInputSlice
ResourcesHandles passed into tool executors for one callToolCallResources
BudgetAn LLM token/window policy — not application stateenforce_token_budget
HostThe 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 labelImport
ReAct run I/Ofrom core.agent.run_io import AgentRunInput, AgentRunResult
ReAct loopfrom core.agent.react_loop import run_react_loop
Loop callback contractfrom core.agent.loop_host import LoopHost
The agent primitivefrom core.agent import Agent
Harness turn snapshotfrom 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.