@thinkingai/ae-cli 6.1.20 → 6.1.23

package/skills/ae-analysis/references/ai_models/retention.md

@@ -0,0 +1,70 @@
+# `retention` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for retained/lost users from an initial event to a return event.
+
+For a rate aggregated across cohorts or entry-date windows, request `rtn_rate_or_num=count`, even when the user asks for a rate. Compute `sum(Dn return counts) / sum(initial counts)` over the same selected cohort set. Use `rate` when directly displaying a returned rate without regrouping it.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "time_particle_size": "day",
+  "retention": {
+    "initial_event": "register",
+    "return_event": "login",
+    "stat_type": "retention",
+    "unit_num": 1,
+    "rtn_rate_or_num": "count",
+    "groups": [
+      {"field": {"name": "channel", "type": "user_property"}}
+    ]
+  }
+}
+```
+
+Use `stat_type=lost` for lost-user analysis. User-count requests also use `count`. The initial `time_range` defines cohort entry dates, not the full return-observation range. For D1, use day grain and `unit_num=1`; the last initial day needs the next complete project day of return data. Keep the initial window unchanged.
+
+For a comparison across entry-date windows, one daily retention query can cover their combined entry range; partition its count rows by the requested dates locally. Use `rtn_rate_or_num=count` to obtain each cohort's denominator and D1 numerator. Read the actual titles and metric labels; count/rate rows and stage totals are separate. Do not query initial counts again when these rows already answer the same cohort-count question. Cohort counts do not replace distinct users across the entire period. No data-arrival watermark is guaranteed: unknown maturity stays unknown, and repeating the same query cannot establish it.
+
+Initial-event and return-event property filters use the retention-specific shape below. Put them inside `retention`; use `event_property_name` instead of a generic `field` object. Do not use top-level `filters`, `retention.filters`, or `initial_event_filters`.
+
+```json
+{
+  "time_range": {"mode": "custom", "start_time": "2026-08-18 00:00:00", "end_time": "2026-08-18 23:59:59"},
+  "time_particle_size": "day",
+  "retention": {
+    "initial_event": "register",
+    "initial_filters": [
+      {"event_property_name": "case_id", "operator": "eq", "values": ["retention_test"]}
+    ],
+    "initial_filter_relation": "and",
+    "return_event": "login",
+    "return_filters": [
+      {"event_property_name": "case_id", "operator": "eq", "values": ["retention_test"]}
+    ],
+    "return_filter_relation": "and",
+    "stat_type": "retention",
+    "unit_num": 1,
+    "rtn_rate_or_num": "rate",
+    "groups": [
+      {"field": {"name": "channel", "type": "event_property"}}
+    ]
+  }
+}
+```
+
+## Aggregation
+
+- `retention` simultaneous metrics: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support only `sum` and `avg_per_user`; boolean properties support only `true_count`, `false_count`, `not_empty_count`, and `empty_count`.
+
+## Returned rows
+
+If retention result files already exist, the optional shared [result reader](../analysis_data_retrieval.md#preserve-and-interpret-results) preserves the columns and row types together. A day-grain D1 result can look like this (illustrative values; use the actual returned titles and metric labels):
+
+| Date | Initial users | Metric | D0 | D1 |
+| --- | ---: | --- | ---: | ---: |
+| <entry date> | 100 | <count label> | 100 | 30 |
+| <entry date> | 100 | <rate label> | 100% | 30% |
+
+Here D1 is the fifth column; the fourth is D0. Grouping and longer intervals change the columns. Select the requested Dn by title, and daily count rows by date and metric label. Stage summaries are separate rows. If the local view omits a needed date or column, read it from the saved file before deciding whether another query is needed.

package/skills/ae-analysis/references/ai_models/revenue.md

@@ -0,0 +1,28 @@
+# `revenue` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for revenue cohort metrics such as LTV, ROI, revenue, and cost.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 30},
+  "initial_event": {"event": "register"},
+  "pay_event": {"event": "purchase"},
+  "revenue_metric": {"event": "purchase", "aggregation": "sum", "property": "amount"},
+  "cost_metric": {"event": "ad_cost", "aggregation": "sum", "property": "cost"},
+  "observation_days": 14,
+  "selected_metrics": ["payAmount", "ltv", "roi"],
+  "groups": [
+    {"field": {"name": "channel", "type": "user_property"}}
+  ]
+}
+```
+
+`cost_metric` is optional when the user does not ask for cost/ROI.
+`selected_metrics` supports `payUsers`, `payAmount`, `cumPayUsers`, `cumPayAmount`, `payRate`, `cumPayRate`, `ltv`, `ltvMultiple`, and `roi`.
+Select at most four metrics per query. The revenue service keeps only the first four supported selections and removes ROI when cost is absent. If more metrics are required, split the selections into non-overlapping batches with the same definition and scope, then join results by verified cohort/group keys. Check returned titles for every requested metric; a successful response alone does not prove full metric coverage.
+
+## Aggregation
+
+- `revenue`: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`. `percentile` is not supported.

package/skills/ae-analysis/references/ai_models/sql.md

@@ -0,0 +1,74 @@
+# `sql` AI-facing definition
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use for SQL analysis. The AI-facing model has only:
+
+- `sql`: required SQL text.
+- `params`: optional dynamic parameter values and definitions, required only when SQL contains `${...}` placeholders.
+
+Simple SQL:
+
+```json
+{"sql":"SELECT 1 AS value"}
+```
+
+Trino special identifiers must use double-quoted identifier delimiters:
+
+```json
+{"sql":"SELECT \"#user_id\", \"$part_event\" FROM hive.ta.v_event_1 WHERE \"$part_date\" BETWEEN '2026-07-01' AND '2026-07-07' LIMIT 20"}
+```
+
+Reserved words used as identifiers must also be double quoted, for example `SELECT "end" FROM ...`.
+
+For multiline SQL JSON, ensure JSON decoding produces a real line break in the `sql` value. Do not submit a literal `\\n` sequence outside a quoted SQL string value; use a JSON escape that the caller decodes once before invoking the capability.
+
+Event-table queries must include a date-partition predicate on the quoted `"$part_date"` column. The backend rejects SQL against an event table when this predicate is absent. This requirement is specific to event tables; do not invent a `$part_date` condition for a table whose discovered columns do not include it.
+
+Typed condition-fragment placeholder:
+
+```json
+{
+  "sql": "select * from events where country ${Text:country}",
+  "params": [
+    {"name": "country", "type": "text", "operator": "eq", "value": "US"}
+  ]
+}
+```
+
+Raw variable placeholder:
+
+```json
+{
+  "sql": "select * from events where country = ${country}",
+  "params": [
+    {"name": "country", "type": "variable", "value": "'US'"}
+  ]
+}
+```
+
+Time placeholder:
+
+```json
+{
+  "sql": "select * from events where ${PartDate:ds}",
+  "params": [
+    {"name": "ds", "type": "part_date", "recent_day": "1-7", "use_timezone": true}
+  ]
+}
+```
+
+Rules:
+
+- If SQL has no `${...}` placeholder, omit `params`.
+- If SQL has placeholders, every placeholder must have one matching item in `params`.
+- Raw variables use `${name}`, not `${Variable:name}`. When creating or updating a selector definition, its saved default `value` must equal one of its `options[].value` SQL fragments. This definition-time rule is different from executing a saved report: `analysis report-data run|export --sql-params` must put the exact `options[].name` UI label in the runtime override's `value`, never the SQL fragment from `options[].value`. `${PartDate:name}` expands to a complete predicate, so place it directly after `WHERE`/`AND` rather than after a column name.
+- A `part_date` parameter must provide either `recent_day` or a complete custom range with both `start_time` and `end_time`; one-sided custom ranges are invalid.
+- `use_timezone` is an optional boolean definition field that is only valid for `part_date`. It defaults to `false`. When `true`, that PartDate parameter uses the query's effective timezone selected by `zone_offset` or the current user/project default; when `false`, it follows the non-timezone-aware PartDate path. This is distinct from the command-level `zone_offset`.
+- Do not pass SQL-IDE internals such as `sqlVoParams`, `sqlViewParams`, `paramType`, `paramName`, `paramExpress`, `commonFilter`, or `requiredEvents`.
+- Delimit any Trino identifier containing `#`, `$`, `@`, spaces, punctuation, or a reserved word with double quotes, for example `"#user_id"`, `"$part_event"`, and `"end"`. Single quotes create string literals, not identifiers. Escape a literal double quote inside an identifier by doubling it. The CLI preserves the submitted SQL and does not rewrite identifiers.
+- For an event table, include a date-partition predicate on the discovered `"$part_date"` column, for example `WHERE "$part_date" BETWEEN '2026-07-01' AND '2026-07-07'`. The backend rejects event-table SQL without this condition.
+- Do not invent table or column names. For an unknown table, call `analysis sql-table list --project-id <project_id>` and select an exact authorized `table_ref`. Inspect columns with `analysis sql-table columns --project-id <project_id> --table-ref <table_ref>` before writing SQL; reuse already verified columns in the same scope. Keep `usage=analysis` for both calls. Ask only when authorized candidates remain ambiguous or the required source is unavailable.
+- For a saved dynamic SQL report, put the default values in `analysis report create/update --definition`. When data is requested, query once using the requested value-only `--sql-params` overrides, or omit that flag to use saved defaults.
+- `use_timezone` belongs to the saved parameter definition. To change it, update the report `definition`; never pass it through report-data `--sql-params`, which changes values only.
+- SQL tags and SQL clusters do not use this general parameter contract. They accept only `${PartDate:name}` with `type=part_date`, and their tables must be discovered with `analysis sql-table list/columns --usage tag_cluster`; see [user tag models](../user_tag_models.md) and [user cluster models](../user_cluster_models.md).

package/skills/ae-analysis/references/ai_models/tag.md

@@ -0,0 +1,19 @@
+# `tag` AI-facing definition (report write only)
+
+Shared input: [common building blocks](../ai_models.md#common-building-blocks).
+
+Use only with `analysis report create/update`; do not use with `analysis adhoc run/export`.
+
+`tag_name` is the only tag-report name field. Do not send `cluster_name` for a tag report; `cluster_name` belongs only to audience-cluster commands.
+
+```json
+{
+  "tag": {
+    "tag_name": "vip_users",
+    "time_range": {"mode": "recent", "unit": "day", "value": 7},
+    "time_particle_size": "day"
+  }
+}
+```
+
+Prefer `time_range` for new tag reports. `recent_day`, `start_time`, and `end_time` are only for report readback or precise round-trip updates.