Files

Apple c552199eed chore: organize documentation structure for monorepo

- Create /docs structure (microdao, daarion, agents)
- Organize 61 cursor technical docs
- Add README files for each category
- Copy key documents to public categories
- Add GitHub setup instructions and scripts

2025-11-15 04:08:35 -08:00

9.6 KiB

Raw Blame History

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

9.6 KiB Raw Blame History Unescape Escape