axes-client 0.4.0

Python client for the Axes data API, and the axes.agent framework

Axes Client Library

Python client for the Axes data API. Send SQL, get parquet back.

pip install axes-client

Quickstart

from axes import sql

result = sql("SELECT state, AVG(income) FROM american_community_survey.demographics GROUP BY state")

result.rows        # int — number of rows
result.bytes       # int — parquet response size in bytes
result.columns     # list[str] — ordered column names
result.elapsed_ms  # int — wall-clock time for the request

# Check size before loading into memory
if result.bytes < 100 * 1024 * 1024:
    df = result.collect()   # polars DataFrame — full result in memory
else:
    lf = result.scan()      # polars LazyFrame — safe for large results

# Save to parquet
result.save("/work/result.parquet")

# Stream directly to a file — never buffers the full response in memory
result = sql(
    "SELECT * FROM american_community_survey.demographics",
    out="/work/result.parquet",
)
lf = result.scan()  # polars LazyFrame over the file

Results under 10 MB are kept in memory. Larger results spill to a temp file in /tmp and are deleted when the SqlResult is garbage collected. .scan() is always safe — it returns a scan_parquet LazyFrame when spilled rather than loading into memory.

Configuration

export AXES_TOKEN=your-personal-access-token

AXES_ENDPOINT defaults to https://app.axes.com. Override it if you are running a self-hosted instance:

export AXES_ENDPOINT=https://your-axes-instance.com
export AXES_TOKEN=your-personal-access-token

Explicit client

from axes import Client, sql

client = Client(
    endpoint="https://your-axes-instance.com",
    token="your-token",
)

result = sql("SELECT * FROM american_community_survey.demographics", client=client)

CLI

# Stream rows to stdout as newline-delimited JSON (ndjson), one object per line
axes sql "SELECT state, AVG(income) FROM american_community_survey.demographics GROUP BY state"

# Pipe to jq — each line is a standalone JSON object
axes sql "SELECT state FROM american_community_survey.demographics" | jq '.state'

# Write parquet and print a JSON summary
axes sql "SELECT * FROM american_community_survey.demographics" --out /work/result.parquet

When --out is provided, a JSON summary is printed to stdout:

{
  "path": "/work/result.parquet",
  "rows": 51,
  "bytes": 4096,
  "columns": ["state", "income"],
  "elapsed_ms": 340
}

Errors

from axes.exceptions import QueryError, ResultTooLarge, AuthError

try:
    result = sql("SELECT * FROM american_community_survey.demographics")
except QueryError as e:
    print(e.message)      # SQL rejected by the server (400)
except ResultTooLarge as e:
    print(e.message)      # Exceeded row/byte cap (413)
except AuthError as e:
    print(e.status_code)  # 401 or 403

Appending data

append_table_data uploads a parquet file to an existing table. It needs a write-scoped token bound to the target dataset — the ingestion runner injects one as AXES_TOKEN; personal access tokens are read-only and raise AuthError.

from axes import append_table_data

# Accepts a polars DataFrame, a parquet path, or raw parquet bytes
result = append_table_data("demographics", df)

result.row_count           # rows written
result.byte_count          # bytes written
result.table_data_file_id  # id of the created file

# Atomically retire this firing's earlier files instead of adding to them
append_table_data("demographics", df, replace=True)

The uploaded parquet's columns must match the table's registered schema; a mismatch raises WriteError (409).

Agent framework

axes.agent is the container-side framework for authoring Chat Plot agents. Agents already read the data catalog through this client, so the framework ships here rather than as a separate package.

from axes.agent import Agent, Tool, RunContext

Author an agent as an Agent subclass with Tool members (and other Agent instances as subagents); the axes-agent console script reads one step off stdin, runs plan_step or run_tool, and writes the result to stdout. Chat Plot drives the multi-turn loop and owns the LLM call, persistence, and streaming. See weather-agent for a worked example.

Development

uv sync

uv run task test    # pytest
uv run task lint    # ruff check
uv run task format  # ruff format
uv run task check   # mypy (strict)

task fix runs ruff check --fix. Linting (ruff), formatting, and strict type checking (mypy) all run in CI on every push and pull request.