DEMO_GUIDE

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)
• LLM provider API key (optional, for LLM-powered pattern mining, e.g., OpenAI)

---

Step 1: Installation

# 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:

# 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

# 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:

curl http://localhost:8000/api/v1/health

You should see:

{"status": "ok"}

---

Step 3: Run the Demo

Option A: Using the Demo Script (Recommended)

./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

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

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

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

These are spam patterns discovered in your messages.

Rules Generated

{
  "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)

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

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

Metadata

{
  "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:

[
  {
    "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

{
  "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

{
  "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:

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:

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 - Learn how to integrate PATAS into your system
• Use Cases - See real-world scenarios
• Overview - 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.