Agent Interaction Sandbox (Starter)

A minimal, extensible sandbox to simulate and evaluate agent-to-agent interactions (digital-only).
Focus: standardized scenarios, deterministic runs, JSONL logs, and simple metrics.

Features

• Pluggable LLM backends (LLMBackend): start with a ScriptedBackend, drop-in a real LLM later.
• Data-driven Scenarios (negotiation, info asymmetry).
• Reproducible runs with seeds, JSONL transcripts (runs.jsonl).
• Simple Evaluator metrics (success, efficiency, fairness, words).
• CLI with typer: run scenarios and report results.

Quick Start

# (optional) create and activate venv
python -m venv .venv && source .venv/bin/activate  # on Windows: .venv\Scripts\activate

pip install -r requirements.txt

# Run a single demo episode (scripted backend)
python scripts/run_demo.py

# Run via CLI (N episodes)
python -m agent_sandbox.cli run --scenario resource_split --episodes 5 --seed 42

# Summarize a runs file
python -m agent_sandbox.cli report --path runs.jsonl

Repo Layout

agent_sandbox/
  __init__.py
  core.py               # Core types (Agent, Scenario, Environment, Evaluator, Runner, Logger)
  cli.py                # Typer-based CLI for run/report
  backends/
    __init__.py
    base.py             # LLMBackend interface
    scripted.py         # Simple baseline (no external calls)
    openai_backend.py   # (Optional) real LLM backend stub
  scenarios/
    __init__.py
    negotiation.py      # Resource split scenario
    info_asymmetry.py   # Hidden-value scenario
  evals/
    __init__.py
    metrics.py          # Shared metrics helpers
scripts/
  run_demo.py           # Example wiring
tests/
  test_sandbox_smoke.py

Roadmap

• Add deception detectors and negotiation quality metrics.
• Batch runner + HTML reports / leaderboard.
• Scenario registry + versioning.