🍑 ASS - Argumentative System Service

🎭 What is ASS?

ASS (Argumentative System Service) is an advanced debate simulation platform that models how expert-level AI personalities argue, reason, and potentially change their minds when presented with compelling evidence. Using internal belief states and sophisticated reasoning systems, ASS helps explore complex topics from multiple perspectives to arrive at more nuanced, well-considered conclusions.

🤖 AI-Generated Project: This entire project was generated by AI from an original idea by Diogo. The concept, architecture, code, and documentation were all created through an AI-assisted development process, demonstrating the potential of human-AI collaboration in software creation.

Perfect for:

• 🧠 Complex Problem-Solving - Model expert debates to find optimal solutions
• 🔬 Research & Analysis - Explore topics with rigorous, evidence-based reasoning
• 🤔 Decision Support - Get high-quality arguments from multiple expert perspectives
• 📚 Educational Tools - Demonstrate critical thinking and belief revision
• 🎯 Truth-Seeking - Watch AI experts converge on well-reasoned conclusions

🎭 Meet the Debaters

Each personality maintains internal beliefs about truth while presenting arguments, potentially updating their views when faced with compelling evidence. After reaching consensus through voting, an impartial Judge synthesizes all perspectives into a final decision.

🧠 Revolutionary Features

Internal Belief Systems

Each AI personality maintains private beliefs about what's actually true, separate from their public arguments. They can:

• Form expert-level initial assessments based on evidence
• Update beliefs when presented with compelling counter-arguments
• Maintain intellectual honesty while arguing their position

Dynamic Consensus Building

• Personalities debate until reaching agreement through ranked voting
• Arguments must directly engage with others' points
• Real belief revision when evidence warrants it
• Configurable resistance to changing minds

Expert-Level Reasoning

• Deep analysis with citations and evidence
• Field-specific expertise applied to questions
• Rigorous logical argumentation
• Truth-seeking balanced with debate dynamics

🎬 Example Debates

🤖 "Should we develop AGI as fast as possible?"

🍕 "Is pineapple on pizza acceptable?"

🚀 Quick Start

Prerequisites

• Python 3.9+
• UV package manager (install here)
• API Keys:
  • OpenAI API key
  • Anthropic Claude API key

Installation

1. Clone the repository:

   git clone https://github.com/DiogoNeves/ass.git
   cd ass

2. Install dependencies:

   uv sync

3. Set up your API keys:
   Create a .env file:

   CLAUDE_API_KEY=your_claude_api_key_here
   OPENAI_API_KEY=your_openai_api_key_here

Running Debates

Web Interface - Browser-based with real-time streaming:

uv run python web_server.py
# Then open http://localhost:8000

Interactive CLI - Terminal interface with Rich formatting:

uv run python debate_app.py

Demo Mode - See a pre-configured debate:

uv run python demo.py

🎮 How It Works

🗳️ Voting Mode (Default)

graph TD
    A[Your Question] --> B[Iteration 0: Initial Positions]
    B --> C[Iteration 1+: Direct Argumentation]
    C --> D{Voting Phase}
    D -->|No Consensus| C
    D -->|Consensus Reached| E[Judge Reviews Everything]
    E --> F[Final Decision]
    
    style A fill:#e1f5fe
    style D fill:#fff3cd
    style F fill:#f3e5f5

1. 🎯 Question Input - You provide any question or topic
2. 💭 Initial Positions - Each personality presents their stance without arguing
3. 🥊 Argumentation - Personalities directly engage with each other's points
4. 🗳️ Voting - After each iteration, personalities rank all participants
5. 🔄 Consensus Check - Continue until voting threshold is reached
6. ⚖️ Judge Review - Final synthesis with potential override

🎭 Classic Mode

graph TD
    A[Your Question] --> B[Round 1: Opening Arguments]
    B --> C[Round 2: Rebuttals & Counter-arguments]
    C --> D[Round 3: Final Positions]
    D --> E[Judge's Final Decision]
    
    style A fill:#e1f5fe
    style E fill:#f3e5f5

Use --classic-mode to run the original 3-round format.

🛠️ Architecture

The application uses a modular architecture with Pydantic validation and clear separation of concerns:

# Create a new personality with validated configuration
from models.personality import PersonalityConfig
from personalities import create_personality

new_personality = create_personality(PersonalityConfig(
    name="My Custom Debater",
    model_provider="claude",  # or "openai" or "local"
    model_name="claude-3-5-sonnet-20241112",
    system_prompt="Your personality description...",
    reasoning_depth=8,
    truth_seeking=7,
    voting_traits=PersonalityTraits(fairness=8, self_confidence=6)
))

Key Components:

• models/ - Pydantic models with automatic validation:
  • PersonalityConfig - Validated personality configuration
  • Vote, VotingConfig - Voting system models
  • DebateConfig, DebateState - Debate management
  • Argument, ArgumentHistory - Argument tracking
• personalities/ - AI personality implementations:
  • LLMPersonality - Abstract base class
  • ClaudePersonality, OpenAIPersonality, LocalModelPersonality
• services/ - Business logic:
  • DebateManager - Core debate orchestration
  • FileManager - Save/load debates with AI titles
• ui/ - User interface:
  • RichFormatter - Terminal formatting
  • PromptHandler - User input handling

💡 Interesting Questions to Try

🧠 Philosophy & Ethics

• "Is free will an illusion?"
• "Should we prioritize individual freedom or collective security?"
• "Is artificial consciousness possible?"

🌍 Society & Technology

• "Should social media be regulated like tobacco?"
• "Is remote work better for society than office work?"
• "Should we colonize Mars or fix Earth first?"

🎨 Creative & Fun

• "Which is the superior breakfast: cereal or toast?"
• "Should we bring back extinct species through genetic engineering?"
• "Is a hot dog a sandwich?"

🏛️ Policy & Governance

• "Should voting be mandatory in democracies?"
• "Is universal basic income feasible?"
• "Should we abolish daylight saving time?"

🎨 Features

• 🧠 Internal Belief States - AI personalities maintain private beliefs about truth
• 🎓 Expert-Level Reasoning - Deep analysis with evidence and field-specific knowledge
• 🔄 Belief Revision - Personalities can genuinely change their minds with strong evidence
• 🗳️ Consensus-Based Voting - Debate until reaching agreement through ranked voting
• 💬 Direct Argumentation - Must engage with others' specific points
• 📊 Configurable Persistence - Control how resistant each personality is to changing beliefs
• 🤖 Multi-Model Support - Claude, OpenAI, and local model servers
• ⚖️ Truth-Seeking Judge - Maximum reasoning depth and openness to best arguments
• 🎯 Sophisticated Traits - Belief persistence, reasoning depth, truth-seeking levels
• ✅ Pydantic Validation - Runtime validation of all data structures with clear error messages
• 🔧 Highly Configurable - JSON configs, environment variables, CLI flags
• 📈 Belief Tracking - Monitor how positions evolve through debate
• 🌐 Web Interface - Browser-based UI with real-time SSE streaming
• 🎭 Rich CLI Interface - Beautiful formatting with progress indicators
• 💾 Automatic Debate Saving - Preserves complete debate history with AI-generated titles
• 🏗️ Modular Architecture - Clear separation between models, services, UI, and personalities

🔧 Customization

Adding New Personalities

Extend the debate by creating personalities with unique traits (with full validation):

from models.personality import PersonalityConfig, PersonalityTraits

personalities["economist"] = create_personality(PersonalityConfig(
    name="Dr. Economy", 
    model_provider="openai",
    model_name="gpt-4o-20250117",
    system_prompt="You are a pragmatic economist focused on costs, benefits, and market dynamics...",
    reasoning_depth=9,
    truth_seeking=8,
    belief_persistence=7,
    voting_traits=PersonalityTraits(
        fairness=8,
        self_confidence=7,
        strategic_thinking=9,
        empathy=6
    )
))

Supported Models

Anthropic Claude:

• claude-sonnet-4-20250514 (Latest & Recommended - 2025)
• claude-3-5-sonnet-20241022
• claude-3-haiku-20240307
• Other Claude models

OpenAI:

• gpt-4.1-2025-04-14 (Latest & Recommended - 2025)
• gpt-4
• gpt-4-turbo
• gpt-3.5-turbo

Local Models:

• Any OpenAI-compatible API endpoint
• Configure with --local-model-url or LOCAL_MODEL_URL environment variable

Configuration Options

Command Line Arguments

# Voting mode options
uv run python debate_app.py --voting-threshold 0.8  # Set consensus to 80%
uv run python debate_app.py --max-iterations 15     # Allow up to 15 rounds
uv run python debate_app.py --min-iterations 3      # Require 3 rounds before voting

# Classic mode
uv run python debate_app.py --classic-mode           # Use original 3-round format
uv run python debate_app.py --no-voting             # Disable voting system

# Local model support
uv run python debate_app.py --local-model-url http://localhost:8080

# Configuration file
uv run python debate_app.py --config my_config.json

# Disable automatic saving
uv run python debate_app.py --no-save

Environment Variables

# Voting configuration
export DEBATE_VOTING_ENABLED=true
export DEBATE_CONSENSUS_THRESHOLD=0.75
export DEBATE_MAX_ITERATIONS=10
export DEBATE_CLASSIC_MODE=false

# Local model configuration
export LOCAL_MODEL_URL=http://localhost:8080
export LOCAL_MODEL_AUTH=your-auth-token
export LOCAL_MODEL_TIMEOUT=30

# API Keys (existing)
export CLAUDE_API_KEY=your_claude_key
export OPENAI_API_KEY=your_openai_key

Configuration File

Create a JSON configuration file (see sample_config.json):

{
  "voting_enabled": true,
  "consensus_threshold": 0.75,
  "min_iterations": 2,
  "max_iterations": 10,
  "scoring_system": {
    "1": 4,
    "2": 3,
    "3": 2,
    "4": 1
  },
  "judge_can_override": true,
  "override_threshold": 0.9,
  "allow_local_models": true,
  "local_model_timeout": 30,
  "classic_mode": false
}

📁 Project Structure

ass/
├── 📄 README.md           # This file
├── ⚙️ pyproject.toml      # UV project configuration
├── 🔒 uv.lock            # Dependency lock file
├── 🔐 .env               # API keys (create this)
├── 🎭 debate_app.py       # CLI interactive application entry point
├── 🧠 debate_engine.py    # Shared debate logic (generator-based, UI-agnostic)
├── 🌐 web_server.py       # FastAPI web server with SSE streaming
├── 📁 static/            # Web frontend assets
│   └── index.html        # Single-page debate UI
├── 📁 models/            # Pydantic data models with validation
│   ├── __init__.py
│   ├── personality.py    # PersonalityConfig, PersonalityTraits
│   ├── voting.py         # Vote, VotingConfig, VotingResult
│   ├── debate.py         # DebateConfig, DebateState
│   └── arguments.py      # Argument, ArgumentHistory
├── 📁 personalities/     # AI personality implementations
│   ├── __init__.py
│   ├── base.py          # LLMPersonality abstract base class
│   ├── claude.py        # Claude implementation
│   ├── openai.py        # OpenAI implementation
│   ├── local.py         # Local model implementation
│   └── factory.py       # create_personality factory
├── 📁 services/         # Business logic services
│   ├── __init__.py
│   ├── debate_manager.py # Core debate orchestration
│   └── file_manager.py   # Save/load with AI titles
├── 📁 ui/               # User interface components
│   ├── __init__.py
│   ├── rich_formatter.py # Rich terminal formatting
│   └── prompts.py       # User input handling
├── 🧠 personality.py     # Backward compatibility imports
├── 🗳️ voting.py         # Voting system implementation
├── ⚙️ config.py         # Debate configuration
├── 🎬 demo.py           # Demo runner with sample debates
├── 📋 sample_config.json # Example configuration file
├── 📄 VOTING-FEATURE.md  # Voting feature requirements
└── 📁 debates/          # Saved debate files (auto-created)
    └── .gitkeep         # Keeps folder in git

🤝 Contributing

We welcome contributions! Here are some ideas:

• 🎭 New Personality Types - Add specialists (scientist, artist, philosopher)
• 🔌 Additional LLM Providers - Support for more AI models (Gemini, Mistral, etc.)
• 🎪 Enhanced Debate Formats - Tournament brackets, team debates, panel discussions
• 🗳️ Alternative Voting Systems - Approval voting, Condorcet method, etc.
• 🎨 UI Improvements - Better visualizations, vote graphs, debate trees
• 📊 Analytics - Argument quality metrics, consensus patterns, debate statistics
• ✅ Web Interface - Already implemented! FastAPI + SSE with dark-themed frontend
• 💾 Enhanced Debate History - Advanced analysis and replay features
• 🔍 Argument Mining - Extract key points and conclusions automatically

Development Setup

# Clone and setup
git clone https://github.com/DiogoNeves/ass.git
cd ass
uv sync

# Install development dependencies
uv sync --dev

# Set up pre-commit hooks (one-time)
uv run pre-commit install

# Code quality checks
uv run pylint *.py                    # Linting (baseline ~6.6/10)
uv run isort . --check-only          # Check import order
uv run autoflake --check -r .        # Check for unused imports

# Auto-fix code issues
uv run isort .                       # Fix import ordering
uv run autoflake --remove-all-unused-imports -r . -i  # Remove unused imports

# Run tests (when added)
uv run pytest

# Run a debate without saving
uv run python debate_app.py --no-save

Code Quality Tools

The project uses several tools to maintain code quality:

• pre-commit - Runs automatic checks before each commit
• pylint - Static code analysis (config in .pylintrc)
• isort - Import sorting (config in .isort.cfg)
• autoflake - Removes unused imports and variables
• Pydantic - Runtime validation for all data models

Current pylint score: ~6.6/10 (improving over time)

Pre-commit hooks automatically run:

• Import sorting with isort
• Unused import removal with autoflake
• Trailing whitespace removal
• File ending fixes
• YAML/JSON validation

Note: pylint is not included in pre-commit due to speed, run it separately.

💾 Automatic Debate Saving

Debates are automatically saved to JSON files in the debates/ directory with:

• AI-Generated Titles - Using Claude Haiku for fast, descriptive naming
• Complete History - All iterations, arguments, votes, and decisions
• Timestamped Files - Format: YYYYMMDD_HHMMSS_Title_Keywords.json
• Incremental Saves - State saved after each iteration for crash recovery

Saved Data Includes:

• Question and generated title
• All personality arguments by iteration
• Voting records and consensus tracking
• Internal belief updates (when DEBUG_BELIEFS=true)
• Judge's final decision
• Configuration used for the debate

Control Saving:

# Disable saving for quick tests
uv run python debate_app.py --no-save

# Or via environment variable
export DEBATE_SAVE_ENABLED=false

Example Saved File:

{
  "title": "AI Development Speed Debate",
  "question": "Should we develop AGI as fast as possible?",
  "timestamp": "20250621_143052",
  "iterations": [
    {
      "iteration": 0,
      "arguments": { /* personality arguments */ },
      "consensus_reached": false
    },
    // ... more iterations
  ],
  "final_consensus": true,
  "final_judge_decision": "After careful consideration..."
}

🛠️ Troubleshooting

🔑 API Key Issues:

• Ensure your .env file is in the project root
• Verify API keys are valid and have sufficient credits
• Check that keys don't have extra spaces or quotes

📦 Import Errors:

• Run uv sync to install all dependencies
• Ensure you're using Python 3.9+
• Use uv run python script.py instead of python script.py

🌐 UV Issues:

• Install UV: Installation Guide
• Update UV: uv self update

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Rich - Beautiful terminal formatting
• OpenAI - GPT models and API
• Anthropic - Claude models and API
• UV - Fast Python package manager