raps-twin

Що таке raps-twin?

raps-twin, також відомий як EDDT (Engineering Department Digital Twin), — це прозорий фреймворк симуляції з можливістю налагодження для моделювання інженерних робочих процесів. Побудований на Mesa для агентного моделювання та SimPy для моделювання конкуренції за ресурси, він дозволяє симулювати та оптимізувати операції інженерного відділу.

Навіщо raps-twin?

Випадки використання

• Планування потужностей — Симулюйте різні склади команд для оптимізації рішень щодо найму
• Аналіз вузьких місць — Виявляйте перевантажених інженерів та черги завдань до того, як вони стануть проблемою
• What-If аналіз — Проводьте експерименти, щоб зрозуміти вплив змін
• Оптимізація процесів — Знаходьте оптимальний баланс навантаження та ресурсів

Ключові можливості

• Порівняння сценаріїв — Порівнюйте 2-5 сценаріїв симуляції пліч-о-пліч
• Аналіз вузьких місць — Виявлення перевантажених інженерів та черг завдань
• What-If аналіз — Проведення експериментів за допомогою запитів природною мовою
• Дашборд у реальному часі — Візуалізація через живий Jupyter-віджет
• Інтеграція з LLM — Опціональне прийняття рішень на основі ШІ

Швидкий старт

Встановлення

pip install eddt

Або з вихідного коду:

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

Базове використання

# 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'])

Порівняння сценаріїв

Порівнюйте кілька сценаріїв для розуміння компромісів:

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/

Аналіз вузьких місць

Виявляйте перевантажених інженерів та черги завдань:

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 аналіз

Проводьте експерименти з простим синтаксисом модифікацій:

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)

Підтримувані модифікації:

• +1 senior_designer — Додати членів команди
• -1 junior_designer — Видалити членів команди
• +50% part_design — Збільшити обсяг завдань
• -50% review — Зменшити обсяг завдань
• +10 review tasks — Додати конкретні завдання
• double the review tasks — Природна мова

Ролі агентів

Типи завдань

Приклади конфігурації

Конфігурація на Python

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

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

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

За замовчуванням EDDT використовує прийняття рішень на основі правил для швидкості. Щоб увімкнути LLM:

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

Потрібен Ollama, що працює локально:

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

Вихідні дані

Результати включають:

• Підсумок: Виконані завдання, відсоток завершення
• Метрики агентів: Утилізація, кількість виконаних завдань на агента
• Метрики моделі: Часові ряди утилізації, прогрес завдань
• Вузькі місця: Виявлені вузькі місця робочих процесів
• Порівняння: Аналіз сценаріїв пліч-о-пліч
• Рекомендації: Практичні пропозиції щодо покращення