---
name: opensearch-launchpad
description: >
  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.
compatibility: Requires Docker and uv. AWS deployment requires AWS credentials.
metadata:
  author: opensearch-project
  version: "2.0"
---

# OpenSearch Launchpad

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

## Prerequisites

- Docker installed and running
- `uv` installed (for running Python scripts)
- The skill directory available locally

## 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 Phase 1** (sample document collection).
- 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.
- Do not describe **Amazon OpenSearch Serverless** as scaling to zero.
- **Agentic search** does not deploy to **Amazon OpenSearch Serverless** — use a **managed domain**.

## Workflow Phases

### Phase 1 — Start OpenSearch & Collect Sample

Check if a cluster is already running:

```bash
uv run python scripts/opensearch_ops.py preflight-check
```

- **`status: "available"`** — Cluster running. Use it directly.
- **`status: "auth_required"`** — Ask for credentials, then retry with `--auth-mode custom`.
- **`status: "no_cluster"`** — Start one: `bash scripts/start_opensearch.sh`

Once available, ask for the data source. Use `load-sample` to load data.

If the user provides PDF, DOCX, PPTX, or XLSX files, use Docling to process them. Read [document_processing_guide.md](document_processing_guide.md) for the workflow.

### Phase 2 — Gather Preferences

Ask **one at a time**: search strategy and deployment preference. Present all five strategies:
- `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+)

### 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 using `opensearch_ops.py` commands. When launching the UI, present the URL (default: `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) for agentic setup commands.

After the UI is running:
> "Your search app is live! Here's what you can do next:"
> 1. **Evaluate search quality** (Phase 4.5)
> 2. **Deploy to Amazon OpenSearch Service** — use the `aws-setup` skill
> 3. **Done for now** — Keep experimenting with the Search Builder UI.

### Phase 4.5 — Evaluate (Optional)

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

### Phase 5 — Deploy to AWS (Optional)

Refer the user to the [aws-setup](../../cloud/aws-setup/SKILL.md) skill for the full deployment workflow.