AI Argument Editor

A professional standalone web application for analyzing, editing, and validating argument structures using AI. Built with FastAPI (backend) and React (frontend).

Features

• Argument Structure Editing: Create and edit propositions with premises, derivation rules, and comments
• Interactive Graph Visualization: View and edit argument structure as an interactive node graph (React Flow)
• AI-Powered Analysis: Analyze argument strength, validate logic, and get improvement suggestions
• Document Source Integration: Extract arguments from pdai scholarly documents (OCR-processed XML)
• Text Extraction: Extract argument structures from unstructured text using AI
• File Management: Manage XML argument files with import/export capabilities
• Portable Path System: Easy to move between computers with configurable paths
• Responsive UI: Works on desktop, tablet, and mobile devices

Quick Start

1. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure API key (required for AI features)
# Edit .env file and add your Gemini API key
# Get a key at: https://makersuite.google.com/app/apikey

# Start the server
uvicorn app.main:app --reload --port 5400

2. Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

3. Access the Application

Open your browser to: http://localhost:5173

Path Configuration System

The AI Argument Editor uses a flexible, portable path configuration system that allows the application to run seamlessly on different computers with different file system architectures.

Overview

The path system supports: - Relative paths (resolved from application root) - Absolute paths (for external drives or specific locations) - Auto-detection (for pdai document sources) - Per-machine configuration (via config.json) - Environment variable overrides (via .env)

Configuration Files

1. config.json (Primary Path Configuration)

Located in the application root directory. Created automatically when you change settings, or create manually:

{
  "paths": {
    "data_folder": "data",
    "xml_folder": "arguments",
    "exports_folder": "exports",
    "pdai_path": null
  }
}

2. backend/.env (Environment Variables)

For sensitive settings and overrides:

# Required for AI features
GEMINI_API_KEY=your_api_key_here

# AI Model (strictly enforced - do not change)
GEMINI_MODEL=gemini-3.8-flash

# Optional: Override application root
APP_ROOT=/custom/path/to/app

# Debug mode
DEBUG=false

# Server port
PORT=5400

Path Resolution

Paths are resolved in the following order:

1. Absolute paths: Used as-is if path starts with / (Unix) or drive letter (Windows)
2. Relative paths: Resolved relative to APP_ROOT
3. APP_ROOT determination:
4. If APP_ROOT env var is set → use that path
5. Otherwise → parent directory of backend/ folder

Examples

// Relative paths (portable - recommended)
{
  "paths": {
    "data_folder": "data",
    "xml_folder": "arguments"
  }
}
// Resolves to: /path/to/ai-argument/data/arguments/

// Absolute paths (machine-specific)
{
  "paths": {
    "data_folder": "/Users/shared/argument-data",
    "xml_folder": "arguments"
  }
}
// Resolves to: /Users/shared/argument-data/arguments/

// External drive (for pdai documents)
{
  "paths": {
    "pdai_path": "/Volumes/ExternalDrive/2026project/pdai"
  }
}

pdai Document Source Configuration

The pdai path can be configured in three ways:

Option 1: Auto-Detection (Default)

When pdai_path is null, the system searches these locations in order:

1. /Volumes/PortableMacAir/2026project/pdai (External drive)
2. ~/Dropbox/202x/2026project/pdai (Dropbox sync)
3. ~/Dropbox/Buero/Begutachtung/Promotionen/Berthoud/pdai (Legacy)

Option 2: Settings UI

1. Go to Settings in the application
2. Find the Document Sources (pdai) card
3. Enter a custom path and click Save
4. Or click Auto-detect to use automatic detection

Option 3: config.json

{
  "paths": {
    "pdai_path": "/Volumes/MyDrive/pdai"
  }
}

Option 4: API

# Set custom path
curl -X PUT http://localhost:5400/api/config/pdai-path \
  -H "Content-Type: application/json" \
  -d '{"path": "/Volumes/MyDrive/pdai"}'

# Use auto-detection
curl -X POST http://localhost:5400/api/config/pdai-path/auto-detect

Multi-Machine Setup

To use the application on multiple computers:

Scenario 1: Shared Dropbox Folder

The application is in a synced Dropbox folder. Both computers access the same files.

config.json (same on both machines):

{
  "paths": {
    "data_folder": "data",
    "xml_folder": "arguments",
    "exports_folder": "exports",
    "pdai_path": null
  }
}

The pdai path auto-detects based on what's available on each machine.

Scenario 2: Different Data Locations

Each machine has data in different locations.

Machine A (MacBook) - config.json:

{
  "paths": {
    "data_folder": "/Users/alice/Documents/argument-data",
    "pdai_path": "/Volumes/PortableMacAir/2026project/pdai"
  }
}

Machine B (Desktop) - config.json:

{
  "paths": {
    "data_folder": "/home/bob/argument-data",
    "pdai_path": "/mnt/external/pdai"
  }
}

Solution: Don't sync config.json - let each machine have its own. Add to .gitignore:

config.json

Scenario 3: Portable USB Setup

Application and data on a USB drive.

config.json:

{
  "paths": {
    "data_folder": "data",
    "xml_folder": "arguments",
    "exports_folder": "exports"
  }
}

Using relative paths, everything stays within the application folder on the USB drive.

Directory Structure

ai-argument/
├── config.json              # Path configuration (machine-specific)
├── backend/
│   ├── .env                 # Environment variables (machine-specific)
│   ├── app/
│   │   ├── config.py        # Configuration manager
│   │   ├── services/
│   │   │   └── document_service.py  # pdai auto-detection
│   │   └── ...
│   └── requirements.txt
├── frontend/
│   └── ...
├── data/                    # Default data folder (relative)
│   ├── arguments/           # XML argument files
│   └── exports/             # Exported files
└── README.md

Configuration API

The configuration can be read and modified via the API:

Example: Get Configuration

curl http://localhost:5400/api/config/

Response:

{
  "app_name": "AI Argument Editor",
  "app_root": "/Users/alice/Dropbox/ai-argument",
  "paths": {
    "data_folder": "data",
    "xml_folder": "arguments",
    "exports_folder": "exports",
    "data_path_absolute": "/Users/alice/Dropbox/ai-argument/data",
    "xml_path_absolute": "/Users/alice/Dropbox/ai-argument/data/arguments",
    "exports_path_absolute": "/Users/alice/Dropbox/ai-argument/data/exports"
  },
  "ai": {
    "model": "gemini-3.8-flash",
    "api_key_configured": true
  },
  "pdai": {
    "path": null,
    "effective_path": "/Volumes/PortableMacAir/2026project/pdai",
    "auto_detected_path": "/Volumes/PortableMacAir/2026project/pdai",
    "available": true,
    "document_count": 12
  }
}

Troubleshooting

"No documents available"

The pdai folder was not found. Check: 1. Is the external drive connected? 2. Is the path correct in Settings? 3. Try clicking "Auto-detect" in Settings

"Failed to save file"

The configured path doesn't exist or isn't writable. Check: 1. Run GET /api/config/health to verify paths 2. Ensure the data folder exists and is writable 3. Check file permissions

Configuration not loading

The config.json file may be malformed. Check: 1. Validate JSON syntax 2. Ensure all path values are strings 3. Check the server logs for errors

Project Structure

ai-argument/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI application
│   │   ├── config.py            # Configuration management
│   │   ├── models.py            # Pydantic models
│   │   ├── schemas/
│   │   │   └── argument.dtd     # XML schema for arguments
│   │   ├── routers/
│   │   │   ├── files.py         # File management endpoints
│   │   │   ├── arguments.py     # Argument processing endpoints
│   │   │   ├── config.py        # Configuration endpoints
│   │   │   └── documents.py     # pdai document endpoints
│   │   └── services/
│   │       ├── xml_service.py   # XML parsing/generation
│   │       ├── ai_service.py    # Gemini AI integration
│   │       └── document_service.py  # pdai document access
│   ├── data/
│   │   ├── arguments/           # XML argument files
│   │   └── exports/             # Exported files
│   ├── requirements.txt
│   └── .env
├── frontend/
│   ├── src/
│   │   ├── App.tsx
│   │   ├── components/
│   │   │   ├── Dashboard.tsx
│   │   │   ├── FileManager.tsx
│   │   │   ├── ArgumentEditor.tsx
│   │   │   ├── Settings.tsx
│   │   │   ├── graph/           # React Flow components
│   │   │   │   ├── ArgumentGraph.tsx
│   │   │   │   ├── PropositionNode.tsx
│   │   │   │   └── PremiseEdge.tsx
│   │   │   └── documents/       # pdai integration
│   │   │       ├── DocumentSelector.tsx
│   │   │       └── SourcePanel.tsx
│   │   ├── services/api.ts
│   │   ├── store.ts
│   │   └── types.ts
│   └── package.json
├── config.json                  # Path configuration
└── README.md

API Endpoints

Files

• GET /api/files/ - List all argument files
• GET /api/files/{filename} - Load a specific file
• POST /api/files/{filename} - Create a new file
• PUT /api/files/{filename} - Update a file
• DELETE /api/files/{filename} - Delete a file
• POST /api/files/rename - Rename a file

Arguments

• POST /api/arguments/validate - Validate argument structure
• POST /api/arguments/export - Export to XML
• POST /api/arguments/analyze - AI analysis
• POST /api/arguments/ai/validate - AI validation
• POST /api/arguments/ai/suggest - AI suggestions
• POST /api/arguments/ai/extract - Extract from text

Documents (pdai)

• GET /api/documents/ - List available documents
• GET /api/documents/status - Get pdai availability status
• GET /api/documents/{id} - Get document details
• GET /api/documents/{id}/pages - Load page content
• POST /api/documents/{id}/extract-argument - Extract argument from pages

Configuration

• GET /api/config/ - Get full configuration
• PUT /api/config/paths - Update path configuration
• PUT /api/config/pdai-path - Set pdai path
• POST /api/config/pdai-path/auto-detect - Auto-detect pdai
• GET /api/config/health - Health check

XML Format

Arguments are stored in XML format following the DTD schema:

<?xml version="1.0" encoding="UTF-8"?>
<argument title="Argument Title" source="Source Reference" 
          document_id="E57" page_range="1-5">
  <meta created="2026-02-02" model="gemini-3.8-flash" version="1.0"/>
  <proposition id="P1" label="First Premise" type="premise">
    <text>The proposition text</text>
    <premises/>
    <rule>assumption</rule>
    <comment>Optional comment</comment>
  </proposition>
  <proposition id="C1" label="Conclusion" type="conclusion" source_page="3">
    <text>The conclusion</text>
    <premises>
      <ref id="P1"/>
    </premises>
    <rule>modus ponens</rule>
    <comment>Derived from P1</comment>
  </proposition>
</argument>

AI Features

The application uses Google Gemini (gemini-3.8-flash) for:

• Analyze: Comprehensive argument analysis including strengths, weaknesses, and structure
• Validate: Check for logical issues, fallacies, and gaps
• Suggest: Get improvement suggestions and proposed additions
• Extract: Extract argument structure from unstructured text or pdai documents

License

MIT License