Skip to content

README.md

Latest commit

 

History

History
225 lines (162 loc) · 7.05 KB

README.md

File metadata and controls

225 lines (162 loc) · 7.05 KB

Trajectory Analysis CLI

This CLI tool analyzes AI agent trajectories against policy guards, validating agent interactions against policy constraints and generating detailed analysis reports.

Overview

The analyzer processes trajectory files containing AI agent interactions and validates them against policy constraints defined in guard files. It generates CSV reports with detailed analysis results including policy violations, guard evaluations, and execution metrics.

Usage

Basic Command

python -m policy_violation.analysis <trajectory_file> [OPTIONS]

Command Arguments

Argument Required Description
TRAJECTORY_FILE Yes Path to the canonical JSON trajectory file to analyze

Command Options

Option Short Required Description
--guards-dir -g Yes Path to guards directory containing policy definitions
--results-dir -r Yes Output directory for analysis results
--wrapper-file -w Yes Path to wrapper Python file (e.g., generated/api_wrapper.py)
--limit -l No Limit number of simulations to process (default: 0 = process all)
--simulation-id -s No Process only the simulation with this specific ID
--verbose -v No Enable verbose debug logging

Examples

Example 1: Basic Analysis

Analyze a trajectory file with all required options:

python -m policy_violation.analysis \
    data/trajectory.json \
    --guards-dir generated \
    --results-dir results \
    --wrapper-file generated/api_wrapper.py

Example 2: Using Short Options

Use short option flags:

python -m policy_violation.analysis \
    data/trajectory.json \
    -g generated \
    -r results \
    -w generated/api_wrapper.py

Example 3: Limit Number of Simulations

Process only the first 10 simulations:

python -m policy_violation.analysis \
    data/trajectory.json \
    --guards-dir generated \
    --results-dir results \
    --wrapper-file generated/api_wrapper.py \
    --limit 10

Example 4: Analyze Specific Simulation

Process only a specific simulation by ID:

python -m policy_violation.analysis \
    data/trajectory.json \
    --guards-dir generated \
    --results-dir results \
    --wrapper-file generated/api_wrapper.py \
    --simulation-id "2b5333f7-4e7a-4694-9d6e-45bd27909cdf"

Example 5: With Verbose Logging

Enable detailed debug logging:

python -m policy_violation.analysis \
    data/trajectory.json \
    --guards-dir generated \
    --results-dir results \
    --wrapper-file generated/api_wrapper.py \
    --verbose

Example 6: Combined Options

Combine multiple options:

python -m policy_violation.analysis \
    data/trajectory.json \
    -g generated \
    -r results \
    -w generated/api_wrapper.py \
    -l 5 \
    -v

Prerequisites

Before running the analyzer, you must have:

  1. Generated Guards: Use the guards CLI to generate policy guards

  2. Generated Wrapper: Use the wrappers CLI to generate the wrapper file

  3. Trajectory File: A canonical JSON trajectory file containing agent interactions

    • Must be in the canonical JSON format

  4. LLM Configuration (Required for Dynamic LLM Wrapper): Set environment variables in .env file

    • MODEL_NAME: LLM model name (e.g., gpt-4o, claude-3-5-sonnet-20241022)
    • LLM_PROVIDER: Provider name (e.g., openai, anthropic, azure)
    • LLM_API_KEY: API key for the LLM provider
    • LLM_API_BASE: API base URL (optional, provider-specific)
    • See .env.example for configuration examples

Wrapper Types

The analyzer supports different wrapper implementations for handling API calls during trajectory analysis:

1. History-Based Wrapper (Default)

The standard wrapper searches the conversation history for exact matches of tool calls and their results. If a tool call with matching arguments is found in the history, it returns the cached result.

Use case: Fast analysis when all tool calls in the trajectory have exact matches in history.

2. Dynamic LLM Wrapper

The DynamicLLMHistoryAPIWrapper uses an LLM to intelligently answer tool calls by analyzing the conversation history. When a tool call is not found in history, it:

  1. Searches for exact matches in conversation history first
  2. If no exact match is found, uses an LLM to:
    • Analyze previous tool call results
    • Extract relevant information from scattered data across multiple tool calls
    • Construct partial or complete responses based on available evidence
    • Return null only when no relevant information exists in history

Use case: More flexible analysis when tool calls may have variations or when information needs to be synthesized from multiple prior tool calls.

How to use:

  1. Configure LLM settings in .env file (see Prerequisites section)
  2. Pass the path to DynamicLLMHistoryAPIWrapper as the wrapper file: 
    --wrapper-file src/policy_violation/analysis/dynamic_llm_api_wrapper.py

Example command:

python -m policy_violation.analysis \
    data/trajectory.json \
    --guards-dir generated \
    --results-dir results \
    --wrapper-file src/policy_violation/analysis/dynamic_llm_api_wrapper.py

Note: The DynamicLLMHistoryAPIWrapper class automatically receives LLM configuration from environment variables and uses the domain information from the guards directory.

Benefits:

  • Handles variations in tool call arguments
  • Synthesizes information from multiple tool calls
  • More robust to incomplete or partial data in history
  • Reduces false positives from missing exact matches

Trade-offs:

  • Slower than history-based wrapper (requires LLM calls)
  • Requires LLM API access and configuration
  • May incur API costs

Output

The tool generates:

  • CSV file with detailed analysis results in the specified results directory
  • Filename format: {trajectory_file_name}_results.csv
  • Contains columns for:
    • Simulation metadata
    • Guard evaluation results
    • Policy violations
    • Execution metrics
    • Error information

Example output:

results/
└── traj_claude-4-sonnet_results.csv

Troubleshooting

Error: Guards directory not found

Ensure you've generated guards first using the guards CLI.

Error: Wrapper file not found

Ensure you've generated the wrapper file using the wrappers CLI.

Error: Invalid trajectory file format

Verify that your trajectory file is in the canonical JSON format. The file must contain valid simulation data with tool calls and responses.

Error: No simulations found

Check that your trajectory file contains simulation data. Use --verbose to see detailed processing information.

See Also