title	emoji	colorFrom	colorTo	sdk	sdk_version	app_file	pinned	license
Socratic Sofa	🏛️	indigo	purple	gradio	6.1.0	app.py	false	mit

🏛️ Socratic Sofa

AI-Powered Philosophical Dialogue Using the Authentic Socratic Method

Experience deep philosophical inquiry where AI explores topics through systematic questioning rather than assertions. Built with CrewAI and Claude, Socratic Sofa follows the classical Socratic method to reveal contradictions, challenge assumptions, and guide toward deeper understanding.

✨ Features

• 🤔 Socratic Philosopher Agent - Masters the art of philosophical questioning following authentic elenchus
• ⚖️ Dialectic Moderator - Evaluates the authenticity and effectiveness of Socratic inquiry with differentiation scoring
• 📚 100 Curated Topics - Philosophical questions across 7 categories: classics, ethics, mind, society, modern, fun, and personal
• 🌍 Multiple Philosophical Traditions - Questions draw from Greek, Eastern, Modern Western, and Contemporary philosophy
• 🛡️ Content Moderation - AI-powered filtering for appropriate philosophical discourse with rate limiting
• 🌐 Mobile-Responsive UI - Beautiful, touch-friendly interface that works on all devices
• 🔄 Streaming Output - Real-time dialogue generation with progress feedback
• 📜 Four-Stage Dialogue - Topic → Proposition → Opposition → Judgment
• 📊 Structured Logging - JSON-formatted logs with context chaining and performance timing
• ⏱️ Rate Limiting - API call throttling with automatic retry for reliability

🎯 How It Works

The Socratic Method

Unlike traditional debate systems, Socratic Sofa uses questions, not assertions:

1. Questions Only - No direct claims about truth, only questions that reveal it
2. Elenchus (Refutation) - Exposes contradictions through systematic questioning
3. Intellectual Humility - The questioner professes ignorance
4. Progressive Inquiry - Definition → Assumption → Contradiction → Insight

Using Socratic Sofa

1. Choose a Topic:

   • Select from 100 curated philosophical questions
   • Enter your own philosophical topic
   • Let the AI propose a topic

2. First Inquiry: Watch as the AI explores the topic through 5-7 Socratic questions

3. Alternative Inquiry: A second line of questioning from a different perspective

4. Evaluation: The Dialectic Moderator assesses both inquiries on:

   • Question Quality (40%)
   • Elenctic Effectiveness (25%)
   • Philosophical Insight (20%)
   • Socratic Fidelity (15%)
   • Differentiation Quality (bonus +10% for second inquiry)

📖 Example Topics

Ethics & Morality

• What is justice?
• Can we justify civil disobedience?
• What constitutes a good life?

Epistemology

• What is the nature of knowledge?
• Can we know anything with certainty?
• How do we distinguish truth from opinion?

Contemporary Issues

• Should AI have rights?
• What is the ethics of AI-generated art?
• What are our obligations to future generations?

🔧 Technical Details

• Framework: CrewAI 1.7.0 for multi-agent orchestration
• LLM: Claude Sonnet 4.5 via Anthropic API
• Interface: Gradio 6.1.0 with mobile-responsive design
• Method: Sequential task execution following philosophical dialogue structure
• Package Manager: UV for fast dependency management
• Testing: 80%+ code coverage with pytest
• CI/CD: GitHub Actions with automated deployment to HuggingFace Spaces
• Content Safety: Claude-powered content moderation with rate limiting (10 calls/60s)
• Logging: Structured JSON logging with context chaining and performance timing
• Rate Limiting: Automatic retry with exponential backoff for API reliability

🚀 Getting Started

Prerequisites

• Python 3.10+ (but less than 3.14)
• UV package manager (pip install uv)
• Anthropic API key (get one here)

Quick Setup

# Clone the repository
git clone https://github.com/darth-dodo/socratic-sofa.git
cd socratic-sofa

# Install dependencies with UV
uv sync

# Configure API key
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# Run the web interface
uv run socratic_web

# Or run the CLI
uv run socratic_sofa

The web interface will be available at http://localhost:7860

Running Tests

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src/socratic_sofa --cov-report=term-missing

# Current coverage: 80%+

🏗️ Architecture Overview

Core Components

• crew.py: CrewAI orchestration with socratic_questioner and judge agents
• gradio_app.py: Web interface with topic selection and streaming output
• content_filter.py: Content moderation using Claude API for safety
• logging_config.py: Structured JSON logging with context chaining and timing
• rate_limiter.py: API rate limiting with automatic retry and exponential backoff
• config/agents.yaml: Agent configurations with philosophical traditions
• config/tasks.yaml: Task definitions with differentiation requirements
• topics.yaml: 100 curated topics organized by 7 categories

Logging and Monitoring

The application uses structured logging for better observability:

• JSON Format: All logs are JSON-formatted for easy parsing and analysis
• Context Chaining: Logger contexts can be chained via with_context() for request tracking
• Performance Timing: log_timing context manager and log_function_call decorator track operation duration
• Request Tracking: Each dialogue session gets a unique request_id for end-to-end tracing

Example usage:

from socratic_sofa.logging_config import get_logger, log_timing

logger = get_logger(__name__)
logger = logger.with_context(request_id="abc-123", user="demo")

with log_timing(logger, "dialogue_generation"):
    # Your code here
    logger.info("Processing topic", topic="justice")

Rate Limiting

API calls are protected with rate limiting to prevent quota exhaustion:

• Decorator-Based: @rate_limited(calls=10, period=60) with automatic retry
• Content Moderation: Limited to 10 calls per 60 seconds
• Exponential Backoff: Automatic retry with increasing delays on rate limit hits
• Exception Handling: RateLimitException for cases requiring manual handling

Agent Workflow

User Topic → Content Filter → Propose Topic
                                    ↓
                            First Inquiry (5-7 questions)
                                    ↓
                            Second Inquiry (different angle)
                                    ↓
                            Judge Evaluation (with differentiation scoring)

Recent Improvements

• Differentiation Scoring: Second inquiry receives bonus points (up to +10%) for exploring genuinely different philosophical angles
• Markdown Output: Judge provides formatted evaluation with tables and emoji indicators
• Philosophical Traditions: Agents draw from Greek, Eastern, Modern Western, and Contemporary philosophy
• Repetition Penalty: Judge penalizes overlapping questions or themes (up to -15%)
• Category Filtering: Topics organized by category with random selection within categories
• Streaming Interface: Real-time output display during dialogue generation

🛠️ Development

Pre-commit Hooks

This project uses pre-commit hooks for code quality:

# Install hooks (one-time setup)
make precommit-install

# Run all checks manually
make precommit

# Run security checks only
make security

Included hooks:

• Formatting: isort, ruff-format
• Linting: ruff (pycodestyle, pyflakes, bugbear, security)
• Security: bandit, detect-secrets
• Quality: vulture (dead code), large file check
• Dev Experience: trailing whitespace, YAML/JSON validation, prettier

🌐 Deployment

HuggingFace Spaces

Live demo available at: https://huggingface.co/spaces/darth-dodo/socratic-sofa

Deployment is automated via GitHub Actions:

• Push to main branch triggers CI tests
• Successful tests trigger deployment to HuggingFace Spaces
• Space configuration: Gradio SDK 6.1.0, Python 3.12

Local Docker Deployment

# Build the image
docker build -t socratic-sofa .

# Run with environment variable
docker run -p 7860:7860 -e ANTHROPIC_API_KEY=your_key socratic-sofa

📚 Learn More

• Live Demo: HuggingFace Spaces
• GitHub: socratic-sofa
• Documentation: Full Docs
• Socratic Method: Stanford Encyclopedia

🤝 Contributing

Contributions welcome! See the GitHub repository for:

• Feature requests
• Bug reports
• Documentation improvements
• New philosophical topics

📄 License

MIT License - See LICENSE for details

---

"The unexamined life is not worth living." - Socrates

Built with CrewAI and Claude | Inspired by classical Socratic philosophy