Skip to content

# 46 — Router Orchestrator Design (MicroDAO)

DAARWIZZ Router: інструментальні маршрути, state machine, контекстні флоу, orchestration, паралелізація, безпека, облік вартості

## 1. Purpose & Scope

DAARWIZZ Router — це центральна оркестраційна система, яка:

- розбиває задачі на кроки
- викликає інструменти
- викликає агентів
- викликає LLM Proxy
- обробляє помилки
- зупиняє надмірні флоу
- гарантує дотримання cost / usage / quotas
- забезпечує state machine для multi-step процесів

Це головний механізм автоматизації процесів в DAARION.city.

## 2. High-Level Architecture

    User / Agent / API
            ↓
        Router Orchestrator
            ↓
      Step Engine / State Machine
            ↓
     Tools / Agents / LLM Proxy / Platform Tools

## 3. Input Specification

Уніфікований формат запиту:

    {
      "input": "...",
      "goal": "...",
      "constraints": {...},
      "context": {
        "team_id": "t_444",
        "agent_run_id": "ar_777",
        "confidential": false
      },
      "steps": "auto|structured",
      "tools": ["math","project","llm","greenfood.order"]
    }

## 4. Router Modes

### 4.1 Mode A — AUTO PLAN

Router сам планує кроки (використання лише у продвинутих планах):

    Goal → Plan Generation → Step Execution

### 4.2 Mode B — STRUCTURED

Користувач/агент визначає точні кроки:

    steps: [
      { tool:"project.create", args:{...} },
      { tool:"llm", args:{...} }
    ]

### 4.3 Mode C — HYBRID

AI пропонує план → користувач затверджує → Router виконує.

## 5. State Machine Architecture

Router має власний state machine:

    INIT
    PLAN
    EXECUTE_STEP
    WAIT_TOOL
    WAIT_AGENT
    ERROR_RECOVERY
    DONE

### Переходи:

- INIT → PLAN
- PLAN → EXECUTE_STEP
- EXECUTE_STEP → WAIT_TOOL/WAIT_AGENT
- WAIT_* → EXECUTE_STEP
- EXECUTE_STEP → DONE
- EXECUTE_STEP → ERROR_RECOVERY
- ERROR_RECOVERY → EXECUTE_STEP | DONE

## 6. Step Engine

Кожен крок має структуру:

    {
      "id": "step_1",
      "type": "tool|agent|llm",
      "tool": "project.create",
      "args": { ... }
    }

### Типи кроків:

- LLM — виклик LLM Proxy
- Tool — виклик інструменту
- Agent — запуск іншого агента (subagent pattern)
- Platform — інтеграція GREENFOOD/EnergyUnion
- Branch — умовні гілки (if/else)
- Parallel — паралельні підкроки
- Loop — повторення (обмежений)

## 7. Safety Limits

Обмеження, які Router зобов'язаний виконати:

- max_steps = 50
- max_parallel = 5
- max_total_cost_1t = team_day_limit
- max_wait_time_per_step = 120s
- max_agent_invocations_per_flow = 5
- no recursive router → router

## 8. Cost Control

Router виконує pre-estimate:

    estimated_cost = sum(step.cost_estimates)

Якщо це > quota:

    abort + error: cost_limit_exceeded

Після кожного кроку:

- оновлюється фактичний cost
- Usage Engine робить ті самі перевірки
- PDP отримує оновлений контекст

## 9. Confidential Mode

Router:

- фільтрує plaintext інформацію
- замінює raw → summary
- забороняє vision-кроки
- забороняє tools категорії C/D
- обмежує autonomy планування
- не зберігає input у логах

## 10. Tool Execution Flow

    sequenceDiagram
        participant R as Router
        participant PDP
        participant T as Tool Proxy

        R->>PDP: authorize(tool.<name>.invoke)
        PDP-->>R: allow
        R->>T: execute tool
        T-->>R: output + usage

## 11. LLM Execution Flow

    sequenceDiagram
        participant R
        participant PDP
        participant LLM

        R->>PDP: authorize(tool.llm.invoke)
        R->>LLM: normalized request
        LLM-->>R: output + tokens

## 12. Subagent Execution Flow

Router може викликати агентів, але з обмеженнями:

    max_subagents_per_flow = 3
    no_chained_subagent → subagent → subagent

Flow:

    sequenceDiagram
        participant R
        participant PDP
        participant A as Agent Orchestrator

        R->>PDP: authorize(agent.run.invoke)
        R->>A: trigger agent
        A-->>R: result

## 13. Error Handling

### Типи помилок:

Type | Action
--- | ---
tool_timeout | retry → skip
llm_timeout | retry → fallback
invalid_args | fail step
unauthorized | abort
quota_exceeded | abort
agent_failed | skip/abort
branch_condition_error | default-fallback

### Recovery logic:

    on error:
      if retryable → retry 1-2 times
      else break or skip

## 14. Logging

Router логування (без plaintext):

- steps
- timings
- cost
- tokens
- used tools
- fallback transitions
- error traces

Logs → telemetry + NATS:

    router.flow.started
    router.flow.completed
    router.flow.failed

## 15. Monitoring

Показники:

- steps/min
- average cost
- retry rate
- failure rate
- parallelism
- queue depth

## 16. Platform Tool Integration (Energy/Food/Water)

Router може викликати:

    tool.greenfood.order
    tool.energy.read
    tool.water.read

Умови:

- PDP must allow
- confidential mode → redacted
- no mass platform actions (>10 per flow)

## 17. Parallel Steps

Router може виконувати групи:

    {
      "type": "parallel",
      "steps": [
        {"type":"llm", ...},
        {"type":"tool", ...}
      ]
    }

Завершення:

- всі успішні → success
- будь-який критичний failure → abort

## 18. Branch Logic

    {
      "type": "branch",
      "condition": "output.text contains 'yes'",
      "if_true": [...],
      "if_false": [...]
    }

Оцінка:

- через LLM Proxy (cheap models)

## 19. Loop Logic

    max_loops = 5

Loop без умови → abort.

## 20. Full Example Flow

    {
      "input": "Створи мені сторінку GreenFood",
      "goal": "Сформувати JSON-структуру і завдання",
      "steps": [
        { "type": "llm", "args": {"task":"extract_requirements"} },
        { "type": "tool", "tool": "project.create", "args": {...} },
        { "type": "parallel", "steps": [
            { "type": "llm", "args": {...} },
            { "type": "tool", "tool": "task.create", "args": {...} }
          ]
        }
      ]
    }

## 21. Integration with Other Docs

Цей документ доповнює:

- `45_llm_proxy_and_multimodel_routing.md`
- `37_agent_tools_and_plugins_specification.md`
- `32_policy_service_PDP_design.md`
- `44_usage_accounting_and_quota_engine.md`
- `40_rwa_energy_food_water_flow_specs.md`

## 22. Завдання для Cursor

    You are a senior backend engineer. Implement Router Orchestrator Design using:
    - 46_router_orchestrator_design.md
    - 45_llm_proxy_and_multimodel_routing.md
    - 37_agent_tools_and_plugins_specification.md

    Tasks:
    1) Create Router Orchestrator service architecture (Step Engine, State Machine).
    2) Implement Input Specification (unified request format).
    3) Add Router Modes (AUTO PLAN, STRUCTURED, HYBRID).
    4) Implement State Machine Architecture (INIT, PLAN, EXECUTE_STEP, WAIT_TOOL, WAIT_AGENT, ERROR_RECOVERY, DONE).
    5) Create Step Engine (step types: LLM, Tool, Agent, Platform, Branch, Parallel, Loop).
    6) Add Safety Limits (max_steps, max_parallel, max_total_cost_1t, max_wait_time_per_step, max_agent_invocations_per_flow, no recursive router).
    7) Implement Cost Control (pre-estimate, quota check, actual cost tracking).
    8) Add Confidential Mode (filter plaintext, replace raw → summary, disable vision, disable category C/D tools, limit autonomy).
    9) Implement Tool Execution Flow (PDP authorization, Tool Proxy integration).
    10) Implement LLM Execution Flow (PDP authorization, LLM Proxy integration).
    11) Add Subagent Execution Flow (max_subagents_per_flow, no chained subagents).
    12) Implement Error Handling (error types, recovery logic, retry mechanism).
    13) Add Logging (steps, timings, cost, tokens, tools, fallback, errors).
    14) Add Monitoring (steps/min, average cost, retry rate, failure rate, parallelism, queue depth).
    15) Implement Platform Tool Integration (GREENFOOD, EnergyUnion, WaterUnion).
    16) Add Parallel Steps (parallel execution, success/failure handling).
    17) Implement Branch Logic (conditional branches, LLM-based condition evaluation).
    18) Add Loop Logic (max_loops, abort on infinite loops).

    Output:
    - list of modified files
    - diff
    - summary

## 23. Summary

DAARWIZZ Router / Orchestrator:

- управляє multi-step AI флоу
- гарантує безпеку кожного кроку
- інтегрує LLM, інструменти, агентів та платформи
- контролює витрати 1T та usage
- виконує state machine
- захищений policy engine
- підтримує branching, loops, parallelism
- працює в confidential mode
- є основою автоматизації у DAARION OS

Версія: 1.0
Останнє оновлення: 2024-11-14