@thinkingai/ae-cli 6.0.30 → 6.0.31

package/skills/ae-analysis/references/adhoc_export.md

@@ -0,0 +1,71 @@
+# analysis adhoc export
+
+Submit one unified ad-hoc analysis export from an AI-facing model definition.
+
+Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `export` command instead of `adhoc run`.
+
+## Command
+
+```bash
+ae-cli analysis adhoc export \
+  --project-id <project_id> \
+  --model-type <model_type> \
+  --definition '<json>' \
+  [--request-id cli_<32 lowercase hex>] \
+  [--use-cache true|false] \
+  [--zone-offset <hours>] \
+  [--fields '["列名"]'] \
+  [--artifact-format jsonl|csv] \
+  [--timeout-seconds <n>]
+```
+
+## AI models
+
+Read [`ai_models.md`](ai_models.md) for the single 12-model `model_type` registry, AI-facing `definition`, and SQL dynamic params contract.
+
+For SQL model definitions, do not invent table or column names. If the table is unknown, call `analysis sql-table list --project-id <project_id>`; then inspect the selected `table_ref` with `analysis sql-table columns --project-id <project_id> --table-ref <table_ref>` before writing SQL.
+
+## Definition contract
+
+Rules:
+
+- `export` does not accept `--limit` or `--offset`; use `--fields` for column projection and download the full artifact.
+
+## Input
+
+- `--project-id`: target project ID.
+- `--model-type`: one of the 12 AI-facing model names from [`ai_models.md`](ai_models.md). Do not pass `scenario`, `history_tag`, or `cluster`; tags and cohorts/clusters are separate capabilities.
+- `--definition`: model-specific AI-facing definition JSON.
+- `--artifact-format`: `jsonl` or `csv`.
+
+Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+
+Do not use raw QP, `events`, `event_view`, `visual_view`, removed ad-hoc QP builder outputs, or schema helper outputs as `--definition`.
+
+## Output
+
+The response is an async artifact descriptor:
+
+- `run_id`: poll or cancel this run.
+- `artifact_id`: download this artifact after completion.
+- `status` / `artifact_status`: initial lifecycle states.
+- `format`: actual logical artifact format (`jsonl` or `csv`).
+- `compression` / `content_encoding`: actual compression/encoding; analysis ad-hoc exports currently return `gzip`.
+- `file_name` / `content_type`: actual downloadable file contract. Do not infer compression from `--artifact-format` alone.
+- `expires_at` / `expires_at_iso`: artifact expiration.
+- `effective_timeout_seconds`, `timeout_source`, `deadline_at`: effective lifecycle policy.
+- `query_context_id` / `query_context_expires_at`: reusable follow-up context when Redis context creation succeeds.
+
+Preserve the `run_id` and `artifact_id` from this exact submit response as one pair. Do not infer either ID from a path or reuse an ID from another export.
+
+Use:
+
+```bash
+ae-cli analysis run inspect --run-id <run_id>
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>
+ae-cli analysis query cancel --run-id <run_id>
+```
+
+If query execution fails, `run inspect` reaches `FAILED`; it must not produce a completed empty artifact. Download only after the successful terminal states documented in `analysis_data_retrieval.md`.
+
+Use the submit response `query_context_id` immediately with `analysis drilldown-users run` or `analysis query create-result-cluster` when present. JSONL artifacts repeat query context plus `format`, `compression`, `content_type`, and `content_encoding` in the first metadata line. Source metadata includes `effective_time_range`, `time_range_adjustments`, and `clipping_reasons`. Date rows expose stable `drilldown_date` and separate `display_date`; copy only `drilldown_date` into a drilldown target. CSV remains pure CSV and carries context/format metadata only in the submit and run-inspect descriptors. Do not pass raw QP.

package/skills/ae-analysis/references/adhoc_run.md

@@ -0,0 +1,58 @@
+# analysis adhoc run
+
+Run one unified ad-hoc analysis inline query from an AI-facing model definition.
+
+Use this command for AI-facing ad-hoc model analysis. Do not use removed ad-hoc QP builder or schema helper commands.
+
+Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `adhoc export`.
+
+## Command
+
+```bash
+ae-cli analysis adhoc run \
+  --project-id <project_id> \
+  --model-type <model_type> \
+  --definition '<json>' \
+  [--request-id cli_<32 lowercase hex>] \
+  [--use-cache true|false] \
+  [--zone-offset <hours>] \
+  [--fields '["列名"]'] \
+  [--limit <n>] \
+  [--timeout-seconds <n>]
+```
+
+## AI models
+
+Read [`ai_models.md`](ai_models.md) for the single 12-model `model_type` registry, AI-facing `definition`, and SQL dynamic params contract.
+
+For SQL model definitions, do not invent table or column names. If the table is unknown, call `analysis sql-table list --project-id <project_id>`; then inspect the selected `table_ref` with `analysis sql-table columns --project-id <project_id> --table-ref <table_ref>` before writing SQL.
+
+## Input
+
+- `--project-id`: target project ID.
+- `--model-type`: one of the 12 AI-facing model names from [`ai_models.md`](ai_models.md). Do not pass `scenario`, `history_tag`, or `cluster`; tags and cohorts/clusters are separate capabilities.
+- `--definition`: model-specific AI-facing definition JSON.
+
+Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+
+If the user asks for more than 1000 rows, or the SQL text requests `LIMIT 2000` (or any limit above 1000), go directly to `analysis adhoc export`. Do not lower the SQL limit to 1000, run a truncated sync query first, or loop over repeated `run` calls.
+
+Do not use raw QP, `events`, `event_view`, `visual_view`, removed ad-hoc QP builder outputs, or schema helper outputs as `--definition`.
+
+## Output
+
+The response may include:
+
+- `query_context_id`: Redis-backed context for drilldown or result-cluster creation.
+- `drilldown_available`: whether the response contains a complete machine-readable follow-up target. When false, read `drilldown_unavailable_reason` and do not infer a target from display text.
+- `sources[].target_contract.default_target`: a complete target that can be passed directly to a follow-up command. Copy and replace only fields named by `copy_from_selected_result` when drilling into a different row or cell.
+- `title` / `rows` / `total` / `returned_rows` / `truncated`: tabular preview fields. When truncated, use `adhoc export`; there is no next-page request.
+- `result`: direct result for non-tabular models.
+- `request_id`: lifecycle request id.
+- `effective_time_range`: the resolved query scope actually sent to execution. `clipping_reasons` is empty when the gateway applied no range cap.
+- `data_time_range`: the minimum/maximum machine dates present in returned rows when available. Compare it with `effective_time_range` to distinguish query-range clipping from missing data.
+- `row_metadata`: row-aligned machine fields. For date-drilldown rows, copy `drilldown_date`; `display_date` is presentation text only.
+
+Execution failures are returned as command failures with `request_id`; only the explicit project-no-data condition is a successful empty result. Do not interpret an empty object as evidence that a failed query succeeded.
+
+Use `query_context_id` with `analysis drilldown-users run` or `analysis query create-result-cluster` only when `drilldown_available=true` and the selected source includes `target_contract.default_target`. Do not pass raw QP or infer a target from display text.

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

@@ -0,0 +1,459 @@
+# Analysis AI-facing models
+
+This file is the single reference for `model_type` spelling and AI-facing `definition` shape.
+
+## Capability coverage
+
+- `analysis adhoc run/export`: supports the 12 analysis models only.
+- `analysis report create/update`: supports the same 12 analysis models plus `tag` for saved tag report data.
+- `analysis report-data run/export`, `analysis dashboard-report-data run/export`, and `analysis bi-panel-page-data run/export`: execute existing saved assets. They do not accept `model_type`; use their own command references.
+
+Do not pass raw QP, `events`, `eventView`, `visualView`, frontend DTOs, schema-generated payloads, `scenario`, `history_tag`, or `cluster` as AI-facing `definition` or `model_type`.
+
+## Model type registry
+
+Common analysis models (9):
+
+- `event`: event analysis
+- `retention`: retention analysis
+- `funnel`: funnel conversion analysis
+- `distribution`: distribution analysis
+- `attribution`: attribution analysis
+- `interval`: interval analysis
+- `path`: path analysis
+- `prop_analysis`: property analysis
+- `sql`: SQL analysis
+
+Scenario analysis models (3):
+
+- `heat_map`: heat map analysis
+- `rank_list`: ranking analysis
+- `revenue`: revenue analysis
+
+Report write only:
+
+- `tag`: saved tag report data. Use this spelling in CLI.
+
+## Common building blocks
+
+Time range:
+
+```json
+{"mode":"previous","unit":"day","value":7}
+```
+
+- `mode`: `recent`, `previous`, `custom`, `start_to_today`, or `start_to_yesterday`.
+- `recent` includes today/current unit; `previous` excludes today/current unit.
+- For `custom`, pass `start_time` and `end_time`.
+
+Chinese natural-language time mapping (mandatory; do not infer a different mode):
+
+| User wording | `time_range` input | Builder QP | Includes today |
+|---|---|---|---|
+| 最近7天 / 近7天 | `{"mode":"recent","unit":"day","value":7}` | `recentDay=0-7` | 是 |
+| 过去7天 / 前7天 / 上7天 | `{"mode":"previous","unit":"day","value":7}` | `recentDay=1-7` | 否 |
+| 今天 | `{"mode":"recent","unit":"day","value":1}` | `recentDay=0-1` | 是 |
+| 昨天 | `{"mode":"previous","unit":"day","value":1}` | `recentDay=1-1` | 否 |
+
+If the user explicitly says whether today is included, that explicit requirement overrides the phrase mapping. Relative dates are resolved at query time using the effective project/user timezone; do not invent absolute dates.
+
+Field reference:
+
+```json
+{"field":{"name":"country","type":"user_property"}}
+```
+
+- `type` can be `event_property`, `user_property`, `cluster`, or `tag`.
+- Omit `type` only when the field name is unambiguous.
+- `prop_analysis` dimensions and filters support `user_property`, `cluster`, and `tag`; they do not support `event_property`.
+
+Filter:
+
+```json
+{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}
+```
+
+- Operators include `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `exists`, `not_exists`, `between`, `contains`, and `not_contains`.
+- Omit `values` for `exists` and `not_exists`.
+- Use exactly two values for `between`.
+
+Group:
+
+```json
+{"field":{"name":"country","type":"user_property"}}
+```
+
+Metric aggregation values should use semantic spelling, not internal A-codes:
+
+- Count-like: `total_count`, `user_count`, `per_user_count`, `count`, `active_days`, `active_hours`
+- Property-like: `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `percentile`
+
+## Model definitions
+
+### `event`
+
+Use for event metrics, trends, grouping, filters, and comparisons.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "time_particle_size": "day",
+  "metrics": [
+    {"event": "login", "aggregation": "user_count"}
+  ],
+  "groups": [
+    {"field": {"name": "country", "type": "user_property"}}
+  ],
+  "filters": [
+    {"field": {"name": "country", "type": "user_property"}, "operator": "eq", "values": ["US"]}
+  ],
+  "relation": "and"
+}
+```
+
+Property aggregation example:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "metrics": [
+    {"event": "purchase", "aggregation": "sum", "property": "amount"}
+  ]
+}
+```
+
+Formula metric example:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "metrics": [
+    {
+      "formula": "revenue / users",
+      "dependencies": [
+        {"alias": "revenue", "event": "purchase", "aggregation": "sum", "property": "amount"},
+        {"alias": "users", "event": "login", "aggregation": "user_count"}
+      ]
+    }
+  ]
+}
+```
+
+### `retention`
+
+Use for retained/lost users from an initial event to a return event.
+
+```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": "rate",
+    "groups": [
+      {"field": {"name": "channel", "type": "user_property"}}
+    ]
+  }
+}
+```
+
+Use `stat_type=lost` for lost-user analysis. Use `rtn_rate_or_num=count` when the user asks for user counts instead of rates.
+
+### `funnel`
+
+Use for ordered conversion steps with a conversion window.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "time_particle_size": "day",
+  "funnel": {
+    "steps": [
+      {"event": "view_product"},
+      {"event": "add_to_cart"},
+      {"event": "purchase"}
+    ],
+    "window": {"value": 3, "unit": "day"},
+    "groups": [
+      {"field": {"name": "channel", "type": "user_property"}}
+    ]
+  }
+}
+```
+
+If the user asks to match users across events by a shared event property, set `relation_event_property_name`.
+
+### `distribution`
+
+Use for user distribution buckets for an event or property metric.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "distribution_metrics": [
+    {
+      "event": "purchase",
+      "aggregation": "sum",
+      "property": "amount",
+      "interval_type": "user_defined",
+      "quota_interval_arr": [100, 1000, 10000]
+    }
+  ],
+  "groups": [
+    {"field": {"name": "country", "type": "user_property"}}
+  ]
+}
+```
+
+Use `interval_type=def` for automatic buckets, `user_defined` for explicit numeric boundaries, and `discrete` to group by raw values.
+
+### `attribution`
+
+Use to attribute target conversions to touchpoint/source events.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 14},
+  "attribution": {
+    "target_event": "purchase",
+    "target_aggregation": "user_count",
+    "attribution_events": [
+      {"event": "ad_click"},
+      {"event": "campaign_view"}
+    ],
+    "attribution_model": "first",
+    "window": {"value": 7, "unit": "day"},
+    "direct_conversion": true
+  }
+}
+```
+
+`attribution_model` values: `first`, `last`, or `linear`.
+
+### `interval`
+
+Use for elapsed-time analysis between an initial event and a return event.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "time_particle_size": "day",
+  "interval": {
+    "initial_event": "register",
+    "return_event": "first_purchase",
+    "window": {"value": 7, "unit": "day"},
+    "groups": [
+      {"field": {"name": "channel", "type": "user_property"}}
+    ]
+  }
+}
+```
+
+### `path`
+
+Use for behavior paths before or after a source event.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "filters": [
+    {"field": {"name": "account_id", "type": "user_property"}, "operator": "exists"}
+  ],
+  "relation": "and",
+  "path": {
+    "source_event": "purchase",
+    "included_events": ["view_product", "add_to_cart", "purchase"],
+    "session_interval": 30,
+    "session_unit": "minute",
+    "direction": "forward"
+  }
+}
+```
+
+`direction=forward` asks what users do after `source_event`; `direction=backward` asks what users did before it. Do not send original-QP fields such as `source_type` or `event_names`.
+
+Path `filters` are global member filters compiled to the original QP `user_filter`. They support `user_property`, `cluster`, and `tag`, but not `event_property`. Do not move a user filter into the source event's event-property filter.
+
+For every non-SQL intent model, do not call `list_events` or `list_properties` as an execution prerequisite. The successful response must expose every internally resolved event/property in `resolved`, including `input`, `resolved_name`, `match_type`, and `path`. Use metadata discovery only after a structured `need_clarification` response or an explicit resolution capability error.
+
+### `prop_analysis`
+
+Use for user-property metrics, grouping, filters, and user-crowd comparison.
+
+```json
+{
+  "prop_analysis": {
+    "metric": {"aggregation": "user_count"},
+    "groups": [
+      {"field": {"name": "country", "type": "user_property"}}
+    ],
+    "filters": [
+      {"field": {"name": "vip_level", "type": "user_property"}, "operator": "gte", "values": ["3"]}
+    ],
+    "user_crowds": [
+      {
+        "name": "US users",
+        "filters": [
+          {"field": {"name": "country", "type": "user_property"}, "operator": "eq", "values": ["US"]}
+        ]
+      }
+    ]
+  }
+}
+```
+
+For property aggregations, pass the user property:
+
+```json
+{"prop_analysis":{"metric":{"aggregation":"distinct_count","property":"account_id"}}}
+```
+
+### `sql`
+
+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"}
+```
+
+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"}
+  ]
+}
+```
+
+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}`. A selector's `value` must equal one of its `options[].value` values. `${PartDate:name}` expands to a complete predicate, so place it directly after `WHERE`/`AND` rather than after a column name.
+- Do not pass SQL-IDE internals such as `sqlVoParams`, `sqlViewParams`, `paramType`, `paramName`, `paramExpress`, `commonFilter`, or `requiredEvents`.
+- Delimit any Trino identifier containing `#`, `$`, `@`, spaces, or punctuation with double quotes, for example `"#user_id"` and `"$part_event"`. 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. If the table is unknown, call `analysis sql-table list --project-id <project_id>` and select an exact returned `table_ref`. Then use `analysis sql-table columns --project-id <project_id> --table-ref <table_ref>` before writing SQL. Ask the user only when multiple authorized tables remain semantically plausible after discovery.
+- For a saved dynamic SQL report, put the default values in `analysis report create/update --definition`. Verify the default once with `analysis report-data run` without `--sql-params`, then verify a changed value with one value-only `--sql-params` override.
+- 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.md` and `user_cluster_models.md`.
+
+### `heat_map`
+
+Use for two-dimensional heat map analysis based on numeric event coordinate properties.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "heat_map": {
+    "hot_event": "click",
+    "hot_aggregation": "total_count",
+    "x_prop": "screen_x",
+    "y_prop": "screen_y",
+    "filters": [
+      {"field": {"name": "page", "type": "event_property"}, "operator": "eq", "values": ["home"]}
+    ]
+  }
+}
+```
+
+For property metrics, set `hot_property` and use a property aggregation such as `sum` or `avg`.
+
+### `rank_list`
+
+Use for ranking users/entities by an event metric.
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "rank_list": {
+    "rank_dimension": {"field": {"name": "#account_id", "type": "user_property"}},
+    "rank_event": "purchase",
+    "rank_aggregation": "sum",
+    "rank_property": "amount",
+    "rank_type": "dense_rank",
+    "order_by": "DESC"
+  }
+}
+```
+
+`rank_type` values: `rank`, `dense_rank`, or `row_rank`.
+
+### `revenue`
+
+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`.
+
+### `tag` report write only
+
+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.