Skip to content

getting-started.md

Latest commit

 

History

History
117 lines (89 loc) · 3.62 KB

getting-started.md

File metadata and controls

117 lines (89 loc) · 3.62 KB

Getting Started with PersonaForge

PersonaForge is a reliability testing platform designed specifically for voice-based conversational AI agents. It tests agents against goal-driven synthetic customer personas, ensuring that they do not hallucinate, fail to escalate, or violate business policies in production.

Prerequisites

Before installing PersonaForge, ensure you have the following:

  • Python: Version 3.10 or higher.
  • Node.js: Version 18 or higher (only required for running the Dashboard/Studio).
  • Database: SQLite (built-in) or PostgreSQL.
  • API Accounts:
    • ElevenLabs: Access to Conversational AI agents.
    • Gemini (Google AI Studio): For persona decisions and Judge evaluations.

Installation

1. Clone the Codebase

git clone https://github.com/yourusername/personaforge.git
cd personaforge

2. Set Up a Virtual Environment

It is highly recommended to isolate dependencies inside a virtual environment:

# Create virtual environment
python3 -m venv venv

# Activate virtual environment (macOS/Linux)
source venv/bin/activate

# Activate virtual environment (Windows)
# venv\Scripts\activate

3. Install Python Dependencies

pip install -r requirements.txt

Environment Configuration

Create a .env file in the root of your project:

# ElevenLabs API Access
ELEVENLABS_API_KEY=your_elevenlabs_api_key

# Google Gemini API Access (used for the Persona & Judge Engines)
GOOGLE_API_KEY=your_gemini_api_key

# Optional: SQLite Database Path (defaults to personaforge.db in root)
DATABASE_URL=sqlite+aiosqlite:///personaforge.db

# Optional: Redis URL (required for async task queue worker mode)
REDIS_URL=redis://localhost:6379

Project Initialization

Scaffold the required directories and initial configuration templates by executing:

# Ensure Python is looking in the root directory for imports
export PYTHONPATH=$PYTHONPATH:.

# Initialize project layout
python3 -m personaforge.backend.app.cli.main init

This command creates the following file structure in your directory:

  • personas/: Definitions for customer personas (e.g. personas/angry_customer.yaml).
  • scenarios/: Test scenarios pairing personas with goals (e.g. scenarios/telecom_refund.yaml).
  • policies/: Compliance and business rules (e.g. policies/refund.md).
  • tests/: Directory for automated tests.
  • reports/: JSON summaries generated by runs.
  • artifacts/: Saved raw conversation history, LLM evaluations, and reports.
  • personaforge.yaml: Main configuration settings.

Running Your First Test Run

To execute a test run, you can either run a Dry-Run Simulation (mocked voices and providers to test configuration without API charges) or a Real Run (connecting directly to ElevenLabs over WebSockets).

Dry-Run Simulation (Recommended to verify setup)

PYTHONPATH=. python3 -m personaforge.backend.app.cli.main run scenarios/telecom_refund.yaml --count 2 --dry-run

Real Live Run

  1. Open personaforge.yaml and set your ElevenLabs agent ID: 
    agent:
  provider: elevenlabs
  agent_id: your_actual_agent_id_here
  2. Start the test: 
    PYTHONPATH=. python3 -m personaforge.backend.app.cli.main run scenarios/telecom_refund.yaml --count 1

Reviewing the Results

Once the run completes, check the summary via the CLI:

PYTHONPATH=. python3 -m personaforge.backend.app.cli.main report latest

You can also print the turn-by-turn log of a specific conversation (copy the UUID from your report output):

PYTHONPATH=. python3 -m personaforge.backend.app.cli.main replay <CONVERSATION_ID>