Configuration

Configure Penelope’s behavior through agent initialization, environment variables, or programmatic configuration.

Agent Configuration

agent_config.py
from rhesis.sdk.models import AnthropicLLM
from rhesis.penelope import PenelopeAgent

agent = PenelopeAgent(
    # Optional: Model (defaults to Vertex AI / gemini-2.0-flash)
    model=AnthropicLLM(),
    # Optional: Conversation depth
    max_turns=20,  # Default is 10
    timeout_seconds=300,  # No timeout by default
    # Observability
    enable_transparency=True,
    verbose=True,
    # Optional: Custom tools
    tools=[],
)

Default Model

Penelope uses Vertex AI with Gemini 2.0 Flash by default. Configure globally:

Environment Variables:

Terminal
export PENELOPE_DEFAULT_MODEL=anthropic
export PENELOPE_DEFAULT_MODEL_NAME=claude-4

Programmatic:

config.py
from rhesis.penelope import PenelopeConfig

PenelopeConfig.set_default_model("anthropic", "claude-4")

# Now all agents use this default
agent = PenelopeAgent()  # Uses anthropic/claude-4

Supported Providers

Penelope works with any Rhesis SDK model:

vertex_ai - Google Vertex AI (Gemini models)
anthropic - Anthropic (Claude models)
openai - OpenAI (GPT models)
openai_compatible - Any OpenAI-compatible API

different_models.py
from rhesis.sdk.models import VertexAILLM, AnthropicLLM, OpenAILLM

# Vertex AI
agent = PenelopeAgent(model=VertexAILLM(model_name="gemini-pro"))

# Anthropic
agent = PenelopeAgent(model=AnthropicLLM(model_name="claude-4"))

# OpenAI
agent = PenelopeAgent(model=OpenAILLM(model_name="gpt-4"))

Conversation Turns

A turn in Penelope is one complete user-assistant exchange: Penelope sends a message to the target and receives a response. Within a single turn, Penelope may also use internal analysis tools (e.g., analyze_response, extract_information), but these do not count as separate turns.

The max_turns parameter controls how many of these exchanges Penelope will complete before stopping. Default: 10.

Setting Max Turns

Environment Variable:

Terminal
export PENELOPE_DEFAULT_MAX_TURNS=20

Programmatic (global default):

config.py
from rhesis.penelope import PenelopeConfig

PenelopeConfig.set_default_max_turns(20)
agent = PenelopeAgent()  # Uses 20

Per Agent (default for all tests run by this agent):

agent.py
agent = PenelopeAgent(max_turns=30)

Per Test (overrides agent default for a specific test):

per_test.py
agent = PenelopeAgent(max_turns=30)  # Agent default

# This test uses 20 turns instead of 30
result = agent.execute_test(
    target=target,
    goal="Focused test",
    max_turns=20,
)

Early Stopping Behavior

Penelope uses a goal achievement metric to evaluate progress after each turn. To ensure the agent exercises the conversation fully, early stopping is only allowed after completing 80% of the configured max_turns:

With max_turns=10, the agent runs at least 8 turns before it can stop early
With max_turns=20, the agent runs at least 16 turns

This prevents premature stopping when the goal appears achieved after only a few exchanges, which would miss important conversational dynamics.

You can override the default 80% threshold with an explicit min_turns parameter:

min_turns.py
result = agent.execute_test(
    target=target,
    goal="Test multi-turn context retention",
    max_turns=10,
    min_turns=5,  # Allow early stopping after 5 turns instead of 8
)

If min_turns exceeds max_turns, it is automatically capped to max_turns.

Choosing Max Turns: Start with 10 for simple tests. Use 15-20 for social engineering or multi-turn attack scenarios. Use 25-30 for comprehensive exploratory testing.

Tool Execution Limit

Separately from max_turns, Penelope enforces a tool execution limit to prevent infinite loops. This counts every tool call (both target interactions and internal analysis tools). It defaults to max_turns * 5 and can be overridden:

tool_limit.py
agent = PenelopeAgent(
    max_turns=20,
    max_tool_executions=200,  # Default would be 20 * 5 = 100
)

Timeout

Set execution timeout to prevent runaway tests:

timeout.py
agent = PenelopeAgent(
    timeout_seconds=300,  # 5 minutes
    max_turns=50,
)

result = agent.execute_test(
    target=target,
    goal="Complex long-running test",
)

# result.status will be 'timeout' if time limit exceeded

Transparency & Verbosity

Control output detail level:

output_control.py
# Full transparency - see all reasoning
agent = PenelopeAgent(
    enable_transparency=True,  # Show reasoning boxes
    verbose=True,  # Print all details
)

# Quiet mode - minimal output
agent = PenelopeAgent(
    enable_transparency=False,
    verbose=False,
)

# Results only - no execution details
agent = PenelopeAgent(verbose=False)

Test-Level Configuration

Override max_turns per test:

test_config.py
result = agent.execute_test(
    target=target,
    goal="Short simple test",
    max_turns=5,  # Override agent default for this test
)

Log Level

Control logging verbosity:

Environment Variable:

Terminal
export PENELOPE_LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL

Programmatic:

logging.py
from rhesis.penelope import PenelopeConfig

PenelopeConfig.set_log_level("DEBUG")  # Shows all logs including external libraries
PenelopeConfig.set_log_level("INFO")  # Standard logging (default)
PenelopeConfig.set_log_level("WARNING")  # Only warnings and errors

Complete Configuration Example

complete_config.py
from rhesis.sdk.models import AnthropicLLM
from rhesis.penelope import PenelopeAgent, PenelopeConfig

# Global defaults
PenelopeConfig.set_default_model("anthropic", "claude-4")
PenelopeConfig.set_default_max_turns(20)
PenelopeConfig.set_log_level("INFO")

# Agent with custom config
agent = PenelopeAgent(
    model=AnthropicLLM(model_name="claude-4"),
    max_turns=30,
    timeout_seconds=600,
    enable_transparency=True,
    verbose=True,
    tools=[],  # Add custom tools here
)

# Execute test
result = agent.execute_test(
    target=target,
    goal="Comprehensive test",
    instructions="Detailed instructions...",
    context={"environment": "staging"},
    max_turns=25,  # Test-specific override
    min_turns=15,  # Early stop allowed after 15 turns
)

Next: Learn how to Extend Penelope with custom tools and architecture details, or explore Examples for practical use cases.