dda-sdk 0.0.1__tar.gz

dda_sdk-0.0.1/.claude/skills/dda-analytics/SKILL.md

@@ -0,0 +1,523 @@
+---
+name: dda-analytics
+description: Use this skill whenever the user asks for charts, graphs, or data analysis using IndieBI game data. Triggers for: "show me revenue from Steam", "chart of wishlist adds", "how did [game] perform in Q1", "compare sales across platforms", "units sold last month", "what's our best performing title", "generate a report", "visualize [metric]", "which countries", "sales by country", "top countries", "geographic breakdown", "discounts", "promotions", "sales events", "what promos ran", "Steam Summer Sale", "how did the discount perform", "what was the discount", "promo impact", "sales uplift", "event performance", "what events ran", "discount history", "promo calendar", "wishlist adds", "wishlist conversions", "store page visits", "visibility data", "page impressions". Always invoke this skill before writing any data-fetching or chart code — it tells you which table to query, how to write the fetch script, and how to render the result as an IndieBI-styled chart.
+---
+
+# DDA Analytics
+
+This skill walks through fetching IndieBI DDA data and rendering it as an HTML chart.
+
+## Pre-flight — Check project is initialized
+
+Before doing anything else, verify the project is ready to run. Do this by checking whether a virtual environment exists:
+
+```bash
+test -d .venv && echo "ok" || echo "missing"
+```
+
+If `.venv` is **missing**, the user hasn't run `uv sync` yet. Walk them through setup:
+
+### 1. Check Python
+
+```bash
+python3 --version
+```
+
+If the command fails or returns a version below 3.12, **ask the user before proceeding**:
+
+> "Python 3.12+ is required but doesn't seem to be installed. Should I install it for you? (This will use your system package manager.)"
+
+Wait for confirmation before running any install command.
+
+### 2. Check uv
+
+```bash
+uv --version
+```
+
+If the command fails, **ask the user before proceeding**:
+
+> "`uv` (the Python package manager) isn't installed. Should I install it now? It's a quick one-liner: `curl -LsSf https://astral.sh/uv/install.sh | sh`"
+
+Wait for confirmation, then run the install.
+
+### 3. Run uv sync
+
+Once Python and uv are available, run:
+
+```bash
+uv sync
+```
+
+Tell the user: "Project dependencies installed — you're ready to go."
+
+If `.venv` **exists**, the project is already set up — skip this section and proceed to Step 0.
+
+---
+
+## Step 0 — Create a project folder
+
+Before doing anything else, create a timestamped folder for this request under `projects/` in the repo root. This folder holds every artifact produced: query scripts and the final HTML. The user can review them there at any time.
+
+```python
+from datetime import datetime
+import os
+
+slug = "short-description-of-request"  # e.g. "steam-revenue-jan2026"
+folder = f"projects/{datetime.now().strftime('%Y%m%d-%H%M%S')}-{slug}"
+os.makedirs(folder, exist_ok=True)
+```
+
+All `.py` scripts go in this folder. The final HTML goes in this folder. Never ask the user to approve the scripts before running them — just run them.
+
+> **Read-only project rule:** This skill only ever writes inside the `projects/` folder it creates. Never create, edit, or delete any file outside of `projects/` — this means no touching `dda_sdk/`, `schemas/`, `tests/`, `.claude/`, or any other file in the repo. The SDK and schemas are the data source; treat them as read-only infrastructure.
+>
+> **Exception:** when handling a credentials error (see below), you must write to `.env` in the project root. That is the only file outside `projects/` you are allowed to touch.
+
+---
+
+## Credential handling
+
+When any fetch script raises a `ValueError` that mentions "Missing credentials", the user hasn't set up their `.env` yet. Handle it like this:
+
+1. **Tell the user what happened** — explain that the SDK needs a User ID and SAS token to access the data lake, and they haven't been set up yet.
+
+2. **Ask for the credentials:**
+   > "To connect to IndieBI data, I need two things from your IndieBI contact:
+   > - **User ID** (looks like `u-xxxxxxx`)
+   > - **SAS Token** (starts with `sp=rl&st=...`)
+   >
+   > Please paste them here and I'll save them to `.env` for you."
+
+3. **Save to `.env`** in the project root. If `.env` doesn't exist, create it from scratch using the format in `.env.example`:
+   ```
+   USER_ID=<value the user gave>
+   SAS_TOKEN=<value the user gave>
+   ```
+   If `.env` already exists but is missing these keys, append them. Never overwrite other keys already in the file.
+
+4. **Retry the fetch script** — run it again. If it works, continue with the rest of the workflow. If it fails for a different reason, debug that separately.
+
+### Invalid or expired SAS token
+
+When any fetch script raises a `ValueError` that mentions "Azure authentication failed" or "invalid or expired", the SAS token in `.env` is either wrong or has expired.
+
+1. **Tell the user what happened:**
+   > "The connection to IndieBI failed — your SAS token appears to be invalid or expired."
+
+2. **Ask for a new token:**
+   > "Could you share a fresh SAS Token? (It starts with `sp=rl&st=...` and comes from your IndieBI contact.) I'll update `.env` for you."
+
+3. **Update `.env`** — replace the existing `SAS_TOKEN` value. Never touch any other key in the file.
+
+4. **Retry the fetch script.** If it works, continue. If it fails again, tell the user and ask them to double-check the token they provided.
+
+---
+
+## Step 1 — Understand the request and clarify scope
+
+Extract three things:
+
+- **Metric**: what to measure (revenue, units, wishlist adds, impressions, visits…)
+- **Filters**: platform (Steam, GOG…), date range, country, product/SKU
+- **Granularity**: daily, weekly, monthly, or a single total
+
+### Clarify before proceeding
+
+**If the request is vague** — e.g. "show me how we're doing" or "what does the data say?" with no clear metric — ask what they want to measure before writing any code. A quick one-line question saves a lot of wasted work.
+
+**If dimensions are unspecified** — date range, platforms, or products — don't silently default to "all". Instead, ask:
+
+> "You didn't specify [date range / platforms / products]. Should I fetch data across all available [dates / platforms / titles], or do you want to narrow it down?"
+
+Use judgment about which dimensions actually need clarifying:
+
+- **Date range**: Almost always worth asking if omitted — "all time" can be a huge query and may not be what the user expects.
+- **Platform**: Ask if the data covers multiple portals and the request doesn't imply "all" (e.g. "compare across platforms" implies all; "show me sales" does not).
+- **Product/SKU**: Ask if there are multiple titles and the request could reasonably mean one specific game.
+
+If the user's phrasing clearly implies "all" (e.g. "show me all platforms", "across everything", "full year"), skip the clarification and proceed. The goal is to avoid wasted compute on huge queries when the user actually had something specific in mind — not to interrogate them on every request.
+
+Ask at most one clarifying message covering all unresolved dimensions and vague intent at once. Then proceed.
+
+---
+
+## Step 2 — Map to table and columns
+
+### Metric → column
+
+| User says                                     | Column                                                                           | Table                                          |
+| --------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------- |
+| revenue / sales / gross revenue               | `gross_sales` (USD)                                                              | `sales_per_sku` or `sales`                     |
+| net revenue                                   | `net_sales_approx` (USD)                                                         | same                                           |
+| units sold                                    | `units_sold_directly`                                                            | same                                           |
+| returns (units)                               | `units_returned`                                                                 | same                                           |
+| returns (revenue)                             | `gross_returned`                                                                 | same                                           |
+| media engagement / clicks                     | `actions`                                                                        | `engagements_per_sku`                          |
+| list of promo events / promo calendar         | `event_name`, `date_from`, `date_to`, `discount`, `promo_length`, `event_status` | `events` — one row per event, no deduplication needed |
+| promo performance / sales uplift score        | `sales_uplift_score`, `click_through_rate`, `conversion_rate`                    | `events`                                       |
+| wishlist adds / removals                      | `adds`, `deletes`                                                                | `wishlist_actions` or `visibility_wishlist_per_sku` |
+| wishlist conversions / purchases              | `purchases_and_activations`, `gifts`, `total_conversions`                        | `wishlist_actions` or `wishlist_cohorts`        |
+| store page visits / impressions               | `non_owner_visits`, `non_owner_impressions`                                      | `visibility` or `visibility_wishlist_per_sku`  |
+
+Use `sales_per_sku` when you need SKU-level detail or want `human_name`. Use `sales` when aggregating across SKUs of the same product.
+
+### Currency
+
+All monetary columns (`net_sales`, `gross_sales`, `gross_returned`, and the `baseline_*`/`uplift_*` sales columns) are denominated in **USD**, unless a column's description states otherwise. The `currency_code` on `countries` and the `currencies` dimension table describe a country's *local* currency for reference/display only (e.g. showing a currency's name or symbol) — do not use them to interpret the denomination of `net_sales`, `gross_sales`, or any other monetary metric.
+
+### Geography → country breakdown
+
+Both `sales_per_sku` and `sales` have a `country_code` column (ISO 3166-1 alpha-3, e.g. `"USA"`, `"GBR"`, `"DEU"`). This is how you get individual country data — **not** by parsing `portal_platform_region`.
+
+Join with `countries` to get human-readable names and regions:
+
+```python
+import polars as pl
+from dda_sdk import DuckDBClient, SalesPerSkuSchema, CountriesSchema
+
+with DuckDBClient() as client:
+    sales_df = client.query(
+        SalesPerSkuSchema,
+        """
+        SELECT *
+        FROM sales_per_sku
+        WHERE date >= '2026-01-01'
+          AND date <= '2026-05-15'
+        """,
+    )
+    countries_df = client.query(CountriesSchema, "SELECT * FROM countries")
+
+# Join and aggregate
+by_country = (
+    sales_df
+    .join(countries_df.select(["country_code", "country_name", "region"]), on="country_code", how="left")
+    .group_by(["country_code", "country_name", "region"])
+    .agg(pl.col("units_sold_directly").sum(), pl.col("gross_sales").sum())
+    .sort("units_sold_directly", descending=True)
+)
+```
+
+> **`portal_platform_region` vs `country_code`**: The region segment in `portal_platform_region` (e.g. `"PS America"`, `"Nintendo Europe/Australia"`, `"Global"`) is the **platform's own regional grouping** — not individual countries. Always use `country_code` when the user asks about countries, country rankings, or geographic breakdowns. Use `portal_platform_region` only when filtering by storefront or platform.
+
+Note: some portals (e.g. Steam when reporting globally) may aggregate all sales under a single `country_code` or leave it empty. If `country_code` values look sparse for a portal, mention it to the user.
+
+---
+
+### Platform → filter
+
+`portal_platform_region` is a composite like `'Steam:PC:Global'` (colon-separated: portal:platform:region).
+
+**Always look up the portals table first** — don't hardcode filter strings. This ensures you use the exact values present in the user's data and catch the region ambiguity. The `display_portal` column has the human-friendly name to use in chart labels and report headers (e.g. `"Steam"` instead of `"steam"`).
+
+```python
+from dda_sdk import DuckDBClient, PortalsSchema
+
+with DuckDBClient() as client:
+    portals_df = client.query(PortalsSchema, "SELECT * FROM portals")
+
+# Find rows matching the portal the user mentioned
+steam_rows = portals_df.filter(portals_df["portal"] == "steam")
+# steam_rows["portal_platform_region"].to_list() → ["Steam:PC:Global"]
+# steam_rows["display_portal"].to_list() → ["Steam"]  ← use this in chart labels
+```
+
+Then decide:
+
+- **One matching row** → use `portal_platform_region == 'Steam:PC:Global'` (exact match, no LIKE needed)
+- **Multiple rows** (e.g. Nintendo has several regions) → ask the user: "Nintendo has these regions: [list]. Do you want all of them, or a specific one?"
+
+Build the SQL filter from the exact value(s) returned:
+
+```python
+# Single portal
+ppr = "Steam:PC:Global"
+sql_filter = f"portal_platform_region = '{ppr}'"
+
+# Multiple portals
+pprs = ["Nintendo:Switch:Americas", "Nintendo:Switch:Europe"]
+in_list = ", ".join(f"'{p}'" for p in pprs)
+sql_filter = f"portal_platform_region IN ({in_list})"
+```
+
+### Date filters
+
+Use ISO dates: `date >= '2026-01-01' AND date <= '2026-01-31'`
+
+---
+
+### Promotions & Discount Events
+
+When the user asks about discounts, promos, or sales events, use `events` — it has **one row per event** (no deduplication needed).
+
+**Key columns:**
+
+- `event_id` — unique identifier per event
+- `event_name` — human-readable name (e.g. "Steam Summer Sale 2026")
+- `date_from` / `date_to` — event start and end
+- `discount` — discount depth as a 0–1 float (e.g. `0.40` = 40% off); multiply by 100 to display as %
+- `promo_length` — event duration in days
+- `event_status` — `"finished"` or `"ongoing"`, or `None`
+- `click_through_rate` — non-owner visits to impressions ratio (null if no impressions)
+- `conversion_rate` — units sold directly to non-owner visits ratio (null if no visits)
+- `sales_uplift_score` — total sales / baseline sales; above 1.0 = positive uplift (null if baseline is zero)
+
+**Example — promo calendar:**
+
+```python
+import polars as pl
+from dda_sdk import DuckDBClient, EventsSchema
+
+with DuckDBClient() as client:
+    events_df = client.query(
+        EventsSchema,
+        "SELECT * FROM events WHERE event_status = 'finished'",
+    )
+
+# Already one row per event — sort and display
+calendar = (
+    events_df
+    .with_columns(
+        (pl.col("discount") * 100).round(0).alias("discount_pct")
+    )
+    .sort("date_from", descending=True)
+)
+print(calendar)
+```
+
+**Example — join event data with sales for promo impact:**
+
+```python
+import polars as pl
+from dda_sdk import DuckDBClient, EventsSchema, SalesSchema
+
+with DuckDBClient() as client:
+    events_df = client.query(EventsSchema, "SELECT * FROM events")
+    sales_df = client.query(SalesSchema, "SELECT * FROM sales")
+
+# Expand events to daily rows, then join to daily sales
+promo_sales = (
+    events_df
+    .with_columns(
+        pl.date_ranges(pl.col("date_from"), pl.col("date_to"), interval="1d").alias("date")
+    )
+    .explode("date")
+    .join(
+        sales_df.select(["date", "regional_product_id", "portal_platform_region",
+                         "gross_sales", "units_sold_directly"]),
+        on=["date", "regional_product_id", "portal_platform_region"],
+        how="inner",
+    )
+)
+```
+
+> **Note on `discount` values**: `1.0` = 100% off, `0.0` = no discount. Some portals may report `0.0` during a promo if they don't expose discount depth — use `event_name` and `date_from`/`date_to` to identify the event in that case.
+
+---
+
+### Wishlist & Visibility
+
+**Wishlist adds/removes at product level** → use `wishlist_actions`. It has `adds`, `deletes`, `purchases_and_activations`, `gifts`, and `is_promo_sale` per day per product per portal per country.
+
+**Wishlist cohort analysis** (how quickly do wishlisted users convert?) → use `wishlist_cohorts`. Group by `month_cohort` to see conversion rates over time.
+
+**Store page impressions and visits** → use `visibility`. It has `non_owner_visits`, `non_owner_impressions`, `owner_visits`, `owner_impressions`, broken down by `visit_source` (`"Direct Navigation"` or `"Visits from Impressions"`), `page_category`, and `page_feature`.
+
+**SKU-level visibility + wishlist combined** → use `visibility_wishlist_per_sku`. Useful when you need `human_name` or want to see data per individual SKU rather than per product.
+
+---
+
+## Step 3 — Check available tables, then fetch
+
+Not all tables are provisioned for every user. When the requested metric uses a table you're not sure about, check first:
+
+```python
+from dda_sdk import DuckDBClient
+with DuckDBClient() as client:
+    tables = client._conn.execute("SHOW TABLES").fetchall()
+    print([t[0] for t in tables])
+```
+
+If a table isn't listed, use mock data or tell the user it isn't in their plan.
+
+Use `DuckDBClient` for straightforward fetching. Pass the schema that matches the table you're reading — it validates the result. **Always use `SELECT *`** — partial column selects break schema validation (the schema needs all required fields present).
+
+**Push filters into the query, never fetch-all-then-filter.** The data lake is large — always pass date ranges, portal, product, and any other known filters directly in the `WHERE` clause (or as `.filter()` before `.collect()` for `PolarsClient`). Never fetch the full table and then filter in Polars. If the user says "January 2026", that goes into `WHERE date >= '2026-01-01' AND date <= '2026-01-31'`, not into a Polars `.filter()` after fetching everything. Aggregate in Polars after fetching, but filter before.
+
+```python
+import polars as pl
+from dda_sdk import DuckDBClient, SalesPerSkuSchema
+
+with DuckDBClient() as client:
+    df = client.query(
+        SalesPerSkuSchema,
+        """
+        SELECT *
+        FROM sales_per_sku
+        WHERE date >= '2026-01-01'
+          AND date <= '2026-01-31'
+          AND portal_platform_region = 'Steam:PC:Global'
+        """,
+    )
+
+# Aggregate in Polars after fetching
+monthly = (
+    df.group_by(pl.col("date").dt.truncate("1mo"))
+    .agg(pl.col("gross_sales").sum())
+    .sort("date")
+)
+```
+
+Alternatively use `PolarsClient` for larger date ranges (lazy evaluation reads only what you need):
+
+```python
+import polars as pl
+from dda_sdk import PolarsClient, SalesPerSkuSchema
+
+with PolarsClient() as client:
+    df = (
+        client.scan_table(SalesPerSkuSchema)
+        .filter(pl.col("date").is_between(pl.date(2026, 1, 1), pl.date(2026, 1, 31)))
+        .filter(pl.col("portal_platform_region").str.starts_with("Steam"))
+        .group_by(pl.col("date").dt.truncate("1mo"))
+        .agg(pl.col("gross_sales").sum())
+        .sort("date")
+        .collect()
+    )
+```
+
+Save the script as `<folder>/fetch.py` (using the folder created in Step 0) and run it. Print the result as JSON or a simple table so you can read the values and embed them in the chart.
+
+---
+
+## Step 4 — Design and generate the HTML chart
+
+Read the design system skill before writing any HTML: `.claude/skills/indiebi-design-system/SKILL.md`
+
+Use the `ui_kits/data-platform/overview.html` file in the design system as a reference for card layouts, chart styling, axis labels, and component patterns.
+
+### Choose the right chart type
+
+Don't default to a bar chart. Look at what the data is actually saying and pick the form that makes it easiest to read:
+
+| Data shape                                        | Best chart                                                       |
+| ------------------------------------------------- | ---------------------------------------------------------------- |
+| One metric over time (single platform)            | **Line chart** — shows trend and momentum clearly                |
+| One metric over time, comparing 2–4 platforms     | **Multi-line chart** or **grouped bar chart**                    |
+| Distribution across categories at a point in time | **Bar chart** (horizontal if labels are long, vertical if short) |
+| Part-to-whole (platform share, revenue breakdown) | **Stacked bar** or **donut/pie** (pie only if ≤5 slices)         |
+| Ranking (top countries, top titles)               | **Horizontal bar chart** — easiest to scan a ranked list         |
+| Two metrics at once (e.g. revenue vs. units)      | **Dual-axis line** or **bar + line combo**                       |
+| A single aggregate number the user asked for      | **Big number + context line** — no chart needed                  |
+
+When in doubt: if it's "over time" → line. If it's "across categories" → bar. If it's "share of total" → stacked or pie.
+
+### Decide whether KPI tiles add value
+
+KPI tiles (the big number cards above the chart) are useful when they answer a question the chart alone doesn't — like the total, the change vs. prior period, or the single most important takeaway. But they're not always the right call:
+
+- **Include KPIs when**: the user asked a summary question ("how much did we make?"), or when the top-line number isn't obvious from the chart shape alone.
+- **Skip KPIs when**: the chart already tells the full story (e.g. a simple ranking of 5 countries), or they'd just duplicate what's on the axes.
+
+When you do include KPIs, pick the ones that are actually meaningful for the specific request — don't default to total / peak / average every time. Think about what would be most useful:
+
+| Request type             | Useful KPIs                                                             |
+| ------------------------ | ----------------------------------------------------------------------- |
+| Annual/period revenue    | Total, best month, MoM change in last month                             |
+| Platform comparison      | #1 platform + its share, combined total                                 |
+| Country ranking          | Top country, top country's % of total, number of countries contributing |
+| Trend / growth           | Starting value, ending value, total % change over period                |
+| Event / promo impact     | Avg discount %, event count, best-performing event name                 |
+| Promo calendar / history | Events run, avg promo length, time since last promo                     |
+
+### Visual rules (always apply)
+
+1. **Import the CSS**: `<link rel="stylesheet" href="../../.claude/skills/indiebi-design-system/colors_and_type.css">`  
+   (adjust relative path based on where the HTML lives)
+2. **Dark theme by default**: `background: var(--theme-00)`, cards on `var(--theme-02)`
+3. **Bar colors**:
+   - Single-platform: `fill: var(--primary-lavender); opacity: 0.75`, peak bar in `var(--primary-orange)`
+   - Multi-platform: use portal brand colors — `var(--portal-steam)`, `var(--portal-gog)`, `var(--portal-nintendo)`, etc. Never use generic colors when platforms are being compared.
+4. **Axis labels**: 9px monospace, `rgba(255,255,255,.35)`
+5. **Platform icons**: use `assets/platforms/<name>.svg` from the design system whenever a storefront is named. Render as `<img>` with `filter: brightness(0) invert(1)` so they appear white on dark backgrounds. Never use emoji or text-only labels for storefronts.
+
+### SVG charts — baking in data
+
+All data values go directly into the SVG markup — no JavaScript needed. For bar/line charts:
+
+- Set `max_value` to a round number slightly above your actual max (e.g. if max is $1.14M, use $1.2M) so bars don't touch the top
+- `chart_height = 150` (y goes from 30 at top to 180 at baseline)
+- `bar_height = value / max_value * chart_height`
+- `y = 180 - bar_height`
+- Grid lines at 25%, 50%, 75%, 100% of max
+
+For line charts, compute `cx` and `cy` for each point and connect with a `<polyline>` or `<path>`.
+
+Write the HTML to `<folder>/chart.html`, then open it:
+
+```bash
+open <folder>/chart.html
+```
+
+---
+
+## Dimension tables
+
+The following tables are **dimension tables** — they serve as lookup/filter tables for the fact tables (`sales`, `sales_per_sku`, `events`, `wishlist_actions`, `visibility`, etc.). Each has a single unique primary key column you can use to join or filter.
+
+| Table | Primary key | Use to get |
+| ----- | ----------- | ---------- |
+| `countries` | `country_code` | `country_name`, `region`, `currency_code` (country's local currency, reference/display only — see [Currency](#currency)) |
+| `currencies` | `currency_code` | `currency_name`, `symbol` |
+| `organizations` | `organization_id` | `organization_name` |
+| `portals` | `portal_platform_region` | `portal`, `display_portal`, `platform`, `store`, `region`, `latest_date` |
+| `products` | `regional_product_id` | `product_name`, `product_type`, `custom_group` |
+| `skus` | `unique_sku_id` | `human_name`, `sku_type`, `base_sku_id`, `release_date`, `product_type` |
+
+Dimension tables can also be joined to each other. For example, `currencies` joins to `countries` on `currency_code` to enrich country rows with currency symbols.
+
+---
+
+## Table relationships
+
+**The join rule:** when the same column name appears in two schema files, those tables can be joined on that column. No separate foreign-key docs needed — the shared name is the contract.
+
+Key shared columns and what they unlock:
+
+| Shared column                                    | Tables that have it                                          | What the join adds                                 |
+| ------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------- |
+| `country_code`                                   | `sales_per_sku`, `sales` ↔ `countries`                       | `country_name`, `region`, `currency_code`          |
+| `currency_code`                                  | `countries` ↔ `currencies`                                   | `currency_name`, `symbol`                          |
+| `regional_product_id`                            | `sales_per_sku`, `sales`, `events` ↔ `products`              | `product_name`, `product_type`                     |
+| `unique_sku_id`                                  | `sales_per_sku`, `engagements_per_sku` ↔ `skus`              | `human_name`, `sku_type`, `product_type`, `regional_product_id` |
+| `date` + `regional_product_id` + `portal_platform_region` | `visibility`, `wishlist_actions` ↔ `sales`          | Join traffic/wishlist data to daily sales          |
+| `portal_platform_region`                         | sales, events, wishlist, visibility tables ↔ `portals`       | `portal`, `display_portal`, `platform`, `region` as separate columns |
+| `organization_id`                                | `sales_per_sku`, `sales` ↔ `organizations`                   | `organization_name`                                |
+
+When you're not sure whether two tables share a column, read both schema files and compare the field names — if a name matches, join on it.
+
+---
+
+## All available tables
+
+Before writing any query, read the schema file for the table you plan to use — it is the authoritative source of column names and types. Column names change; this skill does not auto-update.
+
+| Schema class                    | SQL table name              | Schema file                                                                                       |
+| ------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------- |
+| `SalesPerSkuSchema`             | `sales_per_sku`             | `dda_sdk/schemas/sales_per_sku.py`                                                                |
+| `SalesSchema`                   | `sales`                     | `dda_sdk/schemas/sales.py`                                                                        |
+| `EngagementsPerSkuSchema`       | `engagements_per_sku`       | `dda_sdk/schemas/engagements_per_sku.py`                                                          |
+| `EventsSchema`                  | `events`                    | `dda_sdk/schemas/events.py`                                                                       |
+| `VisibilitySchema`              | `visibility`                | `dda_sdk/schemas/visibility.py`                                                                   |
+| `VisibilityWishlistPerSkuSchema`| `visibility_wishlist_per_sku` | `dda_sdk/schemas/visibility_wishlist_per_sku.py`                                                |
+| `WishlistActionsSchema`         | `wishlist_actions`          | `dda_sdk/schemas/wishlist_actions.py`                                                             |
+| `WishlistCohortsSchema`         | `wishlist_cohorts`          | `dda_sdk/schemas/wishlist_cohorts.py`                                                             |
+| `BaselineSchema`                | `baseline`                  | `dda_sdk/schemas/baseline.py`                                                                     |
+| `ProductsSchema`                | `products`                  | `dda_sdk/schemas/products.py`                                                                     |
+| `SkusSchema`                    | `skus`                      | `dda_sdk/schemas/skus.py`                                                                         |
+| `CountriesSchema`               | `countries`                 | `dda_sdk/schemas/countries.py` — join to sales tables on `country_code` for geographic breakdowns |
+| `CurrenciesSchema`              | `currencies`                | `dda_sdk/schemas/currencies.py` — join to `countries` on `currency_code`                          |
+| `OrganizationsSchema`           | `organizations`             | `dda_sdk/schemas/organizations.py`                                                                |
+| `PortalsSchema`                 | `portals`                   | `dda_sdk/schemas/portals.py` — PK: `portal_platform_region`; use `display_portal` for report labels |
+
+Import any schema: `from dda_sdk import DuckDBClient, SalesPerSkuSchema, PortalsSchema`