@clickzetta/cz-cli-darwin-arm64 0.5.16 → 0.5.17

package/bin/skills/lakehouse-doc-en/references/open-api-overview.md

@@ -0,0 +1,96 @@
+# Open API Overview
+
+## What Is This
+
+The Open API lets you call Analytics Agent's data analysis capabilities through standard HTTP interfaces. You simply send a natural language question, and the system automatically handles data querying, metric calculation, knowledge retrieval, and visualization generation, returning structured analysis results.
+
+In short: **it turns Analytics Agent's conversational capabilities into a programmable interface**.
+
+## Use Cases
+
+| Use Case | Description |
+|----------|-------------|
+| Embed in internal systems | Integrate data Q&A capabilities into your business systems. Users ask questions in natural language, and the backend calls the API asynchronously to retrieve and display analysis results. |
+| Automated workflows | Connect the API to automated processes. Trigger data analysis on a schedule or by events, retrieve structured results, and let your system handle subsequent processing (e.g., generate reports, write to a database). |
+| Custom application integration | Call the Agent's analysis capabilities from your own BI tools or data platforms to retrieve metric calculation results and SQL, which your application then renders and displays. |
+
+## What You Get
+
+After calling the API, you receive the same analysis process and results as asking a question on the Analytics Agent page, including:
+
+- **Knowledge retrieval results** — Business rules and definition entries returned by the Agent after consulting the knowledge base
+- **Metric calculation results** — Semantic layer DSL (metricDsl) and physical layer DSL (physicalMetricDsl)
+- **SQL statements** — Query SQL generated by the Agent (which you can execute in your system to retrieve data)
+- **Chart metadata** — Chart type, column definitions, and corresponding SQL (your application must execute the SQL and render the chart)
+- **Analysis summary** — A text summary in Markdown format with data interpretation
+
+> Note: The API returns analysis process data and structured results. Presentation-layer tasks such as chart rendering and report formatting must be completed by your application.
+
+## 5-Minute Quick Start
+
+For a complete end-to-end example, see → [Quick Start](open-api-quick-start)
+
+The core flow is just 4 steps:
+
+```text
+① Get Token → ② Create Session → ③ Ask Question → ④ Poll for Results
+```
+
+Minimal code (Python):
+
+```python
+import requests, time
+
+BASE = "https://api.clickzetta.com/clickzetta-campaign-data"  # Domestic SaaS environment
+SECRET_KEY = "your_app_secret_key"
+
+# ① Get Token
+token = requests.get(f"{BASE}/open/api/v1/appSecretKey/generateAuthToken",
+                     params={"appSecretKey": SECRET_KEY}).json()["data"]["token"]
+
+# ② Create Session
+session_id = requests.post(f"{BASE}/open/session/safe_new",
+    params={"tenantId": 10, "userId": 1, "loginToken": token},
+    json={"tenantId": 10, "userId": 1, "domainId": 106,
+          "title": "API Test", "loginToken": token}
+).json()["data"]
+
+# ③ Ask Question
+question_id = requests.post(f"{BASE}/open/text2insight/query",
+    params={"tenantId": 10, "userId": 1, "loginToken": token},
+    json={"tenantId": 10, "userId": 1, "domainId": 106,
+          "sessionId": session_id, "msg": "Sales trend by region for the past 6 months", "loginToken": token}
+).json()["data"]["questionId"]
+
+# ④ Poll for Results
+while True:
+    result = requests.post(f"{BASE}/open/safe_question_poll",
+        params={"tenantId": 10, "userId": 1, "loginToken": token},
+        json={"tenantId": 10, "userId": 1, "domainId": 106,
+              "questionId": question_id, "loginToken": token}
+    ).json()
+    responses = result["data"]["responses"]
+    last_type = responses[-1].get("dataType", "")
+    if last_type in ("finish", "finish_stop", "error"):
+        break
+    time.sleep(2)
+
+# Print final results
+for r in responses:
+    print(f"[{r.get('dataType')}] {r.get('message', '')[:80]}")
+```
+
+## API Interface List
+
+| Interface | Description | Required |
+|-----------|-------------|----------|
+| [GenerateAuthToken](open-api-generate-auth-token) | Obtain authentication Token | Yes |
+| [CreateSession](open-api-create-session) | Create a conversation session | No (can reuse an existing sessionId) |
+| [Text2InsightQuery](open-api-text2insight-query) | Submit a data analysis request | Yes |
+| [SafeQuestionPoll](open-api-safe-question-poll) | Poll for question results | Yes |
+| [Text2InsightStop](open-api-text2insight-stop) | Stop a running analysis task | No |
+
+## More Guides
+
+- [Quick Start](open-api-quick-start) — Complete end-to-end code examples (curl + Python)
+- [Understanding Response Results](open-api-response-guide) — Message type descriptions, display recommendations, and real output examples

package/bin/skills/lakehouse-doc-en/references/open-api-quick-start.md

@@ -0,0 +1,286 @@
+# Open API Quick Start
+
+> This guide helps you complete your first API call in 5 minutes, from asking a question to receiving analysis results.
+
+## Prerequisites
+
+Before you begin, prepare the following information:
+
+| Item | Description | How to Obtain |
+|------|-------------|---------------|
+| API Base URL | Base URL for interface requests | See the section below |
+| appSecretKey | Application secret key used to obtain an authentication Token | Generated by admin on the User Management page |
+| tenantId | Tenant ID | View on the Settings configuration page |
+| userId | User ID | View on the Settings configuration page |
+| domainId | Analytics domain ID | Obtained from the URL on the analytics domain settings page |
+
+### API Base URL
+
+| Environment | Base URL |
+|-------------|----------|
+| Domestic SaaS | `https://api.clickzetta.com/clickzetta-campaign-data` |
+| Overseas (Singapore) | `https://ap-southeast-1-alicloud.api.singdata.com/clickzetta-campaign-data` |
+| Private Deployment (OP) | Contact your implementation team; each environment differs |
+
+### Obtaining appSecretKey
+
+Go to **Admin → User Management**, select the corresponding user, click Edit, and in the "App Secret Key" section click + **Generate Key**.
+
+![](/.topwrite/assets/image_1780485364546.png =646)
+
+### Obtaining tenantId and userId
+
+Click the avatar in the bottom-left corner to go to the **Settings** configuration page:
+
+![](/.topwrite/assets/image_1780485505876.png =226)
+
+On the configuration page, you can see **Tenant ID** and **User ID**:
+
+![](/.topwrite/assets/image_1780485442238.png =294)
+
+### Obtaining domainId
+
+Click the settings button (gear icon) on the analytics domain card:
+
+![](/.topwrite/assets/image_1780485535438.png =298)
+
+On the settings page, look at the browser address bar URL — the number at the end is the **domainId**:
+
+![](/.topwrite/assets/image_1780485554164.png =481)
+
+## Complete Flow (curl)
+
+### Step 1: Get a Token
+
+For detailed parameters, see → [GenerateAuthToken](open-api-generate-auth-token)
+
+```bash
+curl "https://api.clickzetta.com/clickzetta-campaign-data/open/api/v1/appSecretKey/generateAuthToken?appSecretKey=YOUR_SECRET_KEY"
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiJ9..."
+  }
+}
+```
+
+Save the `data.token` value — it is required for all subsequent requests.
+
+### Step 2: Create a Session (Optional)
+
+For detailed parameters, see → [CreateSession](open-api-create-session)
+
+If you already have a sessionId, you can skip this step.
+
+```bash
+curl -X POST "https://api.clickzetta.com/clickzetta-campaign-data/open/session/safe_new?tenantId=YOUR_TENANT_ID&userId=YOUR_USER_ID&loginToken=YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenantId": YOUR_TENANT_ID,
+    "userId": YOUR_USER_ID,
+    "domainId": YOUR_DOMAIN_ID,
+    "title": "My First API Call",
+    "loginToken": "YOUR_TOKEN"
+  }'
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": 4729
+}
+```
+
+`data` is your `sessionId`.
+
+### Step 3: Ask a Question
+
+For detailed parameters, see → [Text2InsightQuery](open-api-text2insight-query)
+
+```bash
+curl -X POST "https://api.clickzetta.com/clickzetta-campaign-data/open/text2insight/query?tenantId=YOUR_TENANT_ID&userId=YOUR_USER_ID&loginToken=YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenantId": YOUR_TENANT_ID,
+    "userId": YOUR_USER_ID,
+    "domainId": YOUR_DOMAIN_ID,
+    "sessionId": YOUR_SESSION_ID,
+    "msg": "Show me the sales trend by region for the past 6 months",
+    "loginToken": "YOUR_TOKEN"
+  }'
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "questionId": 34339,
+    "sessionId": 4729,
+    "status": "running"
+  }
+}
+```
+
+Save the `data.questionId`.
+
+### Step 4: Poll for Results
+
+For detailed parameters, see → [SafeQuestionPoll](open-api-safe-question-poll)
+
+Call every 2 seconds until the `dataType` of the last message is `finish`, `finish_stop`, or `error`.
+
+```bash
+curl -X POST "https://api.clickzetta.com/clickzetta-campaign-data/open/safe_question_poll?tenantId=YOUR_TENANT_ID&userId=YOUR_USER_ID&loginToken=YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenantId": YOUR_TENANT_ID,
+    "userId": YOUR_USER_ID,
+    "domainId": YOUR_DOMAIN_ID,
+    "questionId": YOUR_QUESTION_ID,
+    "loginToken": "YOUR_TOKEN"
+  }'
+```
+
+When the analysis is complete, the response will contain the full `responses` array. For how to interpret these returned contents, see [Understanding Response Results](open-api-response-guide).
+
+## Complete Flow (Python)
+
+```python
+import requests
+import time
+import json
+
+# === Configuration ===
+BASE_URL = "https://api.clickzetta.com/clickzetta-campaign-data"  # Domestic SaaS environment
+APP_SECRET_KEY = "your_app_secret_key"
+TENANT_ID = 10
+USER_ID = 1
+DOMAIN_ID = 106
+
+# === Step 1: Get Token ===
+resp = requests.get(
+    f"{BASE_URL}/open/api/v1/appSecretKey/generateAuthToken",
+    params={"appSecretKey": APP_SECRET_KEY}
+)
+token = resp.json()["data"]["token"]
+print(f"Token obtained successfully")
+
+# === Step 2: Create Session ===
+resp = requests.post(
+    f"{BASE_URL}/open/session/safe_new",
+    params={"tenantId": TENANT_ID, "userId": USER_ID, "loginToken": token},
+    json={"tenantId": TENANT_ID, "userId": USER_ID, "domainId": DOMAIN_ID,
+          "title": "API Quick Start", "loginToken": token}
+)
+session_id = resp.json()["data"]
+print(f"Session created successfully, sessionId = {session_id}")
+
+# === Step 3: Ask Question ===
+resp = requests.post(
+    f"{BASE_URL}/open/text2insight/query",
+    params={"tenantId": TENANT_ID, "userId": USER_ID, "loginToken": token},
+    json={"tenantId": TENANT_ID, "userId": USER_ID, "domainId": DOMAIN_ID,
+          "sessionId": session_id, "msg": "Show me the sales trend by region for the past 6 months", "loginToken": token}
+)
+question_id = resp.json()["data"]["questionId"]
+print(f"Question submitted successfully, questionId = {question_id}")
+
+# === Step 4: Poll for Results ===
+print("Waiting for analysis to complete...")
+poll_count = 0
+max_polls = 180  # Poll at most 180 times (360 seconds)
+
+while poll_count < max_polls:
+    time.sleep(2)
+    poll_count += 1
+
+    resp = requests.post(
+        f"{BASE_URL}/open/safe_question_poll",
+        params={"tenantId": TENANT_ID, "userId": USER_ID, "loginToken": token},
+        json={"tenantId": TENANT_ID, "userId": USER_ID, "domainId": DOMAIN_ID,
+              "questionId": question_id, "loginToken": token}
+    )
+    data = resp.json()["data"]
+    responses = data.get("responses", [])
+
+    if not responses:
+        continue
+
+    last_type = responses[-1].get("dataType", "")
+    if last_type in ("finish", "finish_stop", "error"):
+        print(f"Analysis complete (polled {poll_count} times)")
+        break
+
+# === Display Results ===
+print("\n" + "=" * 60)
+print("Analysis Results:")
+print("=" * 60)
+
+for i, r in enumerate(responses):
+    data_type = r.get("dataType", "unknown")
+
+    if data_type == "summary":
+        # Analysis summary
+        summary = r.get("modelRes", {}).get("data", {}).get("summaryData") or r.get("message", "")
+        print(f"\nAnalysis Summary:\n{summary}")
+
+    elif data_type == "metric":
+        # Metric calculation
+        message = r.get("message", "")
+        print(f"\nMetric: {message}")
+
+    elif data_type == "echarts_plus":
+        # Chart
+        message = r.get("message", "")
+        sql = r.get("modelRes", {}).get("data", {}).get("calculateSql", "")
+        print(f"\nChart: {message}")
+        if sql:
+            print(f"   SQL: {sql[:100]}...")
+
+    elif data_type == "error":
+        print(f"\nError: {r.get('message', '')}")
+```
+
+## Sample Output
+
+Running the Python script above produces output similar to this:
+
+```text
+Token obtained successfully
+Session created successfully, sessionId = 4729
+Question submitted successfully, questionId = 34339
+Waiting for analysis to complete...
+Analysis complete (polled 36 times)
+
+============================================================
+Analysis Results:
+============================================================
+
+Metric: Metric: Total sales by region for the past 6 months
+
+Chart: Sales trend by region (2025.07-2026.01)
+   SQL: SELECT region, month, SUM(sales) AS total_sales FROM ...
+
+Analysis Summary:
+**Sales Trend Analysis by Region:**
+- East China region continues to lead, accounting for 42% of total sales
+- South China region has the fastest growth, up 15% month-over-month
+...
+```
+
+## Next Steps
+
+* Understand the meaning of each message type in the response → [Understanding Response Results](open-api-response-guide)
+* View the complete parameter definitions for each interface → [API Interface List](open-api-overview#api-interface-list)
+* Specify a model: add the `modelSettings` parameter when asking a question → [Text2InsightQuery](open-api-text2insight-query)
+
+^

package/bin/skills/lakehouse-doc-en/references/open-api-response-guide.md

@@ -0,0 +1,264 @@
+# Understanding Response Results
+
+> This guide helps you interpret the `responses` array returned by SafeQuestionPoll, understand the meaning of each message type, and how to display them in your application.
+
+## Overall Structure
+
+The `responses` returned from polling is a message array that records, in chronological order, all output produced during the Agent's analysis. It is **a mixed list of incremental process messages and final results**.
+
+A typical analysis produces the following message sequence:
+
+```text
+notify → message (knowledge retrieval) → message (execution process) → metric → code → echarts_plus → summary → finish
+```
+
+Not all types appear every time; this depends on the complexity of the question and the analysis path chosen by the Agent.
+
+## Message Type Quick Reference
+
+| Type | Should You Pay Attention | Description |
+|------|:------------------------:|-------------|
+| **summary** | Yes (required) | Final analysis summary, containing data interpretation and business insights |
+| **metric** | Yes (recommended) | Metric calculation results, including DSL definitions |
+| **echarts_plus** | Yes (recommended) | Chart data, can be used directly for rendering |
+| **code** | Yes (recommended) | Generated code (usually SQL) |
+| **message** | Depends | May contain knowledge details or execution logs |
+| **notify** | Usually ignore | Progress hints, e.g., "Thinking" |
+| **finish** | Status only | Marks the end of analysis |
+| **finish_stop** | Status only | Marks user-initiated stop |
+| **error** | Handle it | Execution error |
+
+## Field Reading Rules
+
+Business fields in each message may appear at different levels. Read in the following priority:
+
+```text
+1. response.fieldName        (top level)
+2. response.modelRes.data.fieldName
+3. JSON.parse(response.rawRes).data.fieldName
+```
+
+It is recommended to implement a unified function:
+
+```python
+def read_field(response, field_name):
+    """Read the specified field from a response in priority order"""
+    # Priority 1: top level
+    if response.get(field_name):
+        return response[field_name]
+    # Priority 2: modelRes.data
+    model_data = response.get("modelRes", {}).get("data", {})
+    if model_data.get(field_name):
+        return model_data[field_name]
+    # Priority 3: rawRes
+    raw_res = response.get("rawRes")
+    if raw_res and isinstance(raw_res, str):
+        try:
+            parsed = json.loads(raw_res)
+            if parsed.get("data", {}).get(field_name):
+                return parsed["data"][field_name]
+        except json.JSONDecodeError:
+            pass
+    return None
+```
+
+## Detailed Description and Display Recommendations by Type
+
+### summary — Analysis Summary
+
+**This is the most important message**, containing the final data insights and conclusions.
+
+Key fields:
+- `summaryData` — Summary text (Markdown format)
+- If `summaryData` is empty, fall back to `message`
+
+Display recommendation: Render directly as Markdown, supporting tables, bold, and other formatting.
+
+Actual output example:
+
+```text
+**Beijing Second-hand Housing Total Transaction Amount by District in the Past 6 Years (2015-2021):**
+
+- **Knowledge Retrieval**: Consulted knowledge base, confirmed "sales" in the dataset corresponds to transaction price
+- **Metric Calculation**: Used the "Total Transaction Amount" metric
+
+**District Rankings by Transaction Amount (unit: CNY 100 million):**
+
+| Rank | District | Total Transaction Amount (CNY 100M) |
+|------|----------|-------------------------------------|
+| 1 | Chaoyang | 10349.27 |
+| 2 | Haidian | 5850.22 |
+| 3 | Fengtai | 3411.86 |
+...
+```
+
+---
+
+### metric — Metric Calculation Result
+
+Generated when the Agent performs calculations through the metric engine.
+
+Key fields:
+- `message` — Metric name description
+- `metricDsl` — Semantic layer DSL (JSON)
+- `physicalMetricDsl` — Physical layer DSL (JSON)
+
+Display recommendation: Show the metric name. For developer-facing views, DSL details can be collapsed.
+
+Actual output example:
+
+```text
+message: Metric: Total Transaction Amount by District in the Past 6 Years
+
+metricDsl:
+{
+  "metricId": { "metricType": "SQL_SIMPLE", "id": 631 },
+  "name": "Total Transaction Amount by District in the Past 6 Years",
+  "params": [
+    { "name": "dims", "values": [{ "left": "region" }] },
+    { "name": "filters", "values": [{ "exprItems": [...] }] }
+  ],
+  "metricDefinition": {
+    "mainTable": "ns10.public.v_gpt_ns10_datagpt_buildin_beijing_house_transaction",
+    "calculationLogic": "SUM(`transaction_price`)"
+  }
+}
+```
+
+---
+
+### echarts_plus — Chart Data
+
+Visualization chart configuration generated by the Agent.
+
+Key fields:
+- `message` — Chart title
+- `chartType` — Chart type (e.g., ECHARTS)
+- `columns` — Column definitions
+- `calculateSql` — SQL used to retrieve chart data
+
+Display recommendation: Use the `calculateSql` query results with `chartType` for frontend rendering.
+
+Actual output example:
+
+```text
+message: Beijing Second-hand Housing Total Transaction Amount by District in the Past 6 Years (2015-2021)
+chartType: ECHARTS
+columns: District (STRING), Total Transaction Amount (10K CNY) (LONG)
+calculateSql:
+SELECT region AS district, SUM(transaction_price) AS total_transaction_amount
+FROM ns10.public.v_gpt_ns10_datagpt_buildin_beijing_house_transaction
+WHERE transaction_date >= '2015.01.01' AND transaction_date <= '2021.01.09'
+GROUP BY region ORDER BY total_transaction_amount DESC
+```
+
+---
+
+### code — Code Block
+
+Code generated by the Agent, usually SQL.
+
+Key fields:
+- `codeType` — Code language (e.g., `sql`)
+- `code` — Code content
+
+Actual output example:
+
+```text
+codeType: sql
+code:
+SELECT
+  region AS district,
+  SUM(transaction_price) AS total_transaction_amount
+FROM ns10.public.v_gpt_ns10_datagpt_buildin_beijing_house_transaction
+WHERE transaction_date >= '2015.01.01' AND transaction_date <= '2021.01.09'
+GROUP BY region
+ORDER BY total_transaction_amount DESC
+```
+
+---
+
+### message — General Message
+
+This is a "catch-all" type that may contain various content. The content should be further evaluated based on its context.
+
+#### Contains Knowledge Details
+
+When the message contains `knowledgeData.detailItems`, or the text includes `Knowledge details:` or `Viewed knowledge details:`, it represents knowledge retrieval results.
+
+Display recommendation: Extract and display the knowledge entries to help users understand which business rules the Agent referenced.
+
+Actual output example:
+
+```text
+source: get_knowledge_detail
+items:
+- id=51, keys=Beijing Second-hand Housing 10-year Transaction Data, value={"desc": "If no time is explicitly specified in the question, use yesterday"}, type=TEXT
+- id=52, keys=Beijing Second-hand Housing 10-year Transaction Data 2, value={"desc":"The answer must include a time range"}, type=TEXT
+```
+
+#### Contains Execution Process
+
+When the text contains `Executing metric calculation:` or similar text, it represents metric execution logs.
+
+Display recommendation: Show in developer-facing debugging interfaces; hide from business users.
+
+---
+
+### notify — Progress Notification
+
+Messages such as "Thinking next step" or "Searching knowledge base".
+
+Display recommendation: Can be used to show status text in a loading animation, or ignored entirely.
+
+---
+
+### error — Error
+
+An exception occurred during analysis.
+
+Display recommendation: Show the error message to the user and suggest retrying or rephrasing the question.
+
+## Recommended Display Priority
+
+If you only need to show core results to end users, filter and display in the following order:
+
+1. **summary** — Primary display content
+2. **echarts_plus** — Paired with chart rendering
+3. **code** — SQL view (collapsible)
+4. **metric** — Metric details (collapsible)
+5. **message (knowledge type)** — Referenced knowledge (collapsible)
+
+Other types need not be shown to end users.
+
+## Real Complete Output Example
+
+The following is the key returned messages from a real Q&A session ("Beijing second-hand housing sales over the past 6 years, by district"):
+
+```text
+[response#61] type=knowledge
+Knowledge retrieval: consulted 2 business rules
+- Rule 1: If no time is explicitly specified in the question, use yesterday
+- Rule 2: The answer must include a time range
+
+[response#93] type=execution log
+Executing metric calculation: Total transaction amount by district in the past 6 years (Metric ID: 631)
+
+[response#95] type=metric
+Metric result: Total transaction amount by district in the past 6 years
+Contains metricDsl and physicalMetricDsl
+
+[response#99] type=code
+SQL: SELECT region AS district, SUM(transaction_price) AS total_transaction_amount FROM ... GROUP BY region
+
+[response#101] type=summary
+Complete analysis summary including district ranking table and key findings
+
+[response#103] type=finish
+Analysis complete
+```
+
+## Next Steps
+
+- Return to [API Overview](open-api-overview) to view the interface list
+- View the complete parameter definitions for [SafeQuestionPoll](open-api-safe-question-poll)