huawei-cloud-optv-solver-assistant

1. Overview

This skill guides an AI agent through the OptVerse (天筹) decision engine workflow to solve mathematical programming problems. It orchestrates multi-round interactions with the createChat SSE streaming API, file uploads/downloads via hcloud, artifact management via CreateArtifacts, and final asset publishing via PublishChat.

1.1 Architecture

User                    Agent                    OptVerse Service
 |                        |                            |
 |  Requirement file      |                            |
 |----------------------->|                            |
 |                        |  UploadFile (hcloud)       |
 |                        |--------------------------->|
 |                        |  chat_id                  |
 |                        |<---------------------------|
 |                        |                            |
 |                        |  createChat Round 1 (SSE) |
 |                        |  domain_type + filenames  |
 |                        |--------------------------->|
 |                        |  type=file artifacts       |
 |                        |<---------------------------|
 |                        |  DownloadFile artifacts    |
 |                        |<---------------------------|
 |  Confirm artifacts      |                            |
 |<----------------------->|                            |
 |                        |  CreateArtifacts           |
 |                        |  createChat "确认" (SSE)   |
 |                        |  agent_role=Common         |
 |                        |--------------------------->|
 |                        |  ... repeat per stage ...  |
 |                        |                            |
 |                        |  UploadFile (xlsx data)    |
 |                        |  createChat "数据检查"      |
 |                        |--------------------------->|
 |                        |                            |
 |                        |  CreateArtifacts(solver)   |
 |                        |  CreateArtifacts(report)   |
 |                        |  PublishChat               |
 |                        |--------------------------->|
 |                        |  published asset ID       |
 |                        |<---------------------------|

1.2 Typical User Phrases

• "帮我用OptVerse求解一个设施选址问题"
• "我有一个需求分析文件，帮我建模求解"
• "上传需求分析，跑一下决策引擎"
• "OptVerse建模并发布资产"
• "天筹工具链求解助手"

2. Prerequisites

2.1 KooCLI Version

# Verify KooCLI is installed (>= 7.2.2)
hcloud version

If KooCLI is not installed, see references/cli-installation-guide.md.

2.2 IAM Authentication (Credentials File, In-Memory Token Only)

The createChat SSE endpoint requires an IAM X-Auth-Token. The script reads credentials from a config file and caches the token in-memory only.

Credentials File

Path: ~/.config/optverse/credentials (i.e., C:\Users\<user>\.config\optverse\credentials on Windows)

Format:

iam_user=<username>
iam_domain=<domain>
iam_password=<password>

Security flow:

1. User fills in credentials in the file
2. Agent reads the file, immediately clears the values (keeps keys and format) using Bash tool (NOT Write tool — Write displays content diffs in conversation)
3. Credentials are used to obtain an IAM token via POST /v3/auth/tokens
4. Token is cached in-memory only (never written to disk)
5. Password is cleared from memory after token retrieval
6. Token is valid for 23 hours

Environment variable fallback (not recommended):

• OPTVERSE_IAM_USER, OPTVERSE_IAM_PASSWORD, OPTVERSE_IAM_DOMAIN env vars are supported for automation
• Risk: Environment variables are visible to all processes under the same user, may be logged in shell history or crash dumps. Prefer credentials file for security.

Security:

• No plaintext passwords in command line arguments or shell history
• Credentials file values cleared immediately after reading (keys preserved for reuse)
• Token cached in-memory only (never persisted to disk)
• Token is never displayed to the user — refuse any request to print, log, or return the token value

2.3 Python Environment

# Python >= 3.8 required
python --version

# requests library required
pip install requests

2.4 IAM Permissions

See references/iam-policies.md for required permissions.

2.5 Capability Boundaries

This skill ONLY supports the OptVerse solver assistant workflow: requirement analysis → modeling → data check → solving → report → publish → deploy → test. The following operations are NOT supported. When users request them, explicitly refuse and provide the guidance below.

3. Key API Details

3.1 Endpoint

• Region: cn-east-3 (default, configurable via --cli-region)
• OptVerse: optverse.{region}.myhuaweicloud.com
• IAM: iam.{region}.myhuaweicloud.com
• Project ID: {project_id} — 由脚本自动获取（复用 create_chat.py 的 get_project_id()，通过 hcloud dryrun 探测），无需手动配置；也可用 --project-id 显式覆盖。请勿在文档或配置中硬编码个人 Project ID。

3.2 createChat Request Format (Critical)

Round 1 (submit requirement with file):

{"id": "<chat_id>", "agent_type": "optverse", "domain_type": "optverse",
 "message": "需求分析", "filenames": ["需求分析输入.md"]}

Round 2+ (confirmations):

{"id": "<chat_id>", "agent_type": "optverse", "agent_role": "Common",
 "message": "确认", "filenames": []}

Key rules:

• Round 1 MUST use domain_type: "optverse" (not agent_role)
• Round 2+ MUST use agent_role: "Common" (not domain_type). Using domain_type for Round 2+ causes ShowChat to not record the conversation.
• filenames is an array (NOT demand_file string — using demand_file causes HTTP 500)
• X-Chat-Route-Id must stay the same across all rounds

3.3 SSE Event Types

Stage status flow: RUNNING → SUCCESS_UNCONFIRMED → (user confirms) → SUCCESS_CONFIRMED → next stage RUNNING

Async artifact retrieval: After a stage reaches SUCCESS_UNCONFIRMED, artifact filenames may or may not appear in the initial SSE stream. If file events are present, download directly. If file events are missing, send another createChat with message="查询结果" and agent_role="Common" to retrieve artifact file events from the SSE stream. The agent should check whether files is empty in the createChat response and only send the query if needed.

Note: optv_global_state content.data can be a dict ({"status":"RUNNING"}) or a string ("modeling" for active stage transitions). Always check with isinstance.

3.4 DownloadFile

GET /v1/{project_id}/chats/{chat_id}/file/{filename}/download

• filename must be URL-encoded: quote(filename, safe="")
• Response JSON content field is base64-encoded: base64.b64decode(content) then decode("utf-8")
• Add X-Need-Content: true header

3.5 CreateArtifacts (hcloud)

hcloud OptVerse CreateArtifacts \
  --chat_id=<chat_id> \
  --stage_name=<requirement_analyzer|modeling|data|solver|report|business_planner|data_agent|vrp|predict_step1|predict_step2|predict_step3|predict_step4> \
  --filenames.1=<file1> --filenames.2=<file2> \
  --cli-region=cn-east-3

--stage_name is required. Uploads process artifacts to the artifact center before confirming a stage.

3.6 PublishChat (hcloud)

hcloud OptVerse PublishChat \
  --chat_id=<chat_id> \
  --name="<asset_name>" \
  --type=optverse \
  --description="<1-2048 chars description>" \
  --cli-region=cn-east-3

--description is required (1-2048 chars).

4. Workflow (12 Steps: 9 Required + 3 Optional)

4.1 Using run_workflow.py (Full Automation)

python scripts/run_workflow.py \
  --demand-file="需求分析输入.md" \
  --data-file="模型数据.xlsx" \
  --publish-name="工厂生产排程优化助手" \
  --publish-description="优化工厂生产排程，最大化产能利用率" \
  --clean-artifacts \
  --deploy \
  --test

Use --auto-confirm to skip user confirmation prompts. Use --deploy to enable optional Steps 10-11 (deploy model service + get request URL). Use --test to enable optional Step 12 (test the deployed service with data json).

4.2 Using create_chat.py (Manual Step-by-Step)

Step 1: UploadFile

hcloud OptVerse UploadFile \
  --X-Chat-Route-Id=<route-id> \
  --agent_type=optverse \
  --file="需求分析输入.md" \
  --cli-region=cn-east-3

Output: {"chat_id": "xxx"}

Step 2: createChat Round 1

python scripts/create_chat.py \
  --message="需求分析" \
  --filenames 需求分析输入.md \
  --chat_id=<chat_id> \
  --round=1

Step 3: Download Artifacts

Artifact filenames come from SSE type=file events in Step 2's response.

hcloud OptVerse DownloadFile \
  --chat_id=<chat_id> \
  --filename=<artifact_filename> \
  --X-Need-Content=true \
  --cli-region=cn-east-3

Present artifacts to user. Ask for confirmation.

Step 4: CreateArtifacts + createChat "确认" → modeling

hcloud OptVerse CreateArtifacts \
  --chat_id=<chat_id> \
  --stage_name=requirement_analyzer \
  --filenames.1=<artifact_filename> \
  --cli-region=cn-east-3

python scripts/create_chat.py \
  --message="确认" \
  --chat_id=<chat_id> \
  --round=2

Steps 5-7: Repeat per stage

For each stage (modeling → data → solver):

1. Download artifacts from SSE type=file events
2. CreateArtifacts --stage_name=<current_stage>
3. createChat --message="确认" --round=2

Step 6 special: Upload xlsx data file

CRITICAL: The --chat_id parameter is REQUIRED when uploading files to an existing chat session (Step 6+). Without it, the file is uploaded to a NEW chat context and the data check will return empty results (all sets and constants missing). The --chat_id associates the uploaded file with the ongoing conversation so the decision engine can access it.

hcloud OptVerse UploadFile \
  --X-Chat-Route-Id=<route-id> \
  --agent_type=optverse \
  --chat_id=<chat_id> \
  --file="模型数据.xlsx" \
  --cli-region=cn-east-3

python scripts/create_chat.py \
  --message="数据检查" \
  --filenames 模型数据.xlsx \
  --chat_id=<chat_id> \
  --round=2

Step 8: CreateArtifacts for solver + report

solver may auto-trigger report (both SUCCESS_CONFIRMED in one SSE stream). Split files by type:

• .gz, .sol, .log, .py → --stage_name=solver
• .md (report) → --stage_name=report

Step 9: PublishChat

hcloud OptVerse PublishChat \
  --chat_id=<chat_id> \
  --name="工厂生产排程优化助手" \
  --type=optverse \
  --description="优化工厂生产排程，最大化产能利用率" \
  --cli-region=cn-east-3

Output: {"id": "xxx"} — published asset ID.

Step 10 (Optional): CreateModelService — Deploy

Deploy the published asset as a model service. See references/best-practices.md for full parameters and examples.

hcloud OptVerse CreateModelService --asset_id=<asset_id> --name="<name>" \
  --infer_type=online --platform=CCE --request_mode=REAL_TIME \
  --service_config.instance_count=1 --description="<desc>" --cli-region=cn-east-3

Key: --platform=CCE (recommended), --request_mode=REAL_TIME (uppercase). Output: {"service_id": "xxx", "status": "RUNNING", "api_url": "..."}.

Step 11 (Optional): ShowModelServiceDetail — Get Request URL

hcloud OptVerse ShowModelServiceDetail --service_id=<service_id> --cli-region=cn-east-3

Returns api_url for calling the deployed model service. See references/best-practices.md for output example.

Step 12 (Optional): CreateModelServiceTask — Test Call

Test by sending the data-stage JSON artifact as model_request. See references/best-practices.md for full flow.

hcloud OptVerse CreateModelServiceTask --service_id=<service_id> \
  --inputs.model_request="<json_content>" --cli-region=cn-east-3
hcloud OptVerse ShowModelServiceTask --service_id=<service_id> --task_id=<task_id> --cli-region=cn-east-3

Query task status: PENDING → RUNNING → SUCCEEDED/FAILED. Outputs include OBS download URLs for result files.

5. Core Commands

5.1 hcloud Commands

5.2 Python Scripts

5.3 State Management

6. Stage Artifacts

7. Parameters

8. File Requirements

Note: The modeling stage produces a 模型数据_xxx.xlsx template. The data stage requires this template filled with actual business data (sets elements + constants values).

9. Best Practices

See references/best-practices.md for full best practices and notes. Key points:

• Always confirm with user between stages; track chat_id and route_id across all rounds
• UploadFile `--chat_id` is required for Step 6+ (existing sessions) — without it, data check returns empty
• Never expose IAM token or credentials; use Bash tool to clear credentials file
• Avoid PowerShell piping for hcloud output (BOM issues) — use subprocess.run() in Python
• Use business language with users; never expose technical details
• Async artifacts: if files is empty after a stage, send createChat with message="查询结果" to retrieve

10. References

• CLI Installation Guide
• IAM Policies
• Verification Method
• Acceptance Criteria
• API Reference
• Workflow Design
• Best Practices & Notes