ARCHITECTURE.md

Architecture

toulmin-argument is a single-module, zero-dependency value-object library. There is intentionally no I/O, no global state, and no framework coupling — it is meant to be embedded inside larger systems and serialized across their boundaries.

Module map

Module	Responsibility
toulmin_argument/models.py	All public types: the two enums (QualifierLevel, DataAvailability), the ToulminArgument value object, and the InferenceStep / InferenceChain composition types. Each carries a to_dict() / from_dict() pair for JSON round-tripping.
toulmin_argument/__init__.py	Re-exports the public API and __version__.

Data flow

your decision code
      │  builds
      ▼
ToulminArgument ──► .to_dict() ──► JSON column / log line / API field
      ▲                                    │
      └──────────── .from_dict() ◄─────────┘  (round-trips for review/replay)

InferenceStep × N ──► InferenceChain ──► .to_dict()   (multi-step derivations)

Seams (external dependencies / injection points)

Seam	Status
Runtime dependencies	None. Pure standard library (dataclasses, enum).
Persistence	Caller-owned. The library only serializes to/from dict; you choose JSON, a DB column, a message field, etc.
Confidence vocabulary	QualifierLevel is a closed enum by design (auditable, finite). To use your own confidence labels, see docs/FORKING.md.

Design invariants

• Value objects, not entities — instances have no identity beyond their fields and no lifecycle.
• Serialization is total — every public type round-trips through to_dict() / from_dict() without loss.
• Domain-neutral — no field name, enum member, or default references any specific industry or product.