Apply review feedback: per-mode breaker split, adapter runner classes, docs fixes (#9, #10, #11)

[kamil-duszynski-dna]

Summary

Addresses three rounds of reviewer feedback. The branch bundles issues
#9, #10 and #11 as three focused commits.

• src/breaker.py issues #9 — Refactor the core CircuitBreaker by mode and apply assorted
  review notes.
• AGENTS.md issues #10 — Documentation fixes (mypy claim, repository layout).
• OOP issues #11 — Replace the with_circuit_breaker functions with per-adapter
  OOP runner classes.

The package stays mypy --strict clean and the full suite is green
(98 passed).

---

#9 — Split CircuitBreaker by mode + review cleanups

• Split into a base + per-mode strategies. CircuitBreaker(mode=...) is now
  a constructor that dispatches to internal _BudgetGuardBreaker /
  _LoopKillerBreaker. Each strategy is free of mode branching, so the
  per-method is None limit checks are gone.
• Mode is now an Enum (Mode.BUDGET_GUARD / Mode.LOOP_KILLER). The
  hand-rolled mode assertion is replaced by coerce_mode, which still accepts
  the string values ("budget-guard" / "loop-killer") for ergonomics.
• Numeric guards moved to core/_numbers.py: is_positive_integer
  (three-state) and is_non_negative_finite; the _describe helper is removed.
• Removed the dead return after _trip (which is NoReturn).
• Renames: set_token_snapshot → set_tokens; TokenMetrics /
  ExtractedTokens fields input/output → input_tokens/output_tokens.

Note: per the reviewer's choice, Mode is a plain Enum, so equality with raw
strings (mode == "budget-guard") no longer holds — assertions were updated to
compare against Mode members. String values are still accepted at all public
boundaries via coerce_mode.

#10 — Documentation fixes

• Corrected the type-check claim. "mypy --strict clean" was misleading:
  python -m mypy / mypy --strict src are clean, but mypy --strict . reports
  errors because the test suite isn't held to strict typing. The wording now says
  the package is strict-clean.
• Sorted the repository-layout tree (directories before files, core first)
  and added the previously-missing core/_numbers.py entry.

The reviewer's suggestion to change python -m mypy && python -m pytest to a
single & was not applied — && is correct (gate + shared exit code);
& would background mypy and run pytest in parallel, losing both.

#11 — Adapter runner classes (drop with_circuit_breaker)

• Removed the four identically-named with_circuit_breaker functions (the
  with prefix collided with the keyword and the duplicated names were a smell).

• New base CircuitBreakerRunner (_runner.py): captures the breaker
  config, mints a fresh breaker per run, gates the preflight estimator,
  resolves on_trip, and implements the context-manager protocol.

• One distinct subclass per adapter with a unified run() method:
  OpenAIAgentsCircuitBreakerRunner, LangChainCircuitBreakerRunner,
  ClaudeAgentCircuitBreakerRunner, LangGraphCircuitBreakerRunner.

• Canonical usage is a context manager:

  with OpenAIAgentsCircuitBreakerRunner(agent, max_input_token=50_000) as safe:
      result = await safe.run("Analyze this dataset")

Two design notes surfaced during review: the context manager is intentionally
minimal (the breaker is per-run, not per-block — documented in the base
class), and LangChain's run() is now async (awaits ainvoke, falls back to

---

Breaking changes

Pre-1.0; per AGENTS.md we prefer cleaner APIs over compat shims.

• with_circuit_breaker(...) → <Framework>CircuitBreakerRunner(...) used as a
  context manager, with a unified .run() method.
• Mode is an Enum (string values still accepted on input).
• CircuitBreaker.set_token_snapshot → set_tokens.
• TokenMetrics.input / .output → .input_tokens / .output_tokens.

Testing

• python -m mypy — clean (20 source files).
• python -m pytest — 98 passed (includes new context-manager coverage per
  adapter).