FORKING.md

Forking this into your product

toulmin-argument is designed to be embedded as-is. There is no domain code to strip — the types are already neutral. This guide covers the few places you may want to adapt.

1. Use it directly (recommended)

Vendor the src/toulmin_argument/ package into your project, or pip install -e . it. Build ToulminArgument objects at every decision site and serialize them with to_dict() into whatever you already persist (a JSONB column, a structured log, an API response field).

decision = ToulminArgument(
    claim=...,
    grounds=...,        # the evidence YOUR system used
    warrant=...,        # YOUR rule that links grounds → claim
    qualifier=QualifierLevel.PROBABLE,
    rebuttal=...,       # what would change YOUR mind
    data_availability=DataAvailability.SUFFICIENT,
)
record["reasoning"] = decision.to_dict()

2. Override the confidence vocabulary

QualifierLevel is a closed enum on purpose: a finite, auditable confidence ladder is more reviewable than free text. If your domain needs different bands (for example a numeric posterior, or a regulator-mandated scale), the override seam is the enum itself:

• Re-map at the boundary — keep the five internal levels and translate to your external scale in your serialization layer. This preserves auditability.
• Replace the enum — edit QualifierLevel in models.py to your members. Keep it an Enum (not free strings) so the linter/DB can still validate it.

3. Add domain fields without forking the core

Prefer composition over editing the dataclass:

@dataclass
class ScoredDecision:
    argument: ToulminArgument
    score: float
    subject_id: str

This keeps you on the upstream toulmin_argument types and confines your domain data to your own wrapper.

4. Multi-step reasoning

When a conclusion is reached through several steps, build an InferenceStep per step and collect them into an InferenceChain. Put the identifiers of the evidence each step used in based_on_ids so the chain is traceable back to source data you control.

What NOT to change

• The to_dict() / from_dict() key names — downstream consumers and stored records depend on them. If you must rename, version your serialization.
• The presence of rebuttal and data_availability — these are the fields that make the model defensible. Dropping them defeats the purpose.