Module 0 core - #1
Merged
Merged
Conversation
- RunResult and value objects: deep-immutable frozen dataclasses (tuples + read-only mappings); with_scores returns a new object. - AgentArgusConfig (env + kwargs) and injectable Judge protocol (no bundled provider client). - Logging: get_logger factory, color + JSON formatters, contextvars trace correlation, TTY/NO_COLOR gating, print() banned via ruff T20. - Tooling: hatchling pyproject, ruff, mypy strict, CI matrix 3.10/3.11/3.12. - 30 tests, 96% coverage; ruff + mypy clean. - DESIGN_LOG + HARD_QUESTIONS for Module 0. NOTE: methodoverload 0.1.7 has no OverloadMeta (spec §4 out of date); @overload works on methods with no metaclass. Documented in DESIGN_LOG. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
HARD_QUESTIONS-driven improvements (owner review): - #5 configure_logging: threading.Lock + atomic handler swap (never half-configured) - #6 batch_complete() helper probes optional complete_batch; Judge keeps complete as its only required protocol member (adding it broke isinstance) - #7 to_dict coerces via _jsonable (JSON -> .to_dict() -> SerializationError naming the field); no silent lossy fallback - #9 malformed AGENTARGUS_COST_CEILING_USD now raises ConfigError (fail-fast) - new _internal/exceptions.py: AgentArgusError, ConfigError, SerializationError methodoverload (studied gracefully, not forced): - read installed source + PyPI; wrote docs/concepts/methodoverload.md - public API is exactly overload/OverloadedFunction/NoMatchingOverloadError; OverloadMeta is internal-only (spec §4 out of date) -> we don't use it - documented isinstance dispatch, no-generics, first-match-wins, the bool<:int ordering trap, and the callable non-fit for Agent.wrap 40 -> 36 tests all green, 96% coverage; ruff + mypy clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The nested AgentArgus/ folder was the PyPI name-reservation stub (empty __init__, planning-stage pyproject, placeholder README). Module 0 supersedes it with a real package at the repo root (standard Python layout). Remote history is preserved; only the stub tree is dropped. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Untrack IMPLEMENTAION.md (private build spec); the public decision record is DESIGN.md / DESIGN_LOG.md / HARD_QUESTIONS.md. - gitignore IMPLEMENTAION.md and module_notes/ (local per-module study notes). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Module 0 — Core Foundation
Establishes the foundation every later module builds on: the canonical result object, central configuration, and the logging system. No features yet by design — just the spine, done right and frozen, so Modules 1–11 never redefine it.
What's included
Core domain model (
agentargus/core/results.py)RunResult— the single canonical result object that is the spine of the system, plus value objectsSpan,ToolCall,Step,ErrorRecord,CostBreakdown.frozen=Truedataclasses with collection fields stored as tuples and mappings as read-only views — genuinely immutable, not just top-level frozen.with_scores()returns a newRunResult(copy-on-write) rather than mutating;to_dict()/from_dict()provide a JSON round-trip.Configuration & judge seam (
agentargus/config.py)AgentArgusConfig— env + explicit-kwarg resolution (explicit wins).Judgeprotocol — the injectable LLM-as-judge seam. No provider client ships in the base package (framework-agnostic, minimal deps); adapters live behind extras.batch_complete()helper for optional batched judging.Logging system (
agentargus/logging.py)get_logger()factory; color + JSON formatters.trace_idcorrelation viacontextvars(bridges logs ↔ traces, survives async boundaries).NO_COLOR, or via config;print()banned in library code via ruffT20.Internal exceptions (
agentargus/_internal/exceptions.py)AgentArgusError,ConfigError,SerializationError— one home for library error types.Tooling & packaging
pyproject.toml(hatchling),.ruff.toml, CI matrix on Python 3.10 / 3.11 / 3.12 (ruff → format-check → mypy strict → pytest).Review-driven hardening (from HARD_QUESTIONS)
ConfigError(never silently default a safety limit).configure_logging(lock + atomic handler swap).Judgeprotocol kept minimal so simplecomplete-only adapters still satisfyisinstance(batching is a duck-typed optional extension).Notes
methodoverload(v0.1.7) against its source; documented the real API indocs/concepts/methodoverload.md. The spec'sOverloadMetametaclass is not part of the public API —@overloadworks on methods without it.Verification
ruff check+ruff format --checkcleanmypy --strictcleanDefinition of Done
print(); correct log levels + trace correlationDESIGN_LOG.mdentry +HARD_QUESTIONS.mdbatch written