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

11 KiB

Raw Blame History

44 — Usage Accounting & Quota Engine (MicroDAO)

Usage Engine: лічильники, квоти, облік вартості, PDP інтеграція, rate limits, soft/hard limits, попередження, економічна стабільність DAARION OS.

1. Purpose & Scope

Usage Engine — це центральна система, яка:

обліковує використання ресурсів,
застосовує квоти відповідно до планів (Freemium → Platformium),
коригує ліміти через стейк RINGK,
блокує надмірне використання,
сигналізує API Gateway про warnings/hard-stops,
інтегрується з PDP та Governance.

Вона контролює витрати:

LLM-токени
agent runs
router invokes
embassy events
storage
wallet tx
compute (1T)

2. Usage Engine Architecture

API Gateway / Agents / Embassy / Tools
       ↓
 Usage Accounting Proxy
       ↓
Quota Engine (core)
       ↓
Postgres / Redis (counters)
       ↓
PDP (authorization)

3. Usage Metrics (Canonical List)

3.1 Compute / LLM:

llm_tokens_input
llm_tokens_output
llm_cost_1t

3.2 Agents:

agent_runs
agent_parallel_runs
agent_tools_used

3.3 Router:

router.invoke
router.steps

3.4 Embassy:

embassy.events_received
embassy.energy.update
embassy.food.update
embassy.water.update

3.5 RWA:

rwa_processed_records

3.6 Wallet:

wallet.tx
payout.claims

3.7 File Storage:

storage.bytes_uploaded
storage.bytes_retained

4. Quota Types

4.1 Hard quotas

Перевищення → STOP + 403 error.

Приклади:

LLM tokens per month
agent runs per day
embassy events per day
browser-lite usage per hour
wallet tx per 10 min

4.2 Soft quotas

Перевищення → тротлінг, warning headers.

Приклади:

router.invoke per minute
search queries

4.3 Compute cost ceilings

Обмеження:

per run (max_cost_per_run)
per day
per month

5. Quota Formula

Кожна квота =

effective_quota = base_quota(plan) × multiplier(stake)

Де:

5.1 Base quota

Визначається планом:

Freemium → найнижча
Casual
Premium
Platformium → максимальні

5.2 Multiplier

Функція:

multiplier = f(RINGK_staked)

Приклад:

RINGK Stake	Multiplier
0	1.0
1000	1.25
5000	1.5
20000	2.0

6. Counters (Storage Model)

6.1 Redis (fast counters)

Проміжні лічильники для:

agent_runs
tokens_per_minute
embassy_events
router_invokes

Приклад ключів:

usage:team:{team_id}:llm_month
usage:team:{team_id}:agent_day
usage:user:{user_id}:wallet_tx_hour

6.2 Postgres (durable counters)

щоденні/місячні агрегати,
історія usage,
перерахунок після crash.

create table usage_daily (
  team_id text,
  metric text,
  value bigint,
  day date
);

7. Quota Engine (Decision Logic)

allow =
   usage(current) < quota(effective)

Виклик надходить від API Gateway.
Usage Engine інкрементує провізорний лічильник.
Перевіряє квоту.
Якщо ок → PDP підтверджує дію.
Якщо переповнення → deny.

8. Warning Thresholds

При 80–90% використання:

X-DAARION-Usage-Warning: <metric> near limit

UI може показувати:

«Залишилось 10% LLM бюджету»
«Агентні запуски майже вичерпані»

9. Rate Limiting Integration

Quota Engine тісно працює з rate limits:

soft RL: попередження
hard RL: блокування на період

Періоди:

1 хвилина
10 хвилин
година
доба
місяць

10. PDP Integration

При оцінці дії:

PDP checks:
  - capability
  - role
  - plan
  - ACL
  - quotas (via Usage Engine)

Usage Engine повертає PDP:

quota_ok = true/false
quota_remaining
cost_estimate

11. Cost Accounting (1T Integration)

LLM Proxy обчислює:

cost_1t = tokens × price_per_token

Router/Agent додає:

cost_1t += tool_cost

Usage Engine додає:

team_monthly_compute += cost_1t

PDP блокує, якщо:

team_monthly_compute > compute_quota

12. Embassy / RWA Quotas

Щоб уникнути спаму і фродових оновлень:

Domain	Limit
energy	10 000 updates/day
food	5 000 updates/day
water	5 000 updates/day

Також:

max_events_per_minute (per platform)

13. Agent Run Limits

Окремі ліміти:

max_runs_per_day
max_parallel_runs
max_tools_per_run
max_llm_tokens_per_run
max_cost_per_run

14. Storage/Files Quotas

На команду:

Freemium: 100MB
Casual: 500MB
Premium: 5GB
Platformium: 25GB+

15. Wallet/Chain Quotas

З метою безпеки:

max_wallet_tx_per_hour = 2
max_claims_per_day = 10
max_stake_ops_per_day = 5

16. Usage Correction / Reconciliation

Раз на добу:

Redis → PostgreSQL sync
anomaly detection
usage recalculation для long tasks (agent runs)
звірка tokens_used з LLM Proxy

17. Governance Controls

Governance може:

підвищувати/знижувати квоти,
змінювати compute price,
вимикати окремі метрики,
вводити "emergency cap",
змінювати stake multipliers.

18. Abuse / Fraud Protection

Виявляє:

різкі стрибки usage,
автоматичні цикли агентів,
LLM infinite loops,
embassy spam,
wallet brute-force,
chain-попит аномальний.

Система автоматично може:

знизити квоти тимчасово,
заблокувати агентів,
призупинити Embassy platform,
вимкнути інструменти.

19. Observability

Метрики:

usage per minute/day/month
quota remaining
cost per run
agent tokens used
embassy event rate
router invoke rate
anomaly score

Графіки в Grafana:

per сервіс
per команду
per користувача
per домен (RWA/Energy/Food/Water)

20. Error Model

Коди помилок Usage Engine:

Code	Meaning
quota_exceeded	перевищено квоту
cost_exceeded	обчислювальний бюджет вичерпано
rate_limited	надто багато дій
anomaly_detected	підозрілий патерн
agent_parallel_limit	забагато агентів
tokens_limit	LLM usage overflow

21. Example Scenarios

21.1 LLM Overflow

Користувач запитує великий контекст → tokens_used > quota → deny.

21.2 Embassy Spam

EnergyUnion шле 10k events/min → throttling → deny.

21.3 Infinite Agent Loop

Агент намагається робити 50 runs/min → deny.

22. Integration with Other Docs

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

32_policy_service_PDP_design.md
30_cost_optimization_and_token_economics_infrastructure.md
31_governance_policies_for_capabilities_and_quotas.md
40_rwa_energy_food_water_flow_specs.md
38_private_agents_lifecycle_and_management.md

23. Завдання для Cursor

You are a senior backend engineer. Implement Usage Accounting & Quota Engine using:
- 44_usage_accounting_and_quota_engine.md
- 32_policy_service_PDP_design.md
- 30_cost_optimization_and_token_economics_infrastructure.md

Tasks:
1) Create Usage Engine service architecture (Usage Accounting Proxy, Quota Engine, Redis/Postgres counters).
2) Define Usage Metrics (LLM tokens, agent runs, router invokes, embassy events, RWA, wallet tx, storage).
3) Implement Quota Types (Hard quotas, Soft quotas, Compute cost ceilings).
4) Implement Quota Formula (base_quota(plan) × multiplier(stake)).
5) Create Counters Storage Model (Redis for fast counters, Postgres for durable counters).
6) Implement Quota Engine Decision Logic (usage check, quota validation, PDP integration).
7) Add Warning Thresholds (80-90% usage warnings).
8) Integrate Rate Limiting (soft/hard limits, time periods).
9) Integrate with PDP (quota_ok, quota_remaining, cost_estimate).
10) Implement Cost Accounting (1T integration, LLM Proxy cost calculation, team monthly compute).
11) Add Embassy/RWA Quotas (per domain limits, max_events_per_minute).
12) Implement Agent Run Limits (max_runs_per_day, max_parallel_runs, max_tools_per_run, max_llm_tokens_per_run, max_cost_per_run).
13) Add Storage/Files Quotas (per plan limits).
14) Implement Wallet/Chain Quotas (max_wallet_tx_per_hour, max_claims_per_day, max_stake_ops_per_day).
15) Add Usage Correction / Reconciliation (Redis → PostgreSQL sync, anomaly detection, usage recalculation).
16) Add Governance Controls (quota updates, compute price changes, emergency cap, stake multipliers).
17) Implement Abuse / Fraud Protection (anomaly detection, automatic quota reduction, agent blocking, embassy suspension).
18) Add Observability (metrics, Grafana dashboards).
19) Implement Error Model (quota_exceeded, cost_exceeded, rate_limited, anomaly_detected, agent_parallel_limit, tokens_limit).

Output:
- list of modified files
- diff
- summary

24. Summary

Usage Engine:

гарантує економічну стабільність системи,
контролює всі ресурси,
застосовує квоти,
працює з PDP, Agents, Embassy, Wallet, Tools,
захищає систему від зловживань,
базується на Redis + Postgres,
повністю конфігурується Governance,
забезпечує масштабовану, передбачувану, справедливу модель використання DAARION OS.

Це — центральний обліковий шар платформи.

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

11 KiB Raw Blame History Unescape Escape