Budget#

In the context of agent execution, a budget refers to a predetermined limit on the amount of resources or actions an agent is allowed to consume during its execution. The purpose of a budget is to control and manage the agent’s behavior, preventing it from using excessive resources, making too many calls to external services, or executing for an extended period.

Budgets are particularly relevant when working with AI agents or language models that interact with external systems, use computational resources, or have certain usage restrictions. It ensures that the agent operates within specified boundaries, making it more predictable and manageable.

Possible Types of Budget#

  1. Time Budget: A time budget imposes a limit on the execution time for the agent. It ensures that the agent’s execution does not exceed a specified time limit, preventing it from running indefinitely.

  2. Token Budget: In natural language processing tasks, tokens are fundamental units representing words or characters. A token budget restricts the number of tokens an agent can use during execution. This is useful for limiting the length of generated responses or controlling the number of tokens processed.

  3. Call Budget: If an agent interacts with external services or APIs, a call budget limits the number of API calls or external requests it can make. This helps prevent abuse or overloading external systems.

Importance of Budgets#

  1. Fair Usage: Budgets promote fair usage of resources, especially in multi-user environments. They prevent a single agent from monopolizing system resources and allow fair access to other agents.

  2. Cost Control: For services where costs are associated with resource consumption (e.g., cloud-based AI services), budgets help control expenses by limiting resource usage.

  3. Safety and Security: Budgets act as safety guards, preventing agents from executing indefinitely and causing resource exhaustion or crashes.

  4. Predictability: With budgets, the behavior of an agent becomes more predictable, making it easier to plan and manage system resources.

  5. Preventing Abuse: Budgets protect against malicious or poorly designed agents that might otherwise overload systems with excessive usage.

Classes#

class council.runners.Budget(duration: float, limits: List[Consumption] | None = None, consumptions: List[ConsumptionEvent] | None = None)[source]#

Bases: object

A class representing a budget with duration, limits, and consumption events.

__init__(duration: float, limits: List[Consumption] | None = None, consumptions: List[ConsumptionEvent] | None = None) → None[source]#

Initialize the Budget object

Parameters:

  • duration (float) – The duration of the budget in some time unit (e.g., days, months, etc.).

  • limits (List[Consumption]) – Optional. A list of Consumption objects representing the budget limits. Each Consumption object contains a value, unit, and kind.

  • consumptions (List[ConsumptionEvent]) – Optional. A list of ConsumptionEvent objects representing the consumption events within the budget duration. Each ConsumptionEvent object contains a consumption measurement, a source, and an optional timestamp.

static default() → Budget[source]#

Helper function that create a new Budget with a default value.

Returns:

Budget

is_expired() → bool[source]#

Check if the budget is expired :returns: True is the budget is expired. Otherwise False

remaining() → Budget[source]#

Create a new instance with the remaining budget

Returns:

a new instance with the remaining budget

class council.runners.Consumption(value: float, unit: str, kind: str)[source]#

Bases: object

A class representing a consumption measurement with value, unit, and kind information.

_value#

The numeric value of the consumption measurement.

Type:

float

_unit#

The unit of measurement for the consumption (e.g., tokens, api_calls, etc.).

Type:

str

_kind#

The kind or category of the consumption.

Type:

str

__init__(value

float, unit: str, kind: str): Initializes a Consumption instance with the provided value, unit, and kind.

__init__(value: float, unit: str, kind: str)[source]#

Initializes a Consumption instance.

Parameters:

  • value (float) – The numeric value of the consumption measurement.

  • unit (str) – The unit of measurement for the consumption (e.g., liters, watts, etc.).

  • kind (str) – The kind or category of the consumption (e.g., water, electricity, etc.).

class council.runners.ConsumptionEvent(consumption: Consumption, source: str)[source]#

Bases: object

A class representing an event related to consumption, along with the source and timestamp information.

_consumption#

An instance of the Consumption class representing the consumption measurement.

Type:

Consumption

_source#

The source of the consumption event (e.g., sensor name, device, etc.).

Type:

str

_timestamp#

The timestamp of the consumption event.

Type:

float

__init__(consumption

Consumption, source: str): Initializes a ConsumptionEvent instance with the provided consumption, source, and timestamp.

__init__(consumption: Consumption, source: str)[source]#

Initializes a ConsumptionEvent instance.

Parameters:

  • consumption (Consumption) – An instance of the Consumption class representing the consumption measurement.

  • source (str) – The source of the consumption event (e.g., sensor name, device, etc.).