# Quick Start Guide

This guide will help you get AuraGen up and running in just a few minutes.

## Prerequisites

Before starting, ensure you have:

- Python 3.8+ installed

- AuraGen installed (see Installation)

- At least one API key (OpenAI or DeepInfra recommended)

## Step 1: Configure API Keys

AuraGen supports multiple API providers. Start by configuring at least one:

    python config/configure_api_keys.py

This interactive tool will guide you through:

1. Selecting API Key Type: Choose from existing types or add custom ones

2. Entering API Key: Securely input your API key (hidden input)

3. Choosing Storage: Save to project `.env` file or system environment

Note

We recommend using the project `.env` file for easy project-specific configuration.

Example session:

    ┌────────────────────────────────────────┐
    │              Setup              │
    └────────────────────────────────────────┘

    Current API Key Values (masked)
    ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
    ┃ Key Type         ┃ Env Var          ┃ Value            ┃
    ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
    │ openai_api_key   │ OPENAI_API_KEY   │ <not set>        │
    │ deepinfra_api_key│ DEEPINFRA_API_KEY│ <not set>        │
    └────────────────────┴──────────────────┴──────────────────┘

## Step 2: Basic Configuration

Configure the generation settings in `config/generation.yaml`:

    # Basic configuration
    generation:
      batch_size: 10
      externalAPI_generation: false  # Use OpenAI (true for external APIs)

    # OpenAI settings
    openai:
      api_key_type: "openai_api_key"
      model: "gpt-4o"
      temperature: 1.0
      max_tokens: 2048

Important

The `externalAPI_generation` setting determines which API service to use:

- `false`: Use OpenAI API

- `true`: Use external API (DeepInfra, etc.)

## Step 3: Generate Your First Dataset

Run the complete generation and injection pipeline:

    python generate_and_inject.py

This command will:

1. Load Scenarios: Read all scenarios from `config/AgentSafetyBench/`

2. Generate Harmless Trajectories: Create clean agent interactions

3. Apply Risk Injection: Introduce realistic risks while maintaining plausibility

4. Save Results: Output files to `generated_records/`

Expected output:

    🚀 Starting AuraGen Pipeline...

    📊 Loaded 150 scenarios
    ⚙️  Using OpenAI API (gpt-4o)

    🔄 Generating harmless trajectories...
    ✅ Generated 1,500 harmless records

    💉 Injecting risks...
    ✅ Created 1,500 risky trajectories

    💾 Saved to generated_records/

    🎉 Pipeline completed successfully!

## Step 4: Examine the Results

The generated files will be saved in the `generated_records/` directory:

    generated_records/
    ├── all_scenarios_openai_20241215_143022.json      # Harmless trajectories
    └── all_injected_openai_20241215_143022.json       # Risk-injected trajectories

Each record contains:

    {
      "scenario_name": "email_assistant",
      "user_request": "Help me write a professional email",
      "agent_action": "draft_email",
      "agent_response": "I'll help you create a professional email...",
      "metadata": {
        "timestamp": 1703172602,
        "api_model": "gpt-4o",
        "risk_type": "privacy_breach",
        "scenario_metadata": {
          "industry": "healthcare",
          "urgency_level": "medium"
        }
      }
    }

## Understanding the Data Structure

### Harmless Trajectories

These represent clean, appropriate agent behavior:

- user_request: The input from the user

- agent_action: The action the agent takes

- agent_response: The agent’s response to the user

- metadata: Contextual information and constraints

### Risk-Injected Trajectories

These contain introduced risks while maintaining plausibility:

- Same structure as harmless trajectories

- Additional `risk_type` in metadata

- Modified `agent_action` or `agent_response` with realistic risks

### Common Risk Types

- `privacy_breach`: Unauthorized access to personal information

- `misinformation`: Spreading false or misleading information

- `bias_amplification`: Reinforcing harmful stereotypes

- `unauthorized_action`: Actions beyond the agent’s scope

- `availability_disruption`: Service interruptions or failures

## Next Steps

Now that you have AuraGen running, explore these advanced features:

- Configuration - Detailed configuration options

- Scenarios - Understanding and customizing scenarios

- Risk Injection - Advanced risk injection techniques

- advanced/custom_scenarios - Creating your own scenarios

## Common Issues

“Environment variable not set” Error

Make sure you’ve configured your API keys:

    python config/configure_api_keys.py

Empty or Failed Generation

Check your API key validity and internet connection. Also verify the model name in your configuration.

Permission Errors

Ensure you have write permissions in the project directory:

    chmod -R 755 /path/to/agentic-guardian

## Need Help?

- Check the advanced/troubleshooting guide

- Review the full Configuration documentation

- Visit our GitHub repository for issues and discussions