moss-docs

Moss 语义搜索的文档和功能参考。 Use for understanding Moss APIs, SDKs, and integration patterns.

## 概述（中文）

Moss 语义搜索的文档和功能参考。 Use for understanding Moss APIs, SDKs, and integration patterns.

## 原文

# Moss Agent Skills

## Capabilities

Moss is the real-time semantic search runtime for conversational AI. It delivers sub-10ms lookups and instant index updates that run in the browser, on-device, or in the cloud - wherever your agent lives. Agents can create indexes, embed documents, perform semantic/hybrid searches, and manage document lifecycles without managing infrastructure. The platform handles embedding generation, index persistence, and optional cloud sync - allowing agents to focus on retrieval logic rather than infrastructure.

## Skills

### Index Management

- **Create Index**: Build a new semantic index with documents and embedding model selection
- **Load Index**: Load an existing index from persistent storage for querying
- **Get Index**: Retrieve metadata about a specific index (document count, model, etc.)
- **List Indexes**: Enumerate all indexes under a project
- **Delete Index**: Remove an index and all associated data

### Document Operations

- **Add Documents**: Insert or upsert documents into an existing index with optional metadata
- **Get Documents**: Retrieve stored documents by ID or fetch all documents
- **Delete Documents**: Remove specific documents from an index by their IDs

### Search & Retrieval

- **Semantic Search**: Query using natural language with vector similarity matching
- **Keyword Search**: Use BM25-based keyword matching for exact term lookups
- **Hybrid Search**: Blend semantic and keyword search with configurable alpha weighting (Python SDK)
- **Metadata Filtering**: Constrain results by document metadata (category, language, tags)
- **Top-K Results**: Return configurable number of best-matching documents with scores

### Embedding Models

- **moss-minilm**: Fast, lightweight model optimized for edge/offline use (default)
- **moss-mediumlm**: Higher accuracy model with reasonable performance for precision-critical use cases

### SDK Methods

| JavaScript        | Python             | Description                    |
| ----------------- | ------------------ | ------------------------------ |
| `createIndex()`   | `create_index()`   | Create index with documents    |
| `loadIndex()`     | `load_index()`     | Load index from storage        |
| `getIndex()`      | `get_index()`      | Get index metadata             |
| `listIndexes()`   | `list_indexes()`   | List all indexes               |
| `deleteIndex()`   | `delete_index()`   | Delete an index                |
| `addDocs()`       | `add_docs()`       | Add/upsert documents           |
| `getDocs()`       | `get_docs()`       | Retrieve documents             |
| `deleteDocs()`    | `delete_docs()`    | Remove documents               |
| `query()`         | `query()`          | Semantic / hybrid search       |

### API Actions

All REST API operations go through `POST /v1/manage` (base URL: `https://service.usemoss.dev/v1`) with an `action` field:

| Action         | Purpose                                          | Extra required fields                           |
| -------------- | ------------------------------------------------ | ----------------------------------------------- |
| `initUpload`   | Get a presigned URL to upload index data         | `indexName`, `modelId`, `docCount`, `dimension` |
| `startBuild`   | Trigger an index build after uploading data      | `jobId`                                         |
| `getJobStatus` | Check the status of an async build job           | `jobId`                                         |
| `getIndex`     | Fetch metadata for a single index                | `indexName`                                     |
| `listIndexes`  | Enumerate every index under the project          | —                                               |
| `deleteIndex`  | Remove an index record and assets                | `indexName`                                     |
| `getIndexUrl`  | Get download URLs for a built index              | `indexName`                                     |
| `addDocs`      | Upsert documents into an existing index          | `indexName`, `docs`                             |
| `deleteDocs`   | Remove documents by ID                           | `indexName`, `docIds`                           |
| `getDocs`      | Retrieve stored documents (without embeddings)   | `indexName`                                     |

## Workflows

### Basic Semantic Search Workflow

1. Initialize MossClient with project credentials
2. Call `createIndex()` with documents and model options (`{ modelId: 'moss-minilm' }` in JS; `"moss-minilm"` string in Python)
3. Call `loadIndex()` to prepare index for queries
4. Call `query()` with search text and `topK` (JS) or `QueryOptions(top_k=...)` (Python)
5. Process returned documents with scores

### Hybrid Search Workflow (Python)

Hybrid blending via `alpha` is available in the Python SDK via `QueryOptions`:

1. Create and load index as above
2. Call `query()` with a `QueryOptions` object specifying `alpha`
3. `alpha=1.0` = pure semantic, `alpha=0.0` = pure keyword, `alpha=0.6` = 60/40 blend
4. Default is semantic-heavy for conversational use cases

### Document Update Workflow

1. Initialize client and ensure index exists
2. Call `addDocs()` with new documents (upserts by default — existing IDs are updated)
3. Call `deleteDocs()` to remove outdated documents by ID

### Voice Agent Context Injection Workflow

This is an opt-in integration pattern for voice agent pipelines — it is not automatic behavior of this skill.

1. Initialize MossClient and load index at agent startup
2. In your application code, call `query()` on each user message to retrieve relevant context
3. Inject search results into the LLM context before generating a response
4. Respond with knowledge-grounded answer (no tool-calling latency)

### Offline-First Search Workflow

1. Create index with documents using local embedding model
2. Load index from local storage
3. Query runs entirely on-device with sub-10ms latency
4. Optionally sync to cloud for backup and sharing

## Integration

### Voice Agent Frameworks

- **LiveKit**: Context injection into voice agent pipeline with `inferedge-moss` SDK
- **Pipecat**: Pipeline processor via `pipecat-moss` package that auto-injects retrieval results

## Context

### Authentication

SDK requires project credentials:

- `MOSS_PROJECT_ID`: Project identifier from Moss Portal
- `MOSS_PROJECT_KEY`: Project access key from Moss Portal

```bash theme={null}
export MOSS_PROJECT_ID=your_project_id
export MOSS_PROJECT_KEY=your_project_key
```

REST API requires the following on every request:

- `x-project-key` header: project access key
- `x-service-version: v1` header: API version
- `projectId` field in the JSON body

```bash theme={null}
curl -X POST "https://service.usemoss.dev/v1/manage" \
  -H "Content-Type: application/json" \
  -H "x-service-version: v1" \
  -H "x-project-key: moss_access_key_xxxxx" \
  -d '{"action": "listIndexes", "projectId": "project_123"}'
```

### Package Installation

| Language              | Package           | Install Command               |
| --------------------- | ----------------- | ----------------------------- |
| JavaScript/TypeScript | `@inferedge/moss` | `npm install @inferedge/moss` |
| Python                | `inferedge-moss`  | `pip install inferedge-moss`  |
| Pipecat Integration   | `pipecat-moss`    | `pip install pipecat-moss`    |

### Document Schema

```typescript theme={null}
interface DocumentInfo {
  id: string;        // Required: unique identifier
  text: string;      // Required: content to embed and search
  metadata?: object; // Optional: key-value pairs for filtering
}
```

### Query Parameters

| Parameter   | SDK         | Type   | Default  | Description                                  |
| ----------- | ----------- | ------ | -------- | -------------------------------------------- |
| `indexName` | JS + Python | s