Skill: cinience/aliyun-opensearch-search (version 1.0.0)

--- name: aliyun-opensearch-search description: Use when working with OpenSearch vector search edition via the Python SDK (ha3engine) to push documents and run HA/SQL searches. Ideal for RAG and vector retrieval pipelines in Claude Code/Codex. version: 1.0.0 --- Category: provider # OpenSearch Vector Search Edition Use the ha3engine SDK to push documents and execute HA/SQL searches. This skill focuses on API/SDK usage only (no console steps). ## Prerequisites - Install SDK (recommended in a venv to avoid PEP 668 limits): ```bash python3 -m venv .venv . .venv/bin/activate python -m pip install alibabacloud-ha3engine ``` - Provide connection config via environment variables: - `OPENSEARCH_ENDPOINT` (API domain) - `OPENSEARCH_INSTANCE_ID` - `OPENSEARCH_USERNAME` - `OPENSEARCH_PASSWORD` - `OPENSEARCH_DATASOURCE` (data source name) - `OPENSEARCH_PK_FIELD` (primary key field name) ## Quickstart (push + search) ```python import os from alibabacloud_ha3engine import models, client from Tea.exceptions import TeaException, RetryError cfg = models.Config( endpoint=os.getenv("OPENSEARCH_ENDPOINT"), instance_id=os.getenv("OPENSEARCH_INSTANCE_ID"), protocol="http", access_user_name=os.getenv("OPENSEARCH_USERNAME"), access_pass_word=os.getenv("OPENSEARCH_PASSWORD"), ) ha3 = client.Client(cfg) def push_docs(): data_source = os.getenv("OPENSEARCH_DATASOURCE") pk_field = os.getenv("OPENSEARCH_PK_FIELD", "id") documents = [ {"fields": {"id": 1, "title": "hello", "content": "world"}, "cmd": "add"}, {"fields": {"id": 2, "title": "faq", "content": "vector search"}, "cmd": "add"}, ] req = models.PushDocumentsRequestModel({}, documents) return ha3.push_documents(data_source, pk_field, req) def search_ha(): # HA query example. Replace cluster/table names as needed. query_str = ( "config=hit:5,format:json,qrs_chain:search" "&&query=title:hello" "&&cluster=general" ) ha_query = models.SearchQuery(query=query_str) req = models.SearchRequestModel({}, ha_query) return ha3.search(req) try: print(push_docs().body) print(search_ha()) except (TeaException, RetryError) as e: print(e) ``` ## Script quickstart ```bash python skills/ai/search/aliyun-opensearch-search/scripts/quickstart.py ``` Environment variables: - `OPENSEARCH_ENDPOINT` - `OPENSEARCH_INSTANCE_ID` - `OPENSEARCH_USERNAME` - `OPENSEARCH_PASSWORD` - `OPENSEARCH_DATASOURCE` - `OPENSEARCH_PK_FIELD` (optional, default `id`) - `OPENSEARCH_CLUSTER` (optional, default `general`) Optional args: `--cluster`, `--hit`, `--query`. ## SQL-style search ```python from alibabacloud_ha3engine import models sql = "select * from <indexTableName>&&kvpair=trace:INFO;formatType:json" sql_query = models.SearchQuery(sql=sql) req = models.SearchRequestModel({}, sql_query) resp = ha3.search(req) print(resp) ``` ## Notes for Claude Code/Codex - Use `push_documents` for add/delete updates. - Large query strings (>30KB) should use the RESTful search API. - HA queries are fast and flexible for vector + keyword retrieval; SQL is helpful for structured data. ## Error handling - Auth errors: verify username/password and instance access. - 4xx on push: check schema fields and `pk_field` alignment. - 5xx: retry with backoff. ## Validation ```bash mkdir -p output/aliyun-opensearch-search for f in skills/ai/search/aliyun-opensearch-search/scripts/*.py; do python3 -m py_compile "$f" done echo "py_compile_ok" > output/aliyun-opensearch-search/validate.txt ``` Pass criteria: command exits 0 and `output/aliyun-opensearch-search/validate.txt` is generated. ## Output And Evidence - Save artifacts, command outputs, and API response summaries under [REDACTED_SECRET]. - Include key parameters (region/resource id/time range) in evidence files for reproducibility. ## Workflow 1) Confirm user intent, region, identifiers, and whether the operation is read-only or mutating. 2) Run one minimal read-only query first to verify connectivity and permissions. 3) Execute the target operation with explicit parameters and bounded scope. 4) Verify results and save output/evidence files. ## References - SDK package: `alibabacloud-ha3engine` - Demos: data push and HA/SQL search demos in OpenSearch docs - Source list: `references/sources.md`

path: agents/openai.yaml
content: interface:
  display_name: "Alibaba Cloud AI Search OpenSearch"
  short_description: "OpenSearch vector indexing and query"
  default_prompt: "Use $alicloud-ai-search-opensearch to complete this ai/search task on Alibaba Cloud."


path: references/sources.md
content: 官方文档来源（用于后续更新）
============================

- （暂无外部文档链接）


path: scripts/quickstart.py
content: import argparse
import os
import sys

from alibabacloud_ha3engine import client, models
from Tea.exceptions import TeaException, RetryError


def get_env(name: str, default: str | None = None) -> str:
    value = os.getenv(name, default)
    if not value:
        print(f"Missing env var: {name}", file=sys.stderr)
        sys.exit(1)
    return value


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="OpenSearch vector quickstart")
    parser.add_argument("--cluster", default=os.getenv("OPENSEARCH_CLUSTER", "general"))
    parser.add_argument("--hit", type=int, default=5)
    parser.add_argument("--query", default="title:hello")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    cfg = models.Config(
        endpoint=get_env("OPENSEARCH_ENDPOINT"),
        instance_id=get_env("OPENSEARCH_INSTANCE_ID"),
        protocol="http",
        access_user_name=get_env("OPENSEARCH_USERNAME"),
        access_pass_word=get_env("OPENSEARCH_PASSWORD"),
    )
    ha3 = client.Client(cfg)

    data_source = get_env("OPENSEARCH_DATASOURCE")
    pk_field = get_env("OPENSEARCH_PK_FIELD", "id")

    documents = [
        {"fields": {"id": 1, "title": "hello", "content": "world"}, "cmd": "add"},
        {"fields": {"id": 2, "title": "faq", "content": "vector search"}, "cmd": "add"},
    ]

    try:
        print("Pushing docs...")
        req = models.PushDocumentsRequestModel({}, documents)
        resp = ha3.push_documents(data_source, pk_field, req)
        print(resp.body)

        print("Searching...")
        query_str = (
            f"config=hit:{args.hit},format:json,qrs_chain:search"
            f"&&query={args.query}"
            f"&&cluster={args.cluster}"
        )
        ha_query = models.SearchQuery(query=query_str)
        req = models.SearchRequestModel({}, ha_query)
        resp = ha3.search(req)
        print(resp)
    except (TeaException, RetryError) as exc:
        print(exc)
        sys.exit(1)


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)