# PATAS Demo Guide

This guide walks you through running a complete PATAS demo, from setup to viewing results.

---

## Prerequisites

- Python 3.9 or higher
- Poetry installed ([installation guide](https://python-poetry.org/docs/#installation))
- LLM provider API key (optional, for LLM-powered pattern mining, e.g., OpenAI)

---

## Step 1: Installation

```bash
# Clone the repository (or use your local copy)
git clone <repository-url>
cd PATAS

# Install dependencies
poetry install

# Copy environment template
cp .env.example .env
```

### Optional: Configure LLM Provider API Key

If you want to use LLM-powered pattern mining, add your LLM provider API key to `.env`:

```bash
# For OpenAI (default)
OPENAI_API_KEY=your-key-here
# or
PATAS_OPENAI_API_KEY=your-key-here
```

**Note**: PATAS works without LLM, but LLM enhances pattern discovery quality.

---

## Step 2: Start the API Server

```bash
# Option 1: Using uvicorn directly
poetry run uvicorn app.api.main:app --host 0.0.0.0 --port 8000

# Option 2: Using the CLI entry point
poetry run patas-api

# Option 3: Using the demo script (it will check if server is running)
```

The API will be available at `http://localhost:8000`

**Verify it's running:**
```bash
curl http://localhost:8000/api/v1/health
```

You should see:
```json
{"status": "ok"}
```

---

## Step 3: Run the Demo

### Option A: Using the Demo Script (Recommended)

```bash
./docs/run_demo.sh
```

The script will:
1. Check if the API is running
2. Send the demo dataset to `/api/v1/analyze`
3. Display results in the terminal
4. Save results to `docs/demo_results.json`

### Option B: Manual Request

```bash
curl -X POST http://localhost:8000/api/v1/analyze \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "messages": $(cat docs/demo_messages.json),
  "run_mining": true,
  "run_evaluation": true,
  "export_backend": "sql"
}
EOF
```

### Option C: Using Python

```python
import requests
import json

# Load demo messages
with open('docs/demo_messages.json') as f:
    messages = json.load(f)

# Send request
response = requests.post(
    'http://localhost:8000/api/v1/analyze',
    json={
        'messages': messages,
        'run_mining': True,
        'run_evaluation': True,
        'export_backend': 'sql'
    }
)

# Print results
print(json.dumps(response.json(), indent=2))
```

---

## Step 4: Understanding the Results

The response includes several key sections:

### Patterns Discovered

```json
{
  "patterns": [
    {
      "id": 1,
      "type": "URL",
      "description": "Suspicious URL pattern: http://spam-shop.com"
    }
  ]
}
```

These are spam patterns discovered in your messages.

### Rules Generated

```json
{
  "rules": [
    {
      "id": 1,
      "pattern_id": 1,
      "status": "candidate",
      "sql_expression": "SELECT id FROM messages WHERE text LIKE '%spam-shop.com%'",
      "precision": 0.95,
      "coverage": 0.15
    }
  ]
}
```

These are blocking rules generated from the patterns.

### Export (SQL Rules)

```json
{
  "export": "SELECT id FROM messages WHERE text LIKE '%spam-shop.com%';\n..."
}
```

Ready-to-deploy SQL rules (if `export_backend: "sql"` was requested).

### Metadata

```json
{
  "meta": {
    "ingested_count": 10,
    "patterns_created": 3,
    "rules_created": 3,
    "evaluation_count": 3,
    "timings": {
      "ingest_seconds": 0.123,
      "mining_seconds": 2.456,
      "evaluation_seconds": 0.789,
      "total_seconds": 3.368
    }
  }
}
```

Statistics about the analysis process.

---

## Step 5: Customizing the Demo

### Add Your Own Messages

Edit `docs/demo_messages.json`:

```json
[
  {
    "id": "custom_001",
    "text": "Your spam message here",
    "is_spam": true,
    "meta": {"lang": "en"}
  },
  {
    "id": "custom_002",
    "text": "Your legitimate message here",
    "is_spam": false,
    "meta": {"lang": "en"}
  }
]
```

### Adjust Analysis Options

```json
{
  "messages": [...],
  "run_mining": true,        // Enable pattern mining
  "run_evaluation": true,    // Enable rule evaluation
  "export_backend": "sql"    // Export format: "sql" or "rol"
}
```

### Try Different Export Formats

```json
{
  "export_backend": "rol"  // ROL (Rule Object Language) format
}
```

---

## Troubleshooting

### API Server Not Running

**Error**: `API server is not running`

**Solution**: Start the API server first (see Step 2)

### Database Error

**Error**: Database connection issues

**Solution**: PATAS uses SQLite by default. Ensure `data/` directory exists and is writable:
```bash
mkdir -p data
```

### LLM Errors

**Error**: LLM provider API errors

**Solution**: 
- Check your API key in `.env`
- Or disable LLM by setting `run_mining: false` (pattern mining will use rule-based extraction only)

### Port Already in Use

**Error**: `Address already in use`

**Solution**: Use a different port:
```bash
poetry run uvicorn app.api.main:app --host 0.0.0.0 --port 8001
```

Then update the demo script or use `API_URL=http://localhost:8001 ./docs/run_demo.sh`

---

## Next Steps

- [API Quickstart](API_QUICKSTART.md) - Learn how to integrate PATAS into your system
- [Use Cases](USE_CASES.md) - See real-world scenarios
- [Overview](OVERVIEW_PUBLIC.md) - Understand how PATAS works

---

## Demo Dataset

The demo includes 10 sample messages:
- 7 spam messages (various patterns: URLs, phone numbers, keywords)
- 3 legitimate messages

This small dataset demonstrates PATAS capabilities. For production use, analyze larger datasets (hundreds or thousands of messages) for better pattern discovery.

---

**Tip**: Save the results JSON and explore the discovered patterns and generated rules. This gives you a sense of what PATAS can do with your own data.