Toulmini

"The purpose of an argument is not to establish the truth of a conclusion, but to justify the right to hold it." — Stephen Toulmin, The Uses of Argument (1958)

A Logic Harness for arguments. Forces LLMs into structured, sequential reasoning through Toulmin's argumentation model—7 components, 4 phases. Bad logic crashes. Good logic flows.

When to Use Toulmini

Holiday dinner getting heated? Uncle says something that doesn't quite add up. Instead of arguing, try: "I wonder what my Logic Harness would say about that."

Toulmini turns debates into structured inquiry. Instead of getting defensive, invite others on the journey of figuring out what actually makes logical sense—together.

Perfect for:

• Family gatherings — When loved ones hold views that seem illogical, explore why instead of fighting
• Philosophical questions — "Would immortality be a curse?" "Is free will an illusion?"
• Contested claims — Force any argument through rigorous logical scrutiny
• Self-reflection — Test your own beliefs before defending them

What is Toulmin's Model?

Stephen Toulmin's argumentation model breaks reasoning into six interconnected components (plus a final verdict):

graph TD
    DATA["DATA (Grounds)"] --> CLAIM
    BACKING --> WARRANT
    WARRANT --> CLAIM
    REBUTTAL --> WARRANT
    QUALIFIER --> CLAIM
    CLAIM --> VERDICT

The 4 Tools

Phase 1: initiate_toulmin_sequence

Starts the analysis. Extracts DATA and constructs CLAIM.

• Input: query (str) - "Is this copyright infringement?"
• Output: Structured prompt → JSON with data + claim

Phase 2: inject_logic_bridge

Builds the logical bridge: WARRANT and BACKING.

• Input: query, data_json, claim_json
• Output: Structured prompt → JSON with warrant + backing

⚠️ HARD REJECTION: If strength == "weak" or "irrelevant", chain terminates.

Phase 3: stress_test_argument

Adversarial attack: REBUTTAL and QUALIFIER.

• Input: query, data_json, claim_json, warrant_json, backing_json
• Output: Structured prompt → JSON with rebuttal + qualifier

Must find "black swan" scenarios where the warrant fails.

Phase 4: render_verdict

Final judgment on the complete 6-part chain.

• Input: All 6 component JSONs + query
• Output: Structured prompt → JSON with verdict

Verdicts: SUSTAINED | OVERRULED | REMANDED

Execution Flow (The "Toulmin Loop")

Each phase consists of two distinct steps:

1. Tool Call: The MCP server returns a strict system directive (Prompt).
2. LLM Generation: The LLM follows that directive to generate structured JSON.

Query: "Would immortality be a curse?"

Phase 1: Grounding

1. Tool Call: initiate_toulmin_sequence(query)
2. LLM Generates:
   • DATA: Terror Management Theory, hedonic adaptation research
   • CLAIM: "Immortality constitutes a psychological curse..."

Phase 2: Logic Bridge

3. Tool Call: inject_logic_bridge(query, data, claim)
4. LLM Generates:
   • WARRANT: "If well-being depends on mortality awareness..."
   • BACKING: Heidegger, Becker, empirical TMT research
   • Strength Check: "strong" ✓

Phase 3: Stress Test

5. Tool Call: stress_test_argument(...)
6. LLM Generates:
   • REBUTTAL: Category error (mortal→immortal psychology)
   • QUALIFIER: "possibly" (45% confidence)

Phase 4: Judgment

7. Tool Call: render_verdict(...)
8. LLM Generates:
   • VERDICT: "REMANDED" - insufficient empirical grounding

See examples/ for complete JSON traces.

Why This Exists

LLMs tend to hedge, compromise, or give "balanced" answers without confronting genuine contradictions. Toulmini forces separation:

• No hedging in claims — qualifiers come later
• No skipping steps — can't render verdict without rebuttal
• Hard rejection of weak backing — stops the chain if support is speculative
• Adversarial stress testing — must find "black swan" edge cases

Architectural Constraints

Project Structure

toulmini/
├── pyproject.toml
├── README.md
├── verify_toulmini.py      # Verification script
├── examples/               # Full reasoning traces
└── src/toulmini/
    ├── __init__.py
    ├── server.py           # MCP entry point (FastMCP)
    ├── prompts.py          # 4 JSON-forcing prompt templates
    └── models/
        ├── __init__.py
        ├── base.py         # Citation, Literal types
        ├── components.py   # 7 Toulmin components
        └── chain.py        # ToulminChain aggregate

Failure Modes

Installation & Configuration

Prerequisites

• Python 3.10+
• pip or uv

Install Toulmini

pip install toulmini

Or for development:

git clone https://github.com/Hmbown/Toulmini.git
cd Toulmini
pip install -e .

Configure Your MCP Client

claude mcp add toulmini --scope user -- python -m toulmini.server

claude mcp list

{
  "mcpServers": {
    "toulmini": {
      "command": "python",
      "args": ["-m", "toulmini.server"]
    }
  }
}

{
  "toulmini": {
    "command": "python",
    "args": ["-m", "toulmini.server"]
  }
}

{
  "mcpServers": {
    "toulmini": {
      "command": "python",
      "args": ["-m", "toulmini.server"]
    }
  }
}

Verify Installation

Run the verification script:

python verify_toulmini.py

Or test manually by asking your AI assistant:

"Use the initiate_toulmin_sequence tool to analyze: Would immortality be a curse?"

Troubleshooting

Inspired By

• Hegelion — Dialectical reasoning (thesis/antithesis/synthesis)
• Stephen Toulmin, The Uses of Argument (1958)

License

MIT

Development

Running Tests

To run the tests, install pytest and mcp[cli], then run:

PYTHONPATH=src pytest