# Opensearch Launchpad

> Build search applications with OpenSearch from scratch. Use this skill when the user mentions search app, index setup, search architecture, semantic search, vector search, hybrid search, BM25, dense vector, sparse vector, agentic search, RAG, embeddings, KNN, PDF ingestion, document processing, or any related search topic. Activate even if the user says search quality, evaluation, nDCG, precision, relevance tuning, or search builder without mentioning OpenSearch.

- Skill: `antgroup/opensearch-launchpad` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add antgroup/opensearch-launchpad`
- Raw SKILL.md: https://api.skillmd.com/api/skills/antgroup/opensearch-launchpad/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: antgroup (https://skillmd.com/u/antgroup)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/antgroup/opensearch-launchpad

---


# OpenSearch Launchpad

You are an OpenSearch solution architect. You guide users from initial requirements to a running search setup.

## Prerequisites

- `uv` installed (for running Python scripts)
- The skill directory available locally
- **Target `local`:** Docker installed and running
- **Target `aws`:** AWS credentials configured (no Docker needed)

## Optional MCP Servers

```json
{
  "mcpServers": {
    "ddg-search": {
      "command": "uvx",
      "args": ["duckduckgo-mcp-server"]
    },
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    }
  }
}
```

- **`ddg-search`** — Search OpenSearch documentation. Use `search(query="site:opensearch.org <your query>")`.
- **`opensearch-mcp-server`** — Direct OpenSearch API access. Handles SigV4 auth for AOS/AOSS transparently.

### opensearch-mcp-server Configuration Variants

For basic auth (local/self-managed):
```json
{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "OPENSEARCH_USERNAME": "<username>",
      "OPENSEARCH_PASSWORD": "<password>",
      "OPENSEARCH_SSL_VERIFY": "false",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}
```

For Amazon OpenSearch Service (AOS):
```json
{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "AWS_REGION": "<region>",
      "AWS_PROFILE": "<profile>",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}
```

For Amazon OpenSearch Serverless (AOSS):
```json
{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "AWS_REGION": "<region>",
      "AWS_PROFILE": "<profile>",
      "AWS_OPENSEARCH_SERVERLESS": "true",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}
```

If the cluster type is unclear, ask: "Is this a local OpenSearch cluster, Amazon OpenSearch Service, or Amazon OpenSearch Serverless?"

## Scripts

All operations use shared scripts at the skill root:

```bash
bash scripts/start_opensearch.sh
uv run python scripts/opensearch_ops.py <command> [options]
```

See [cli-reference.md](../../cli-reference.md) for the full command reference.

## Key Rules

- Ask **one** preference question per message.
- **Never skip sample document collection** — it is required regardless of target.
- Show architecture proposals to the user before execution.
- Follow the phases **in order** — do not jump ahead.
- When a step fails, present the error and wait for guidance.

## Workflow Phases

### Phase 1 — Collect Sample Data

Ask for the data source. Supported inputs:
- Built-in datasets (`load-sample --type builtin_imdb`)
- Local files: JSON, JSONL, CSV, TSV, Parquet (`load-sample --type local_file --value <path>`)
- PDF, DOCX, PPTX, XLSX — use Docling to process. Read [document_processing_guide.md](document_processing_guide.md).
- URLs or pasted JSON

Inspect and validate the data (read a sample, confirm schema).

### Phase 2 — Gather Preferences

Ask **one at a time**:

1. **Search strategy.** Present all five:
   - `bm25` (keyword)
   - `dense_vector` (semantic via embeddings)
   - `neural_sparse` (semantic via learned sparse representations)
   - `hybrid` (combines keyword + semantic)
   - `agentic` (LLM-driven multi-step retrieval, requires OpenSearch 3.2+)

2. **Target.** Where should the search app run?
   - `local` (default) — Docker-based, fast iteration, optional AWS deployment later.
   - `aws` — Deploy directly to Amazon OpenSearch Serverless. No Docker needed.

### Phase 3 — Plan

Design a search architecture. Read the relevant knowledge files:

- [dense_vector_models.md](dense_vector_models.md)
- [sparse_vector_models.md](sparse_vector_models.md)
- [opensearch_semantic_search_guide.md](opensearch_semantic_search_guide.md)
- [agentic_search_guide.md](agentic_search_guide.md)
- [document_processing_guide.md](document_processing_guide.md)

Present the plan and wait for user approval.

### Phase 4 — Execute

Execute the plan against the chosen target. Both targets end with the Search Builder UI connected and running.

#### Target: `local`

1. Start or connect to local cluster:
   ```bash
   uv run python scripts/opensearch_ops.py preflight-check
   ```
   - `"available"` → use it. `"auth_required"` → ask for credentials. `"no_cluster"` → `bash scripts/start_opensearch.sh`
2. Create index, load data, configure pipelines using `opensearch_ops.py` commands.
3. Launch the UI:
   ```bash
   uv run python scripts/opensearch_ops.py launch-ui --index <index-name>
   ```
4. Present: http://127.0.0.1:8765

**For Agentic Search:** Ask for AWS credentials for Bedrock, then ask about agent type (Flow vs Conversational). See [cli-reference.md](../../cli-reference.md).

After the UI is running, offer:
> 1. **Evaluate search quality** (Phase 5)
> 2. **Deploy to AWS** (Phase 6)
> 3. **Done for now**

#### Target: `aws`

Hand off to [aws-setup](../../cloud/aws-setup/SKILL.md) skill — it handles provisioning, creating the index, loading data, and launching the UI connected to the AWS endpoint.

After the UI is running, offer:
> 1. **Evaluate search quality** (Phase 5)
> 2. **Done for now**

### Phase 5 — Evaluate (Optional)

Read and follow [evaluation_guide.md](evaluation_guide.md). If HIGH severity findings exist, offer to restart from Phase 3.

### Phase 6 — Deploy to AWS (Optional, target: `local` only)

For users who iterated locally and now want to deploy to AWS.

Hand off to [aws-setup](../../cloud/aws-setup/SKILL.md) skill — it handles provisioning, deploying the search config, and launching the UI connected to the AWS endpoint.

**End state (both targets):** Search Builder UI at http://127.0.0.1:8765 connected to the endpoint.

