Stirrup Documentation

Group By operations collapse the dataset into groups based on one or more columns. Use .group_by() followed by .agg() to apply aggregation functions to each group.

Basic Group By

You can group by a single column or a list of columns.

Common Aggregation Functions

• Numeric: sum(), mean(), median(), std(), var(), min(), max().
• Counting: pl.len(), n_unique().
• First/Last: first(), last(), min(), max().
• Quantiles: quantile(q).

Computed Aggregations

You can perform arithmetic within .agg() to calculate ratios, weighted averages, ranges, or coefficients of variation.

Collect Into Lists

Aggregations can return lists of values per group using col("column") or concatenate strings using .str.concat().

# Single grouping column
result = df.group_by("category").agg(
    col("value").sum().alias("total"),
    col("value").mean().alias("avg"),
    pl.len().alias("count"),
)

# Multiple grouping columns
result = df.group_by(["region", "category"]).agg(
    col("revenue").sum().alias("total_revenue"),
    col("quantity").sum().alias("total_quantity"),
)

# Computed Aggregations
df.group_by("category").agg([
    (col("successes").sum() / col("attempts").sum()).alias("success_rate"),
    (col("value") * col("weight")).sum() / col("weight").sum().alias("weighted_avg"),
])

# Collect Into Lists
df.group_by("user_id").agg([
    col("product").alias("products"),
    col("product").unique().alias("unique_products"),
])

When implementing a client, be aware of the following guarantees provided by the Stirrup framework:

• Stable identity: AssistantMessage.id is assigned once at construction and remains stable through serialization (model_dump/model_validate) cycles.
• Same object in history: The exact object returned by generate is what is appended to history. The framework does not copy or rebuild messages unless performing summarization or context-overflow unwinding.
• Subclasses are preserved: You can return an AssistantMessage subclass to carry integration-specific state. To prevent this state from being serialized into history, mark the extra fields with exclude=True.
• metadata is opaque: The framework does not interact with the metadata field. You should namespace your keys (e.g., "myco/...") to avoid collisions with other users.
• Summaries carry lineage: SummaryMessage objects record the IDs of the assistant messages they replaced via replaced_ids, allowing for reconstruction of history lineage.

Window functions compute values across related rows without collapsing the dataset. Use the .over() method to define the partition (the group) over which the function operates.

Ranking

Use .rank(method=...) to assign ranks within a group. Supported methods:

• "ordinal": 1, 2, 3, 4 (unique ranks).
• "dense": 1, 2, 2, 3 (no gaps for ties).
• "min": 1, 2, 2, 4 (min rank for ties).
• "max": 1, 3, 3, 4 (max rank for ties).
• "average": 1, 2.5, 2.5, 4 (average rank for ties).

Lag and Lead

Use .shift(n) to access values from other rows within a group:

• shift(1): Previous value (Lag).
• shift(-1): Next value (Lead).

Cumulative Functions

• cum_sum(): Running total.
• cum_mean(): Running average.
• cum_count(): Running count.
• cum_min() / cum_max(): Running minimum/maximum.

# Sum per group (added to each row)
df = df.with_columns(
    col("value").sum().over("category").alias("category_total")
)

# Ranking
df = df.with_columns(
    col("score").rank(method="dense", descending=True).over("department").alias("dense_rank")
)

# Lag/Lead
df = df.with_columns(
    col("value").shift(1).over("user_id").alias("prev_value")
)

# Cumulative
df = df.with_columns(
    col("value").cum_sum().over("user_id").alias("running_total")
)

The run() method returns a tuple of three values: (finish_params, history, metadata).

finish_params

Contains the agent's final response when it calls the finish tool. It includes:

• reason: A string explanation of what was accomplished.
• paths: A list of file paths created or modified during execution.

history

A list of message groups (SystemMessage, UserMessage, AssistantMessage, ToolMessage).

AssistantMessage objects use a blocks list to preserve the model's emission order (e.g., reasoning $\rightarrow$ text $\rightarrow$ tool call). Block types include text, reasoning, tool_call, and various media kinds.

Note: Accessing deprecated attributes like .content or .tool_calls on an AssistantMessage will emit a DeprecationWarning. Use convenience accessors like joined_text, final_text, tool_call_blocks, or reasoning_blocks instead.

metadata

A dictionary containing metadata from tool executions and token usage. You can use aggregate_metadata to combine metadata across all tool calls.

# Example of unpacking run results
finish_params, history, metadata = await session.run("Your task")

# Example of accessing finish_params
print(finish_params["reason"])
print(finish_params["paths"]) # e.g., ["output.png"]

# Example of aggregating metadata
from stirrup import aggregate_metadata
aggregated = aggregate_metadata(metadata)
print(f"Total tokens: {aggregated['token_usage'].total}")