raps-twin

What is raps-twin?

raps-twin, also known as EDDT (Engineering Department Digital Twin), is a transparent, debuggable simulation framework for modeling engineering workflows. Built on Mesa for agent-based modeling and SimPy for resource contention, it enables you to simulate and optimize engineering department operations.

Why raps-twin?

Use Cases

• Capacity Planning - Simulate different team compositions to optimize hiring decisions
• Bottleneck Analysis - Identify overloaded engineers and queue backlogs before they happen
• What-If Analysis - Run experiments to understand the impact of changes
• Process Optimization - Find the optimal balance of workload and resources

Key Features

• Scenario Comparison - Compare 2-5 simulation scenarios side-by-side
• Bottleneck Analysis - Detect overloaded engineers and queue backlogs
• What-If Analysis - Run experiments with natural language queries
• Real-time Dashboard - Live Jupyter widget visualization
• LLM Integration - Optional AI-powered decision making

Quick Start

Installation

pip install eddt

Or from source:

git clone https://github.com/dmytro-yemelianov/raps-twin.git
cd raps-twin
pip install -e ".[dev]"

Basic Usage

# Run simulation
python -m eddt.cli --days 5

# Compare scenarios
python -m eddt.cli --compare baseline.yaml optimized.yaml --days 5

# Bottleneck analysis
python -m eddt.cli --config scenario.yaml --bottleneck --days 10

# What-if experiment
python -m eddt.cli --config baseline.yaml --whatif "+1 senior_designer" --days 5

Python API

from eddt import EngineeringDepartment, run_simulation

# Create model with default config
model = EngineeringDepartment()

# Run for 5 simulated days
results = model.run(days=5)

# Explore results
print(results['summary'])

Scenario Comparison

Compare multiple scenarios to understand trade-offs:

from eddt import compare_scenarios, get_comparison_summary_table

result = compare_scenarios(
    config_paths=["baseline.yaml", "add_designer.yaml", "add_reviewer.yaml"],
    labels=["Baseline", "+1 Designer", "+1 Reviewer"],
    days=10,
)

print(get_comparison_summary_table(result))

CLI:

eddt --compare baseline.yaml add_designer.yaml --labels "Baseline" "Add Designer" --export results/

Bottleneck Analysis

Identify overloaded engineers and queue backlogs:

from eddt import analyze_bottlenecks, format_bottleneck_report, BottleneckConfig

model = EngineeringDepartment(config_path="scenario.yaml")
model.run(days=10)

config = BottleneckConfig(utilization_threshold=0.85)
report = analyze_bottlenecks(model, config=config)

print(format_bottleneck_report(report))

# Access recommendations
for rec in report.recommendations:
    print(f"[{'{'}rec.severity{'}'}] {'{'}rec.recommendation_text{'}'}")

CLI:

eddt --config scenario.yaml --bottleneck --util-threshold 0.85 --days 10

What-If Analysis

Run experiments with simple modification syntax:

from eddt import run_whatif_experiment, ask_whatif

# Structured syntax
experiment = run_whatif_experiment(
    "baseline.yaml",
    modifications=["+1 senior_designer", "-50% review"],
    days=5,
)

# Natural language
experiment = ask_whatif(
    "baseline.yaml",
    "what if we double the review tasks?",
    days=5,
)

print(experiment.comparison.summary)

Supported modifications:

• +1 senior_designer - Add team members
• -1 junior_designer - Remove team members
• +50% part_design - Scale task workload up
• -50% review - Scale task workload down
• +10 review tasks - Add specific tasks
• double the review tasks - Natural language

Agent Roles

Task Types

Configuration Examples

Python Configuration

config = {'{'}
    'simulation': {'{'}
        'start_date': '2025-01-15T08:00:00',
        'tick_minutes': 15,
        'work_hours': {'{'}'start': 8, 'end': 17{'}'},
    {'}'},
    'agents': [
        {'{'}'name': 'Alice', 'role': 'senior_designer', 'count': 1{'}'},
        {'{'}'name': 'Bob', 'role': 'junior_designer', 'count': 3{'}'},
    ],
    'projects': [
        {'{'}
            'name': 'Product Launch',
            'tasks': [
                {'{'}'type': 'part_design', 'count': 10, 'hours': 8{'}'},
                {'{'}'type': 'drawing', 'count': 10, 'hours': 4{'}'},
            ]
        {'}'}
    ],
{'}'}

model = EngineeringDepartment(config=config)
results = model.run(days=10)

YAML Configuration

simulation:
  start_date: '2025-01-15T08:00:00'
  tick_minutes: 15
  work_hours:
    start: 8
    end: 17

agents:
  - name: Alice
    role: senior_designer
    count: 1
  - name: Bob
    role: junior_designer
    count: 3

projects:
  - name: Product Launch
    tasks:
      - type: part_design
        count: 10
        hours: 8
      - type: drawing
        count: 10
        hours: 4

CLI Reference

eddt [OPTIONS]

Options:
  -c, --config PATH       YAML configuration file
  -d, --days INT          Number of days to simulate (default: 5)
  -s, --seed INT          Random seed (default: 42)
  -o, --output PATH       Output file for results (CSV)
  -q, --quiet             Suppress progress output
  --use-llm               Enable LLM decision making

Comparison:
  --compare CONFIG...     Compare 2-5 scenario configs
  --labels LABEL...       Labels for comparison scenarios
  --export DIR            Export comparison results (CSV/JSON)

Bottleneck Analysis:
  --bottleneck            Enable bottleneck analysis
  --util-threshold FLOAT  Utilization threshold (default: 0.85)
  --wait-threshold FLOAT  Wait time threshold in hours (default: 2.0)

What-If Analysis:
  --whatif MOD...         What-if modifications (e.g., "+1 senior_designer")

LLM Integration

By default, EDDT uses rule-based decision making for speed. To enable LLM:

model = EngineeringDepartment(config={'{'}
    'llm': {'{'}
        'use_llm': True,
        'tier1_model': 'qwen2.5:1.5b',
        'tier2_model': 'qwen2.5:7b',
    {'}'}
{'}'})

Requires Ollama running locally:

ollama serve
ollama pull qwen2.5:1.5b
ollama pull qwen2.5:7b

Output

Results include:

• Summary: Tasks completed, completion rate
• Agent metrics: Utilization, tasks completed per agent
• Model metrics: Time series of utilization, task progress
• Bottlenecks: Identified workflow bottlenecks
• Comparison: Side-by-side scenario analysis
• Recommendations: Actionable suggestions for improvement