Aigora

Aigora is a Python framework for running market experiments with large language-model (LLM) agents. This page gives the big picture of how Aigora works. Details are omitted here, but you can easily find them in the rest of the documentation.

The Aigora loop

The organising principle of Aigora is the agent loop (pictured below). Each agent operates in an asynchronous loop that alternates between observation and action. In each iteration, the agent observes a snapshot of the current market state, selects an action (buy, sell, cancel, or do nothing), and submits it to the engine. The engine checks the action against the trading rules, decides whether to accept it, and updates the market state accordingly. The agent then receives a fresh snapshot with the updated market state, and the loop repeats until the end of the experiment (or you run out of API credits).

Everything that happens in the agent loop is defined in a single YAML configuration file. Think of this configuration file as the single source of truth for the experiment, housing all the parameters and settings that control what happens in the loop.

The configuration is designed to be flexible and composable, so you have ample freedom to design the experiment you want, while offering some sensible structure to keep things organised and reproducible.

What the agent 'sees'

The most pivotal design choice for you, the experimenter, is what information to supply to each agent before it makes a decision. This information is called the agent's context, and it is assembled from a composable set of context providers: components that turn information into text for the agent.

Aigora provides several built-in providers that will likely be included in most experiments (e.g., orderbook information, the agent’s own holdings and orders, recent trades, etc.), but you can also write your own custom providers to precisely control what each agent sees.

What the agent 'sees' is an amalgamation of three sources (pictured below): the conversation history (which includes the initial instructions, and all past responses), the latest update from the context providers, and a system prompt that defines the expected format of the agent's response. Aigora provides an interface for you to manipulate each of these sources, so you can control exactly what the agent sees.

The market

The market operates under a continuous double auction (CDA) — as is typical in modern financial markets. In a CDA, traders can submit bids (offers to buy) and asks (offers to sell) at any time, and trades occur whenever a bid and ask cross (i.e., the bid price is greater than or equal to the ask price). Orders are matched in price-time priority: the best price is matched first, and if there are multiple orders at the same price, the earliest order is matched first.

A note on reproducibility

While aigora attempts to control as much randomness as it can, there are some sources of randomness that are beyond control, such as the inherent non-determinism of LLMs and the latency of API calls. The same version of a hosted model may return different responses to the same prompt at different times, and with variable latency. Both of these factors can affect the sequence of events in a market experiment, which can affect subsequent observations and decisions.