Moss

https://docs.moss.dev/docs
Admin
Moss provides real-time semantic search with sub-10 ms retrieval for conversational AI, voice...
Tokens:338,086
Snippets:2,513
Trust Score:6
Update:5 days ago
Show doc for...
Tokens:
Raw
### SQLite: install and ingest example

Source: https://docs.moss.dev/docs/integrations/data-connectors

Install the SQLite connector package and run an example that indexes rows from a SQLite database. The example uses a query to select id, title, and body columns, and maps them to DocumentInfo. The output prints the number of copied rows.

```bash
pip install moss-connector-sqlite

```

```python
import asyncio
from moss import DocumentInfo
from moss_connector_sqlite import SQLiteConnector, ingest

async def main():
    source = SQLiteConnector(
        database="./my.db",
        query="SELECT id, title, body FROM articles",
        mapper=lambda r: DocumentInfo(
            id=str(r["id"]),
            text=r["body"],
            metadata={"title": r["title"]},
        ),
    )
    result = await ingest(source, project_id="...", project_key="...", index_name="articles")
    print(f"copied {result.doc_count} rows")

asyncio.run(main())

```

--------------------------------

### MySQL/MariaDB: install and ingest example

Source: https://docs.moss.dev/docs/integrations/data-connectors

Install the MySQL connector package and run an example that indexes rows from a MySQL or MariaDB database. The example shows connection parameters and a query. The output prints the number of copied rows.

```bash
pip install moss-connector-mysql

```

```python
import asyncio
from moss import DocumentInfo
from moss_connector_mysql import MySQLConnector, ingest

async def main():
    source = MySQLConnector(
        host="localhost",
        user="root",
        password="secret",
        database="mydb",
        query="SELECT id, title, body FROM articles",
        mapper=lambda row: DocumentInfo(
            id=str(row["id"]),
            text=row["body"],
            metadata={"title": row["title"]},
        ),
        port=3306,
    )
    result = await ingest(source, project_id="...", project_key="...", index_name="articles")
    print(f"copied {result.doc_count} rows")

asyncio.run(main())

```

--------------------------------

### Migration guide: Before (v1.x Deployment SDK)

Source: https://docs.moss.dev/docs/changelog

Example of the old deployment-based SDK usage before the rewrite.

```python
from moss_voice_agent_manager import MossVoiceClient

client = MossVoiceClient(project_id="...", project_key="...")
client.deploy(
    voice_agent_id="...",
    prompt="...",
    function_tools=[my_tool]
)

```

--------------------------------

### Migration guide: After (v1.0.0-beta.4 Runtime SDK)

Source: https://docs.moss.dev/docs/changelog

Example of the new runtime SDK usage after the rewrite.

```python
from moss_voice_agent_manager import MossAgentSession

# Set environment variables first
session = MossAgentSession(
    userdata=your_data,
    vad=vad,  # optional
    max_tool_steps=10
)

# Access platform API
api = session.platform_api

# Get metrics
metrics = session.metrics
diagnostics = session.diagnostics

```

--------------------------------

### Supabase: install and ingest example

Source: https://docs.moss.dev/docs/integrations/data-connectors

Install the Supabase connector package and run an example that indexes rows from a Supabase table via PostgREST. The table needs at least one stringifiable column for id and one text column for text; all other columns are optional metadata. The output prints the number of copied rows.

```bash
pip install moss-connector-supabase

```

```python
import asyncio
from moss import DocumentInfo
from moss_connector_supabase import SupabaseConnector, ingest

async def main():
    source = SupabaseConnector(
        url="https://xxx.supabase.co",
        key="your-anon-or-service-key",
        table="articles",
        mapper=lambda row: DocumentInfo(
            id=str(row["id"]),
            text=row["body"],
            metadata={"title": row["title"]},
        ),
    )
    result = await ingest(source, project_id="...", project_key="...", index_name="articles")
    print(f"copied {result.doc_count} rows")

asyncio.run(main())

```

--------------------------------

### MongoDB: install and ingest example

Source: https://docs.moss.dev/docs/integrations/data-connectors

Install the MongoDB connector package and run an example that indexes documents from a MongoDB collection. The mapper converts the _id field to a hex string. Optional filter and projection parameters are shown. The output prints the number of copied rows.

```bash
pip install moss-connector-mongodb

```

```python
import asyncio
from moss import DocumentInfo
from moss_connector_mongodb import MongoDBConnector, ingest

async def main():
    source = MongoDBConnector(
        uri="mongodb://localhost:27017",
        database="shop",
        collection="articles",
        mapper=lambda r: DocumentInfo(
            id=str(r["_id"]),   # bson.ObjectId → hex string
            text=r["body"],
            metadata={"title": r["title"]},
        ),
        filter={"status": "published"},                 # optional
        projection={"_id": 1, "title": 1, "body": 1},  # optional
    )
    result = await ingest(source, project_id="...", project_key="...", index_name="articles")
    print(f"copied {result.doc_count} rows")

asyncio.run(main())

```

--------------------------------

### Minimal example for any React app

Source: https://docs.moss.dev/docs/founding-agent/embed/react-components

Shows the minimal setup for any React app. The `tokenEndpoint` is set to `/your/token/endpoint`.

```tsx
import {
  MossFoundingAgentBubble,
  MossFoundingAgentProvider,
} from "@moss-js/founding-agent/react";

export default function App() {
  return (
    <MossFoundingAgentProvider
      publishableKey="pk_your_publishable_key"
      tokenEndpoint="/your/token/endpoint"
    >
      <MossFoundingAgentBubble color="emerald" />
    </MossFoundingAgentProvider>
  );
}

```

--------------------------------

### Install moss-voice-server

Source: https://docs.moss.dev/docs/voice-agents/voice-agents

Install the Python backend SDK for use in FastAPI, Flask, Django, or any Python server.

```bash
pip install moss-voice-server

```

--------------------------------

### Install @moss-tools/voice-server

Source: https://docs.moss.dev/docs/voice-agents/voice-agents

Install the Node.js backend SDK for use in Next.js, Express, or any Node.js server.

```bash
npm install @moss-tools/voice-server

```

--------------------------------

### Install dependencies with uv

Source: https://docs.moss.dev/docs/cookbook/pydantic-ai

Install pydantic-ai, moss, and python-dotenv using uv.

```bash
uv add pydantic-ai moss python-dotenv

```

--------------------------------

### Starter Prompt for Vibecoding with Moss

Source: https://docs.moss.dev/docs/start/vibecoding

A prompt to paste into your AI coding tool before starting a Moss project. It provides context about Moss, documentation links, setup instructions, key concepts, and common errors to guide the AI assistant.

```markdown
You are helping me build an application that uses Moss for real-time semantic search.

## About Moss
Moss is a semantic search runtime for conversational AI with sub-10ms local queries, instant index
updates, same SDK for browser, on-device, and cloud. No separate search infrastructure needed.

## Documentation
- Quickstart:    https://docs.moss.dev/docs/start/quickstart
- Core concepts: https://docs.moss.dev/docs/start/core-concepts
- SDK reference: https://docs.moss.dev/docs/reference/sdk
- API reference: https://docs.moss.dev/api-reference/v1
- MCP server:    https://docs.moss.dev/docs/integrations/mcp-server
- Full doc index (LLM-friendly): https://docs.moss.dev/llms.txt

## Setup
- JS package: @moss-js/moss 1.9.0+  |  Python package: moss 1.9.0+
- Credentials: MOSS_PROJECT_ID from the project page and MOSS_PROJECT_KEY from the API Keys page at https://portal.usemoss.dev

## Key concepts
- createIndex / loadIndex / query is the core flow - see the quickstart for full examples
- Hybrid search: pass alpha (0.0 = keyword, 1.0 = semantic, default 0.8) to query()
- Mutations (createIndex, addDocs, deleteDocs) are async jobs; SDK polls until completion
- Embedding models: moss-minilm (fast, default), moss-mediumlm (higher accuracy), custom (bring your own vectors)
- Metadata filtering on local indexes: $eq, $ne, $in, $gt, $lt, $and, $or operators

## Common errors
- Unauthorized: missing or wrong MOSS_PROJECT_ID / MOSS_PROJECT_KEY
- Index not found: call createIndex() before loading or querying
- Index not loaded: call loadIndex() before query() - query() throws if the index isn't loaded locally
- Missing embeddings runtime: use moss-minilm or moss-mediumlm unless supplying custom vectors
```

--------------------------------

### Quick start: create index, load, and query

Source: https://docs.moss.dev/docs/reference/python/api

Shows the main async workflow: create a MossClient with project credentials, create an index with documents, load it, and query it. Requires Python 3.10+ and project credentials from the Moss portal.

```python
import asyncio
from moss import MossClient, DocumentInfo, QueryOptions

async def main():
    client = MossClient(MOSS_PROJECT_ID, MOSS_PROJECT_KEY)
    await client.create_index("faqs", [
        DocumentInfo(id="doc1", text="Track your order in your account.", metadata={"category": "shipping"}),
        DocumentInfo(id="doc2", text="30-day return policy for most items.", metadata={"category": "returns"}),
    ])
    await client.load_index("faqs")
    results = await client.query("faqs", "return a damaged product", QueryOptions(top_k=3))
    for doc in results.docs:
        print(doc.id, doc.score)

asyncio.run(main())

```

--------------------------------

### Example: Create client, open session, add docs, and query

Source: https://docs.moss.dev/docs/reference/swift/classes/MossClient

Shows how to instantiate MossClient with projectId and projectKey, open a session, add documents, and run a query. The client is closed with defer.

```swift
import Moss

let client = try MossClient(projectId: "your-project-id", projectKey: "your-project-key")
defer { client.close() }

// Open an on-device session and search locally.
let session = try await client.session("docs")
try await session.addDocs([
  .init(id: "1", text: "Machine learning fundamentals"),
  .init(id: "2", text: "Deep learning neural networks"),
])
let results = try await session.query("AI and neural networks")

```

--------------------------------

### Quickstart: create client, index, load, and query

Source: https://docs.moss.dev/docs/reference/browser/api

Initializes a MossClient, creates an index with documents, loads it into the browser, and runs a query. The inline projectKey is for local experiments only; production frontends must use a custom authenticator. Always call loadIndex before query.

```typescript
import { MossClient } from "@moss-dev/moss-web";

// 1. Initialize the client (WASM/model download happens on first use)
const client = new MossClient("your-project-id", "your-project-key");

// 2. Create an index with documents
await client.createIndex("knowledge-base", [
  { id: "1", text: "Machine learning fundamentals" },
  { id: "2", text: "Deep learning neural networks" },
]);

// 3. Load the index into the browser for fast local queries
await client.loadIndex("knowledge-base");

// 4. Query - runs entirely in-browser
const results = await client.query("knowledge-base", "AI and neural networks");
results.docs.forEach((doc) => {
  console.log(`${doc.id}: ${doc.text} (score: ${doc.score})`);
});

```

--------------------------------

### Quick start with moss CLI

Source: https://docs.moss.dev/docs/integrations/moss-cli

A four-step workflow: save credentials, list indexes, create an index from a JSON file with `--wait`, and run a query.

```bash
# 1. Save credentials
moss init

# 2. List indexes
moss index list

# 3. Create an index from a JSON file
moss index create my-index -f docs.json --wait

# 4. Search it
moss query my-index "what is machine learning"

```

--------------------------------

### getIndexInfo example

Source: https://docs.moss.dev/docs/reference/browser/classes/MossClient

Gets information about a locally loaded index.

```typescript
const info = await client.getIndexInfo("knowledge-base");
```

--------------------------------

### getDocs() example

Source: https://docs.moss.dev/docs/reference/browser/classes/MossClient

Retrieves documents from the 'knowledge-base' index. The first call gets all documents, the second call gets specific documents by ID.

```typescript
// Get all documents
const allDocs = await client.getDocs("knowledge-base");

// Get specific documents
const specificDocs = await client.getDocs("knowledge-base", {
  docIds: ["doc1", "doc2"],
});
```

--------------------------------

### Example: Create client, session, add docs, query, and push index

Source: https://docs.moss.dev/docs/reference/elixir/classes/Session

Shows the typical workflow: create a client, open a session, add documents, query, and push the index to the cloud. Uses built-in models for automatic embeddings. The session is opened with Moss.Client.session/3.

```elixir
{:ok, client} = Moss.Client.new("project-id", "project-key")
{:ok, session} = Moss.Client.session(client, "session-abc")

docs = [
  %Moss.DocumentInfo{id: "turn-1", text: "Customer: I need to cancel my subscription"},
  %Moss.DocumentInfo{id: "turn-2", text: "Agent: I can help with that. Can I ask why?"}
]

{:ok, {2, 0}} = Moss.Session.add_docs(session, docs)
{:ok, result} = Moss.Session.query(session, "subscription cancellation", top_k: 2)
{:ok, push_result} = Moss.Session.push_index(session)
```

--------------------------------

### getIndex example

Source: https://docs.moss.dev/docs/reference/js/classes/MossClient

Gets information about a specific index. Throws if the index does not exist.

```typescript
const info = await client.getIndex('knowledge-base');
console.log(`Index has ${info.docCount} documents`);
```

--------------------------------

### Quick start: open session, add docs, query, push index

Source: https://docs.moss.dev/docs/reference/c/getting-started

Demonstrates the core workflow: create a client, open a session (auto-embeds with built-in model), add documents with optional metadata, query locally (no network round trip), and push the index to the cloud. Error checks are omitted for brevity; production code should inspect return values and call moss_last_error() on failure.

```c
#include "libmoss.h"
#include <stdio.h>

int main(void) {
    MossClient *client = NULL;
    moss_client_new("your-project-id", "your-project-key", &client);

    // Open a session (auto-embeds with the built-in model).
    MossSession *session = NULL;
    moss_client_session(client, "my-index", NULL, &session);

    // Add documents. Metadata is optional; pass NULL / 0 to skip it.
    MossDocumentInfo docs[] = {
        { .id = "1", .text = "Billing refund request" },
        { .id = "2", .text = "How to grow tomatoes" },
    };
    size_t added = 0, updated = 0;
    moss_session_add_docs(session, docs, 2, NULL, &added, &updated);

    // Query locally - no network round trip. NULL options use the defaults,
    // and the two NULL group fields skip parent grouping.
    MossSearchResult *result = NULL;
    moss_session_query(session, "refund", NULL, NULL, NULL, &result);
    for (size_t i = 0; i < result->doc_count; i++) {
        printf("%s  score=%.4f\n", result->docs[i].id, result->docs[i].score);
    }
    moss_free_search_result(result);

    // Push to the cloud so other devices can load it.
    MossPushIndexResult *push = NULL;
    moss_session_push_index(session, &push);
    moss_free_push_index_result(push);

    moss_session_free(session);
    moss_client_free(client);
    return 0;
}

```

--------------------------------

### Environment setup (.env)

Source: https://docs.moss.dev/docs/integrations/agora

Create a .env file with Moss and Agora credentials. Required before running the server.

```dotenv
# Moss Credentials
MOSS_PROJECT_ID=your_project_id
MOSS_PROJECT_KEY=your_project_key
MOSS_INDEX_NAME=support-docs

# Agora Credentials
AGORA_APP_ID=your_app_id
AGORA_APP_CERTIFICATE=your_app_certificate
AGORA_CUSTOMER_ID=your_customer_id
AGORA_CUSTOMER_SECRET=your_customer_secret

```

--------------------------------

### getJobStatus() example

Source: https://docs.moss.dev/docs/reference/browser/classes/MossClient

Gets the current status of an async operation using the provided job ID.

```typescript
const status = await client.getJobStatus(jobId);
```

--------------------------------

### Environment Setup (.env)

Source: https://docs.moss.dev/docs/integrations/livekit

Create a .env file with LiveKit, Moss, OpenAI, and Deepgram credentials. Keep LiveKit credentials as-is for local deployment.

```dotenv
# LiveKit Credentials, keep it as it is for local deployment, don't change it.
LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret

# Moss Credentials
MOSS_PROJECT_ID=your-moss-id
MOSS_PROJECT_KEY=your-moss-key

# AI Provider Keys
OPENAI_API_KEY=sk-...
DEEPGRAM_API_KEY=your-deepgram-key

```

--------------------------------

### Quick start: create index, load, and query with MossClient

Source: https://docs.moss.dev/docs/reference/js/api

Initializes a MossClient with project ID and key from environment variables, creates an index named 'faqs' with two documents, loads it, and queries for 'return a damaged product' with topK 3, logging document IDs and scores.

```typescript
import { MossClient } from '@moss-js/moss'

const client = new MossClient(process.env.MOSS_PROJECT_ID!, process.env.MOSS_PROJECT_KEY!)

await client.createIndex('faqs', [
  { id: 'doc1', text: 'Track your order in your account.', metadata: { category: 'shipping' } },
  { id: 'doc2', text: '30-day return policy for most items.', metadata: { category: 'returns' } },
])
await client.loadIndex('faqs')
const results = await client.query('faqs', 'return a damaged product', { topK: 3 })
results.docs.forEach(d => console.log(d.id, d.score))

```

--------------------------------

### Quick start: build, push, and load an on-device index

Source: https://docs.moss.dev/docs/reference/swift/api

Shows the full workflow: create a MossClient, build an on-device index with addDocs, query locally, push to the cloud, wait for the job, then load the index into a new session and query again. Documents are embedded locally and can carry metadata for filtering.

```swift
import Moss

let client = try MossClient(projectId: "your_project_id", projectKey: "your_project_key")
defer { client.close() }

// 1. Build an index on-device. Documents are embedded locally and can carry
//    metadata you filter on later.
let session = try await client.session("products")
try await session.addDocs([
  .init(id: "p1", text: "Running shoes with breathable mesh.",
        metadata: ["category": "shoes", "brand": "swiftfit", "price": "79", "city": "new-york"]),
  .init(id: "p2", text: "Lightweight city backpack.",
        metadata: ["category": "bags", "brand": "urbanpack", "price": "95", "city": "seattle"]),
])

// 2. Query locally. Tune `alpha` and add metadata filters - see the Querying guide.
let hits = try await session.query("something to run in", options: .init(topK: 3))
hits.docs.forEach { print($0.score, $0.id) }

// 3. Push it to the cloud and wait for the job to finish.
let push = try await session.pushIndex()
session.close()
while try await client.getJobStatus(push.jobId).status != "ready" {
  try await Task.sleep(nanoseconds: 1_000_000_000)
}

// 4. Load it back into a new session and query - still on-device.
let restored = try await client.session(push.indexName)
defer { restored.close() }
_ = try await restored.loadIndex(push.indexName)
let results = try await restored.query("something to run in", options: .init(topK: 3))
print(results.docs.map(\.id))

```

--------------------------------

### getJobStatus(_:)

Source: https://docs.moss.dev/docs/reference/swift/classes/MossClient

Gets the current status of an async job - for example, the job returned by MossSession.pushIndex. Poll until status is ready. Returns a JobStatus.

```APIDOC
## getJobStatus(_:)

### Description
Gets the current status of an async job - for example, the job returned by `MossSession.pushIndex`. Poll until `status` is `ready`. Returns a `JobStatus`.

### Method
async throws -> JobStatus

### Signature
```swift
func getJobStatus(_ jobId: String) async throws -> JobStatus
```

### Parameters
#### Path Parameters
- **jobId** (String) - Required - Id of the job to check.

### Request Example
```swift
let push = try await session.pushIndex()
while try await client.getJobStatus(push.jobId).status != "ready" {
  try await Task.sleep(nanoseconds: 1_000_000_000)
}
```

### Response
Returns a `JobStatus`.
```

--------------------------------

### Quick start: create client, index, load, and query

Source: https://docs.moss.dev/docs/reference/elixir/api

Initializes the client with project credentials, prepares documents, creates a cloud index (defaults to the moss-minilm model), loads it into memory, and queries it. Outputs the query and each result with id, score, and text.

```elixir
alias Moss.{Client, DocumentInfo}

# Initialize the client with your project credentials
{:ok, client} = Client.new("your-project-id", "your-project-key")

# Prepare documents to index
documents = [
  %DocumentInfo{
    id: "doc1",
    text: "How do I track my order? Log into your account to see live status.",
    metadata: %{"category" => "shipping"}
  },
  %DocumentInfo{
    id: "doc2",
    text: "What is your return policy? We offer a 30-day return policy.",
    metadata: %{"category" => "returns"}
  }
]

# Create a cloud index (defaults to the moss-minilm model)
{:ok, _} = Client.create_index(client, "faqs", documents)

# Load the index into memory before querying
{:ok, _} = Client.load_index(client, "faqs")

# Query the loaded index
{:ok, result} = Client.query(client, "faqs", "How do I return a damaged product?", top_k: 3, alpha: 0.6)

IO.puts("Query: #{result.query}")

for doc <- result.docs do
  IO.puts("#{doc.id} (#{Float.round(doc.score, 4)}): #{doc.text}")
end

```

--------------------------------

### Use OpenAI model provider with Moss

Source: https://docs.moss.dev/docs/integrations/agno

Example of using OpenAIChat as the model provider with the same knowledge setup. Any Agno-compatible model provider can be used.

```python
from agno.models.openai import OpenAIChat

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    knowledge=knowledge,
    search_knowledge=True,
)
```

--------------------------------

### Voice Agent Manager deploy() migration - after

Source: https://docs.moss.dev/docs/changelog

Shows the new signature of deploy() with voice_agent_id before prompt, and without agent_id. This is the 'After' example in the migration guide.

```python
client.deploy(
    voice_agent_id="agent-uuid",
    prompt="You are helpful"
)
```

--------------------------------

### getDocs(options:)

Source: https://docs.moss.dev/docs/reference/swift/classes/MossSession

Full-control deterministic fetch — combine ids, filter, sortBy, ascending, and groupByParent via GetDocsOptions. See the Exact / Graph Retrieval guide for worked examples.

```APIDOC
## getDocs(options:)

### Description
Full-control deterministic fetch — combine `ids`, `filter`, `sortBy`, `ascending`, and `groupByParent` via `GetDocsOptions`. See the Exact / Graph Retrieval guide for worked examples of all four overloads, the `Filter` DSL, and parent grouping.

### Method
`func getDocs(options: GetDocsOptions) async throws -> [DocumentInfo]`

### Parameters
- **options** (GetDocsOptions) - Required - Options controlling the fetch, including `ids`, `filter`, `sortBy`, `ascending`, and `groupByParent`.

### Return Value
- **[DocumentInfo]** - The documents matching the options.
```

--------------------------------

### Sync dependencies with uv for cookbook example

Source: https://docs.moss.dev/docs/integrations/sim

If using the cookbook example, sync dependencies directly with uv from the examples/cookbook/sim directory.

```bash
cd examples/cookbook/sim
uv sync

```

--------------------------------

### Wire up the entrypoint with AgentSession and MossClient

Source: https://docs.moss.dev/docs/cookbook/airline-customer-agent

Sets up the agent session with LiveKit and Moss. It loads a booking index from the BOOKING_PNR environment variable, disables preemptive generation, and configures STT, LLM, TTS, and VAD. The entrypoint is run via cli.run_app.

```python
import os
from livekit.agents import AgentSession, JobContext, TurnHandlingOptions, WorkerOptions, cli
from livekit.plugins import cartesia, deepgram, openai, silero
from moss import MossClient

async def entrypoint(ctx: JobContext):
    await ctx.connect()

    moss_client = MossClient(os.environ["MOSS_PROJECT_ID"], os.environ["MOSS_PROJECT_KEY"])
    userdata = CallSessionData(moss_client=moss_client)

    # IVR preload: if BOOKING_PNR is set, load the index before the first turn
    pnr = os.getenv("BOOKING_PNR")
    if pnr:
        await moss_client.load_index(f"booking-{pnr.lower()}")
        userdata.active_pnr = pnr.upper()
        userdata.active_index = f"booking-{pnr.lower()}"

    session = AgentSession[CallSessionData](
        userdata=userdata,
        # Ambient injection mutates the chat context every turn, so preemptive
        # generation must be off or LiveKit discards and regenerates the draft.
        turn_handling=TurnHandlingOptions(preemptive_generation={"enabled": False}),
        stt=deepgram.STT(model="nova-2"),
        llm=openai.LLM(model="gpt-4o"),
        tts=cartesia.TTS(),
        vad=silero.VAD.load(),
    )
    await session.start(agent=AirlineAgent(moss_client), room=ctx.room)

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

```

--------------------------------

### getDocs(options:)

Source: https://docs.moss.dev/docs/reference/swift/classes/MossSession

Full-control deterministic fetch — combine ids, filter, sortBy, ascending, and groupByParent via GetDocsOptions. See the Exact / Graph Retrieval guide for worked examples.

```swift
func getDocs(options: GetDocsOptions) async throws -> [DocumentInfo]

```

--------------------------------

### Voice Agent Manager deploy() migration - before

Source: https://docs.moss.dev/docs/changelog

Shows the previous signature of deploy() with agent_id, prompt, and voice_agent_id parameters. This is the 'Before' example in the migration guide for the breaking change that removed agent_id.

```python
client.deploy(
    agent_id="my-agent",
    prompt="You are helpful",
    voice_agent_id="agent-uuid"
)
```

--------------------------------

### Run program with project credentials

Source: https://docs.moss.dev/docs/reference/c/examples

Each example program expects the project ID and project key as command-line arguments. This command shows the invocation format.

```bash
./your_app <project_id> <project_key>

```

--------------------------------

### Register MossClientTool with ElevenLabs ClientTools

Source: https://docs.moss.dev/docs/integrations/elevenlabs

Create a MossClientTool, pre-load the index, register it with ElevenLabs ClientTools, and start a conversation. The tool_name must match the dashboard configuration (case-sensitive). The example uses top_k=3 and index_name='support-docs'.

```python
from elevenlabs.conversational_ai.conversation import ClientTools, Conversation
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
from elevenlabs import ElevenLabs
from elevenlabs_moss import MossClientTool

# Create and configure the Moss tool
moss_tool = MossClientTool(
    index_name="support-docs",
    tool_name="search_knowledge_base",
    top_k=3,
)

# Pre-load the index for fast queries
await moss_tool.load_index()

# Register with ElevenLabs ClientTools
client_tools = ClientTools()
moss_tool.register(client_tools)

# Start the conversation
conversation = Conversation(
    client=ElevenLabs(api_key="your-api-key"),
    agent_id="your-agent-id",
    requires_auth=False,
    audio_interface=DefaultAudioInterface(),
    client_tools=client_tools,
)
conversation.start_session()

```

--------------------------------

### Create and query an index (Python)

Source: https://docs.moss.dev/docs/start/quickstart

Python example using MossClient to create an index, load it, and query it. Uses the default model 'moss-minilm' or 'moss-mediumlm' for higher accuracy. Run with python quickstart.py.

```python
import os
import asyncio
from moss import MossClient, DocumentInfo, QueryOptions
client = MossClient(os.getenv("MOSS_PROJECT_ID"), os.getenv("MOSS_PROJECT_KEY"))
index_name = "faqs"
documents = [
    DocumentInfo(id="doc1", text="How do I track my order? You can track your order by logging into your account.", metadata={"category": "shipping"}),
    DocumentInfo(id="doc2", text="What is your return policy? We offer a 30-day return policy for most items.", metadata={"category": "returns"}),
    DocumentInfo(id="doc3", text="How can I change my shipping address? Contact our customer service team.", metadata={"category": "support"}),
]
async def main():
    await client.create_index(index_name, documents, "moss-minilm")  # default; use "moss-mediumlm" for higher accuracy
    await client.load_index(index_name)
    results = await client.query(index_name, "How do I return a damaged product?", QueryOptions(top_k=3, alpha=0.6))
    print(f"  ID: {results.docs[0].id}")
    print(f"  Text: {results.docs[0].text}")
    print(f"  Score: {results.docs[0].score}")
asyncio.run(main())

```

--------------------------------

### Environment setup (.env)

Source: https://docs.moss.dev/docs/cookbook/airline-customer-agent

Define required API keys and project credentials. Optionally preload a PNR for IVR handoff.

```dotenv
MOSS_PROJECT_ID=your-moss-project-id
MOSS_PROJECT_KEY=your-moss-project-key

OPENAI_API_KEY=your-openai-api-key
DEEPGRAM_API_KEY=your-deepgram-api-key
CARTESIA_API_KEY=your-cartesia-api-key

# Optional: preload a PNR before the first turn (IVR handoff pattern)
# BOOKING_PNR=XKQ4P2

```

--------------------------------

### Create or resume a session with client.session()

Source: https://docs.moss.dev/docs/reference/python/sessions

Creates a SessionIndex. If a cloud index with that name exists, it auto-loads; otherwise starts empty. Pass auto_load_on_init=False to skip loading. The example prints the number of existing docs loaded.

```python
import asyncio
from moss import DocumentInfo, MossClient, QueryOptions

async def main():
    client = MossClient(MOSS_PROJECT_ID, MOSS_PROJECT_KEY)

    # Auto-loads from cloud if the index exists, starts fresh if not.
    session = await client.session(index_name="my-session-index")
    print(f"{session.doc_count} existing docs loaded")

asyncio.run(main())

```

--------------------------------

### init(projectId:projectKey:)

Source: https://docs.moss.dev/docs/reference/swift/classes/MossClient

Creates a client backed by a static project key. Use this for development or when the project key can be safely embedded.

```APIDOC
## init(projectId:projectKey:)

### Description
Creates a client backed by a static project key. Use this for development or when the project key can be safely embedded.

### Method
Constructor

### Signature
```swift
init(projectId: String, projectKey: String) throws
```

### Parameters
- **projectId** (String) - Required - Your project identifier.
- **projectKey** (String) - Required - Your project authentication key. Prefer the `Authenticator` form for shipped apps so the key never ships in the binary.

### Example
```swift
let client = try MossClient(projectId: "your-project-id", projectKey: "your-project-key")
```
```

--------------------------------

### load_from_disk: Restore session with error handling

Source: https://docs.moss.dev/docs/reference/python/classes/SessionIndex

Restores a session saved by save_to_disk. A missing or damaged snapshot raises MossError with code DESERIALIZATION and leaves the session unchanged. The example shows catching that error to start with an empty session. Available in moss 1.16.0+.

```python
from moss import MossError

session = await client.session(index_name="notes", auto_load_on_init=False)
try:
    loaded = await session.load_from_disk("/var/cache/my-app/moss")
except MossError as e:
    if e.code != "DESERIALIZATION":
        raise
    loaded = 0  # no snapshot yet, so the session starts empty

```
Tokens:
Raw