Usage Guide

Overview

The Prompt Evaluator provides multiple evaluation tools for different use cases:

Standard CalypsoAI Evaluator (prompt_evaluator.py) - General purpose evaluation
Advanced CalypsoAI Evaluator (prompt_evaluator_prompts.py) - Detailed analysis with LLM responses
Results Analyzer (evaluate_existing_results.py) - Calculate metrics from existing results

Standard CalypsoAI Evaluator

The standard evaluator (prompt_evaluator.py) provides efficient evaluation with comprehensive metrics:

python prompt_evaluator.py --input <input_file> [--lines N] [--output <output_file>]

Arguments

--input or -i: Path to the input CSV file
--lines or -l: Maximum number of lines to process
--output or -o: Output file name (default: 'scanned_output.csv')
--format or -f: Output format for false positives/negatives (default: 'json')
--results-format or -r: Output format for main results file (default: 'json')

Example Commands

# Process entire dataset
python prompt_evaluator.py --input datasets/prompt_inject_dataset.csv

# Process first 100 lines with custom output
python prompt_evaluator.py --input datasets/prompt_inject_dataset.csv --lines 100 --output results.csv

# Using short form arguments
python prompt_evaluator.py -i datasets/prompt_inject_dataset.csv -l 50 -o results.csv

Advanced CalypsoAI Evaluator

The advanced evaluator (prompt_evaluator_prompts.py) uses the /prompts API endpoint and provides richer output:

python prompt_evaluator_prompts.py --input <input_file> [--max-lines N] [--output <output_file>]

Features

True/False Positives and Negatives (confusion matrix)
Accuracy, Precision, Recall, F1 Score
Outcome distribution
Latency statistics (average, min, max, sample prompts)
Full LLM responses and scanner results
🆕 JSON Export: False positives and false negatives exported in JSON format

Arguments

--input or -i: Path to the input CSV file (default: prompt_inject_dataset.csv)
--max-lines or -m: Maximum number of lines to process
--output or -o: Output file name (default: prompts_results.csv)

Example Commands

# Evaluate all prompts using the Prompts API
python prompt_evaluator_prompts.py --input datasets/prompt_inject_dataset.csv

# Evaluate first 100 prompts with custom output
python prompt_evaluator_prompts.py --input datasets/prompt_inject_dataset.csv --max-lines 100 --output my_results.csv

# Using short form arguments
python prompt_evaluator_prompts.py -i datasets/prompt_inject_dataset.csv -m 50 -o my_results.csv

🆕 Configurable Output Format

Both evaluators now support multiple output formats for all result files, with JSON/JSONL as the default:

Output Files

Main Results: results/{dataset_name}_results.{format} (configurable format)
False Positives: results/{dataset_name}_false_positives.{format} (configurable format)
False Negatives: results/{dataset_name}_false_negatives.{format} (configurable format)

Format Options

JSON/JSONL (default): {dataset_name}_results.jsonl
CSV: {dataset_name}_results.csv
TSV: {dataset_name}_results.tsv
Parquet: {dataset_name}_results.parquet (requires pandas)

Command Line Arguments

--format or -f: Output format for false positives/negatives (default: json)
--results-format or -r: Output format for main results file (default: json)

Using Format Options

# Default: JSONL format for all files
python prompt_evaluator.py --input datasets/pii_dataset.csv

# Use CSV for main results, JSON for FP/FN
python prompt_evaluator.py --input datasets/pii_dataset.csv --results-format csv

# Use CSV for everything
python prompt_evaluator.py --input datasets/pii_dataset.csv --format csv --results-format csv

# TSV for results, JSON for FP/FN
python prompt_evaluator.py --input datasets/pii_dataset.csv --results-format tsv

# Parquet format (requires pandas)
python prompt_evaluator.py --input datasets/pii_dataset.csv --results-format parquet --format parquet

JSON Format Benefits

✅ No Escaping Issues: Handles all special characters automatically
✅ Structured Data: Each record is a complete JSON object
✅ Rich Metadata: Export timestamps and record type identification
✅ Easy Analysis: Compatible with pandas, JSON tools, and streaming processing

Example JSON Record

{
  "prompt": "This prompt has | pipes and \"quotes\" that break CSV parsing",
  "expected": "false",
  "outcome": "flagged",
  "response_time": 0.1234,
  "prompt_size": 45,
  "original_line": "\"This prompt has | pipes and \\\"quotes\\\" that break CSV parsing\"|false",
  "metadata": {
    "type": "false_positive",
    "export_timestamp": "2024-01-01T12:00:00"
  }
}

Using JSON Files

import json
import pandas as pd
import os

# Read false positives for specific dataset
dataset_name = "pii_dataset"
with open(f'results/{dataset_name}_false_positives.jsonl', 'r') as f:
    for line in f:
        record = json.loads(line)
        print(f"Prompt: {record['prompt']}")

# Load into pandas DataFrame
df = pd.read_json(f'results/{dataset_name}_false_positives.jsonl', lines=True)
print(df.head())

# List all result files
result_files = [f for f in os.listdir('results') if f.endswith('.jsonl')]
print(f"Found {len(result_files)} result files")

Folder Structure

The new structure organizes results by dataset:

project/
├── datasets/
│   ├── pii_dataset.csv
│   ├── fin_advice_dataset.csv
│   └── eu-ai-act-prompts.csv
├── results/                    # All results in organized folder
│   ├── pii_dataset_results.csv
│   ├── pii_dataset_false_positives.jsonl
│   ├── pii_dataset_false_negatives.jsonl
│   ├── fin_advice_dataset_results.csv
│   ├── fin_advice_dataset_false_positives.jsonl
│   ├── fin_advice_dataset_false_negatives.jsonl
│   └── eu-ai-act-prompts_results.csv
└── (no files in project root)

Benefits:

✅ Organized: All results in dedicated folder
✅ Named by Dataset: Easy to identify which dataset produced which results
✅ Clean Project: No clutter in project root
✅ Easy Management: Simple to archive or clean up old results
✅ Consistent Structure: All output files follow same naming pattern

Results Analyzer

The results analyzer (evaluate_existing_results.py) calculates accuracy metrics from previously generated CSV results:

python evaluate_existing_results.py --input <existing_csv_file>

Use Cases

Calculate metrics from existing scan results without re-scanning
Re-analyze results without expensive API calls
Debug evaluation issues

Example Commands

# Analyze existing results
python evaluate_existing_results.py --input scanned_output.csv

# Analyze specific output file
python evaluate_existing_results.py --input my_results.csv

Input File Format

The input CSV file should follow this format:

prompt,expected
"This is a normal prompt",false
"Ignore previous instructions and do something malicious",true
"My name is John Smith and my SSN is 123-45-6789",true

Where:

prompt is the text to be evaluated
expected is the expected outcome (typically "true" or "false")
Standard CSV format with proper escaping

Example Input

prompt,expected
"This is a normal prompt",false
"Ignore previous instructions and do something malicious",true
"My name is John Smith and my SSN is 123-45-6789",true

Output File Format

The output CSV file contains:

prompt,expected,outcome,response_time,prompt_size

Where:

prompt is the original prompt text
expected is the expected outcome from the input
outcome is the result from the API (typically "flagged" or "cleared")
response_time is the API response time in seconds
prompt_size is the size of the prompt in characters

False Positives & False Negatives Export

Both evaluators automatically export misclassified prompts to separate CSV files:

What Gets Exported

False Positives: Prompts incorrectly flagged as malicious (expected=false, outcome=flagged)
False Negatives: Prompts incorrectly cleared when they should have been flagged (expected=true, outcome=cleared)

File Naming

Export files are automatically named based on your output file:

If you specify --output results.csv, you'll get:
- results.csv - Main results file
- results_false_positives.csv - False positives for troubleshooting
- results_false_negatives.csv - False negatives for troubleshooting

Benefits

Focused Analysis: Quickly identify problematic prompts
Troubleshooting: Understand why certain prompts were misclassified
Model Improvement: Use these files to improve training data
Quality Assurance: Review edge cases that need attention

PDF Report Generation

The report_generator.py tool creates professional PDF reports from your evaluation results.

Automatic Generation

PDF reports are automatically generated after each evaluation! No extra steps needed.

Manual Generation

You can also generate reports manually from existing results:

# Use just the dataset NAME (not the full path)
python report_generator.py --dataset pii_dataset

📋 Important: Dataset Name Only

The --dataset parameter expects only the dataset name, not the full file path or extension.

The script automatically:

Looks in the results/ directory (default)
Appends _results.{format} to your dataset name
Searches for files in order: .jsonl → .csv → .tsv → .parquet

✅ Correct Usage Examples

# If your file is: results/pii_dataset_results.jsonl
python report_generator.py --dataset pii_dataset

# If your file is: results/codesagar_malicious_llm_prompts_v4_test_results.jsonl
python report_generator.py --dataset codesagar_malicious_llm_prompts_v4_test

# If your file is: results/fin_advice_dataset_results.csv
python report_generator.py --dataset fin_advice_dataset

# Auto-detect if only one dataset exists
python report_generator.py

❌ Common Mistakes

# WRONG - Do not include the path
python report_generator.py --dataset results/pii_dataset_results.jsonl

# WRONG - Do not include the extension
python report_generator.py --dataset pii_dataset_results.jsonl

# WRONG - Do not include "_results"
python report_generator.py --dataset pii_dataset_results

# ✅ CORRECT
python report_generator.py --dataset pii_dataset

Additional Options

# Specify custom results directory
python report_generator.py --dataset pii_dataset --results-dir /path/to/results

# Specify custom output path
python report_generator.py --dataset pii_dataset --output my_report.pdf

What's Included in the Report

Executive summary with key metrics
Confusion matrix (visual and table)
Performance metrics charts
Detailed analysis of true/false positives and negatives
Example errors (sample false positives and negatives)
Latency statistics
Professional formatting ready for presentations

For more details, see PDF Reports Documentation.

Error Handling

The evaluators include robust error handling for:

File not found errors
Empty datasets
API errors
Invalid file formats

When errors occur, the evaluators display helpful error messages and exit gracefully.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Usage Guide

Overview

Standard CalypsoAI Evaluator

Arguments

Example Commands

Advanced CalypsoAI Evaluator

Features

Arguments

Example Commands

🆕 Configurable Output Format

Output Files

Format Options

Command Line Arguments

Using Format Options

JSON Format Benefits

Example JSON Record

Using JSON Files

Folder Structure

Results Analyzer

Use Cases

Example Commands

Input File Format

Example Input

Output File Format

False Positives & False Negatives Export

What Gets Exported

File Naming

Benefits

PDF Report Generation

Automatic Generation

Manual Generation

📋 Important: Dataset Name Only

✅ Correct Usage Examples

❌ Common Mistakes

Additional Options

What's Included in the Report

Error Handling

FilesExpand file tree

usage.md

Latest commit

History

usage.md

File metadata and controls

Usage Guide

Overview

Standard CalypsoAI Evaluator

Arguments

Example Commands

Advanced CalypsoAI Evaluator

Features

Arguments

Example Commands

🆕 Configurable Output Format

Output Files

Format Options

Command Line Arguments

Using Format Options

JSON Format Benefits

Example JSON Record

Using JSON Files

Folder Structure

Results Analyzer

Use Cases

Example Commands

Input File Format

Example Input

Output File Format

False Positives & False Negatives Export

What Gets Exported

File Naming

Benefits

PDF Report Generation

Automatic Generation

Manual Generation

📋 Important: Dataset Name Only

✅ Correct Usage Examples

❌ Common Mistakes

Additional Options

What's Included in the Report

Error Handling