Metadata-Version: 2.4
Name: moss-agent
Version: 1.0.0
Summary: Moss runtime for LiveKit voice agents - a hot index cache shared across rooms and a one-line attach per call.
Author-email: "InferEdge Inc." <contact@usemoss.dev>
Project-URL: Homepage, https://github.com/usemoss/moss-samples
Project-URL: Repository, https://github.com/usemoss/moss-samples
Project-URL: Documentation, https://docs.usemoss.dev/
Keywords: livekit,voice-agent,semantic-search,moss,usemoss
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: inferedge-moss-core==0.12.0
Provides-Extra: livekit
Requires-Dist: livekit-agents>=0.10.0; extra == "livekit"
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.2.0; extra == "dev"
Requires-Dist: black>=25.9.0; extra == "dev"
Requires-Dist: isort>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.18.2; extra == "dev"
Dynamic: license-file

# moss-agent

Moss runtime for LiveKit voice agents - a hot index cache shared across rooms and a one-line attach per call.

## Install

```bash
pip install moss-agent
```

## Use - voice (LiveKit)

```python
from livekit.agents import AgentServer, JobContext, JobProcess
from moss_agent import MossAgent

server = AgentServer()


def prewarm(proc: JobProcess) -> None:
    agent = MossAgent(
        project_id="...",
        project_key="...",
    )
    import asyncio
    asyncio.run(agent.load_indexes(["product_catalog", "faq", "policies"]))
    proc.userdata["moss_agent"] = agent


server.setup_fnc = prewarm


@server.rtc_session(agent_name="my-agent")
async def handle_visit(ctx: JobContext) -> None:
    await ctx.connect()

    agent: MossAgent = ctx.proc.userdata["moss_agent"]
    call = agent.attach(ctx)

    results = await call.query("product_catalog", user_question)
    # ... your existing agent loop ...
```

## Use - text (HTTP / chat / non-LiveKit)

```python
from moss_agent import MossAgent

# Module level - reuse across requests
agent = MossAgent(project_id="...", project_key="...")
await agent.load_indexes(["product_catalog"])


# In your HTTP / chat handler
async def handle_message(req):
    results = await agent.query("product_catalog", req.user_message)
    # ... feed results to your model ...
```

## API surface

- `MossAgent(project_id, project_key)` - process-wide instance. Build once, share across every room (voice) or every request (text).
- **Voice:** `MossAgent.attach(ctx) -> MossCall` binds a Moss call scope to a LiveKit `JobContext`. Idempotent on `ctx.room.name`. `MossCall.query(name, query, options=None)` and `MossCall.query_multi_index(names, query, options=None)` are the call-scoped query surface.
- **Text:** `MossAgent.query(name, query, options=None)` and `MossAgent.query_multi_index(names, query, options=None)`.
- Full index CRUD (`create_index`, `add_docs`, `delete_docs`, `delete_index`, `list_indexes`, `get_index`, `get_docs`, `get_job_status`) and cache lifecycle (`load_index`, `load_indexes`, `unload_index`, `unload_indexes`) on `MossAgent`.

## Requirements

- Python 3.10+
- `inferedge-moss-core == 0.12.0`
- `livekit-agents >= 0.10.0` (only required if you call `attach()`; install via the `[livekit]` extra)

## License

Proprietary. See `LICENSE.txt`.
