Skip to content

Getting Started

Installation

Install from PyPI:

pip install aitaem

For BigQuery support, install the optional extra:

pip install "aitaem[bigquery]"

Three-Step API

Every aitaem workflow has three steps:

from aitaem import SpecCache, ConnectionManager, MetricCompute

# 1. Load metric, slice, and segment specs from YAML files or directories
cache = SpecCache.from_yaml(
    metric_paths="examples/metrics/",
    slice_paths="examples/slices/",
    segment_paths="examples/segments/",
)

# 2. Configure the data backend (DuckDB, BigQuery, etc.)
conn = ConnectionManager.from_yaml("examples/connections.yaml")

# 3. Compute metrics
mc = MetricCompute(cache, conn)
df = mc.compute(
    metrics="ctr",
    slices="campaign_type",
    segments="platform",
    time_window=("2024-01-01", "2024-04-01"),
)
print(df)

Standard Output Format

Every compute() call returns a pandas DataFrame with exactly these 10 columns:

Column Description
period_type "all_time" or a named period
period_start_date ISO date string or None
period_end_date ISO date string or None
entity_id Entity column value when by_entity is set; None otherwise
metric_name Name of the metric (e.g. "ctr")
slice_type Slice name or "none" for the all-data baseline
slice_value Slice value (e.g. "Search") or "all"
segment_name Segment name or "none" for the all-data baseline
segment_value Segment value (e.g. "Google Ads") or "all"
metric_value Computed numeric result

Example: Ad Campaigns Dataset

The examples/ directory contains sample YAML specs and a DuckDB dataset for an ad campaigns use case.

from aitaem import SpecCache, ConnectionManager, MetricCompute
from aitaem.helpers import load_csvs_to_duckdb

# Load the sample CSV into a DuckDB database
connector = load_csvs_to_duckdb(
    csv_path="examples/data/ad_campaigns.csv",
    db_path="/tmp/ad_campaigns.duckdb",
)

conn = ConnectionManager()
conn.add_connection("duckdb", connector=connector)

cache = SpecCache.from_yaml(
    metric_paths="examples/metrics/",
    slice_paths="examples/slices/",
    segment_paths="examples/segments/",
)

mc = MetricCompute(cache, conn)

# CTR by campaign type for Q1 2024
df = mc.compute(
    metrics="ctr",
    slices="campaign_type",
    time_window=("2024-01-01", "2024-04-01"),
)
print(df[["slice_value", "metric_value"]])

Next Steps