> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Moss

> Knowledge retrieval service that injects semantic search results from Moss vector indexes into a Pipecat agent's LLM context

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="usemoss" maintainerUrl="https://github.com/usemoss" repo="https://github.com/usemoss/pipecat-moss" />

## Overview

`MossRetrievalService` performs low-latency semantic retrieval against
[Moss](https://www.usemoss.dev/) vector indexes and injects the relevant
passages into your Pipecat agent's LLM context. Its `query()` method returns a
`MossIndexProcessor` that you place in the pipeline to augment each user turn
with context-aware search results.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/usemoss/pipecat-moss">
    Source code, examples, and issues for the Moss integration
  </Card>

  <Card title="PyPI Package" icon="cube" href="https://pypi.org/project/pipecat-moss/">
    The `pipecat-moss` package on PyPI
  </Card>

  <Card title="Moss" icon="book" href="https://www.usemoss.dev/">
    Learn more about Moss semantic retrieval
  </Card>

  <Card title="Moss Portal" icon="key" href="https://portal.usemoss.dev">
    Create a project and get your project ID and key
  </Card>
</CardGroup>

## Installation

This is a community-maintained package distributed separately from `pipecat-ai`:

```bash theme={null}
pip install pipecat-moss
```

## Prerequisites

### Moss Project Setup

Before using the Moss retrieval service, you need:

1. **Moss Project**: Create a project in the [Moss Portal](https://portal.usemoss.dev)
2. **Project Credentials**: Get your project ID and project key from the portal
3. **A Moss Index**: Create and populate an index before running your pipeline
   (see the [source repository](https://github.com/usemoss/pipecat-moss) for the
   index-creation example)

### Required Environment Variables

* `MOSS_PROJECT_ID`: Your Moss project ID
* `MOSS_PROJECT_KEY`: Your Moss project key

## Configuration

### MossRetrievalService

<ParamField path="project_id" type="str" default="None">
  Moss project ID. Can be supplied via the `MOSS_PROJECT_ID` environment
  variable.
</ParamField>

<ParamField path="project_key" type="str" default="None">
  Moss project key. Can be supplied via the `MOSS_PROJECT_KEY` environment
  variable.
</ParamField>

<ParamField path="system_prompt" type="str" default="Here is additional context retrieved from database:\n\n">
  Prefix prepended to the retrieved documents before they are added to the LLM
  context.
</ParamField>

Load an index before the pipeline runs with the awaitable
`load_index(index_name)` method, then create a pipeline processor with
`query(index_name, *, top_k=5, alpha=0.8)`.

### query() parameters

<ParamField path="index_name" type="str" required>
  Name of the Moss index to retrieve from.
</ParamField>

<ParamField path="top_k" type="int" default="5">
  Number of documents to retrieve per query.
</ParamField>

<ParamField path="alpha" type="float" default="0.8">
  Blends semantic vs. keyword scoring. `0.0` is keyword-only and `1.0` is
  semantic-only.
</ParamField>

## Usage

```python theme={null}
import os
import asyncio
from pipecat_moss import MossRetrievalService
from pipecat.pipeline.pipeline import Pipeline

moss_service = MossRetrievalService(
    project_id=os.getenv("MOSS_PROJECT_ID"),
    project_key=os.getenv("MOSS_PROJECT_KEY"),
    system_prompt="Relevant passages from the Moss knowledge base:\n\n",
)

async def setup_indexes():
    await moss_service.load_index(os.getenv("MOSS_INDEX_NAME"))

asyncio.run(setup_indexes())

pipeline = Pipeline([
    transport.input(),               # audio/user input
    stt,                             # speech to text
    context_aggregator.user(),       # add user text to context
    moss_service.query(os.getenv("MOSS_INDEX_NAME"), top_k=5, alpha=0.8),  # retrieve docs
    llm,                             # LLM generates response
    tts,                             # TTS synthesis
    transport.output(),              # stream audio back to user
    context_aggregator.assistant(),  # store assistant response
])
```

<Note>
  `setup_indexes()` must be awaited before the pipeline starts so the service
  can load the Moss index. See the [source
  repository](https://github.com/usemoss/pipecat-moss) for a complete working
  example.
</Note>

## Compatibility

Tested with Pipecat v0.0.99. Check the [source
repository](https://github.com/usemoss/pipecat-moss) for the latest tested
version and changelog.