An AI-driven testing and prototyping tool for AI personal assistants. UES provides a simple web-based UI and comprehensive REST API for simulating a variety of input modalities, enabling customizable and reproducible testing of AI agent capabilities.

• Multi-Modal Simulation: Email, SMS, Calendar, Chat, Location, Weather, and more
• REST API: 95 endpoints for complete control over simulation state
• API Access Control: Key-based authentication with fine-grained permissions
• Real-time Updates: WebSocket and Webhook support for event notifications
• Python Client Library: Sync and async support for easy integration
• Web UI: Modern React-based interface for interactive scenario design
• Scenario Management: Save, export, and replay test scenarios
• Time Control: Manual, event-driven, or auto-advance simulation modes
• Agent Testing Harness: Evaluate AI agent performance with customizable criteria
• Multi-Agent Coordination: Hold system for synchronizing concurrent agents

# Using pip
pip install ues

# Using uv (recommended)
uv add ues

# Using the CLI
ues server

# With auto-reload for development
ues server --reload

# Or directly with uvicorn
uvicorn main:app --reload

The API is now available at:

• API Server: http://localhost:8000
• Interactive Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Note: When the server starts, an admin API key is printed to the console. Save this key for authentication.

from ues.client import UESClient

# Connect to the server with your API key
client = UESClient("http://localhost:8000", api_key="ues_your_key_here...")

# Get current simulation time
time_state = client.time.get_state()
print(f"Simulator time: {time_state.current_time}")

# Simulate receiving an email
client.email.receive(
    from_addr="[email protected]",
    to_addr="[email protected]",
    subject="Meeting Tomorrow",
    body="Don't forget our 9am meeting!"
)

# Check email state
email_state = client.email.get_state()
print(f"Inbox has {len(email_state.inbox)} emails")

# Advance time by 1 hour
client.time.advance(hours=1)

• Python 3.12+
• uv (recommended) or pip
• Node.js 18+ (for Web UI)

# Clone the repository
git clone https://github.com/JBoggsy/ues.git
cd ues

# Install Python dependencies
uv sync

# Install Web UI dependencies
cd webapp && npm install

# Terminal 1: Start API server with auto-reload
uv run ues server --reload

# Terminal 2: Start Web UI
cd webapp && npm run dev

Access:

• API: http://localhost:8000/docs
• Web UI: http://localhost:5173

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/api/modalities/test_email_routes.py -v

# Run with coverage
uv run pytest --cov=api --cov=models

UES uses an event-sourcing architecture where simulation state progresses through discrete events:

src/ues/                           # Main Python package
    ├── models/                    # Data models (events, modalities, etc.)
    ├── api/                       # FastAPI REST endpoints
    ├── client/                    # Python client library
    └── agent_testing/             # Testing harness for AI agents
tests/                             # Pytest test suite
webapp/                            # React + TypeScript web UI
docs/                              # Documentation
examples/                          # Example agents and scenarios

SimulationEngine (Orchestrator)
    ├── Environment (Current state)
    │   ├── SimulatorTime (Virtual time tracking)
    │   └── ModalityStates (Email, Location, Calendar, etc.)
    ├── EventQueue (Scheduled events)
    └── SimulationLoop (Auto-advance threading)

• Manual Mode: Time advances only via explicit API calls
• Event-Driven Mode: Time skips directly to next scheduled event
• Auto-Advance Mode: Real-time or accelerated time progression

See docs/models/SIMULATION_ENGINE.md for detailed architecture documentation.

All API endpoints require an API key via the X-API-Key header:

curl -H "X-API-Key: ues_your_key_here..." http://localhost:8000/simulation/status

An admin key with full permissions is generated at server startup. See Authentication docs for key management and permissions.

GET  /simulator/time          # Get current time state
POST /simulator/time/advance  # Advance time by duration
POST /simulator/time/set      # Jump to specific time
POST /simulator/time/pause    # Freeze time
POST /simulator/time/resume   # Resume time

GET  /events                  # List events with filters
POST /events                  # Schedule new event
POST /events/immediate        # Execute event immediately

GET  /{modality}/state        # Get current state
POST /{modality}/query        # Query with filters
POST /{modality}/*            # Modality-specific actions

Full API documentation: http://localhost:8000/docs (when server is running)

UES is designed as an agent-interactable simulation platform:

┌─────────────────────────────────────────────────────────────┐
│                    UES Core (Pure Simulation)               │
│  • Deterministic scenario execution                         │
│  • State management & event scheduling                      │
│  • REST API + WebSocket                                     │
└───────────────────────────┬─────────────────────────────────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
   Simulator-Side      User-Side Agent    Developer
   Agent (external)    (being tested)     (Web UI)
         │                  │                  │
         └──────────────────┴──────────────────┘
                    All use the same REST API

Use Cases:

• Reactive Agents: Monitor for sent emails, generate replies
• Content Generation: Use LLMs to create realistic test data
• Trigger-based Events: Watch for conditions and schedule events
• Character Simulation: Maintain personalities that respond consistently

The examples/agents/ directory contains complete, runnable agent implementations:

Evaluate AI agent performance with the built-in testing framework:

from ues.agent_testing import EvalRunner

runner = EvalRunner(
    scenario_path="./scenario.ues-scenario.json",
    criteria_path="./test_criteria.json",
)
report = await runner.run()
runner.print_report()  # Terminal scoreboard with grades

See docs/agent-testing/AGENT_TESTING.md for complete documentation.

We welcome contributions! See CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes with tests
4. Commit (`git commit -m 'Add amazing feature'`)
5. Push (`git push origin feature/amazing-feature`)
6. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• FastAPI - Modern Python web framework
• Pydantic - Data validation using Python type annotations
• React + Vite - Frontend framework and tooling
• shadcn/ui - Beautiful UI components