Core Concepts
Constraint Graph
Ratelord models constraints as a directed graph. Resources are nodes in this graph, and relationships (like "belongs to" or "consumes") are edges. This allows for complex modeling of nested budgets.
Identities & Scopes
- Identity: A unique actor in the system (e.g., a specific agent script, a user, or a microservice).
- Scope: A logical grouping of resources. Scopes can be hierarchical (e.g., `org:acme` -> `team:engineering` -> `project:backend`).
Resource Pools
A bucket of available units. Pools can be:
- Renewable: Refills over time (e.g., API rate limits).
- Depletable: A fixed budget that runs out (e.g., prepaid token credits).
Intent Negotiation
The core protocol of Ratelord. Agents do not just "take" resources; they negotiate for them.
- Propose: Agent asks, "I need 100 tokens to run this query."
- Evaluate: Ratelord checks available pools, policies, and priorities.
- Grant/Reject/Counter: Ratelord responds. It might say "Granted", "Rejected (limit reached)", or "Counter: You can have 50 tokens now, or wait 10s for 100."
Forecasts
Ratelord calculates Time-to-Exhaustion (TTE) for every pool. This allows agents to make informed decisions: "If I continue at this rate, I will be blocked in 5 minutes. I should slow down now."