moss-agent 1.0.0__tar.gz

moss_agent-1.0.0/LICENSE.txt

@@ -0,0 +1,168 @@
+Copyright (c) 2025 InferEdge Inc.
+Required Notice: Copyright InferEdge Inc. (https://inferedge.dev)
+Licensor Line of Business: InferEdge MOSS Runtime (https://inferedge.dev)
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management
+System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+[Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations than an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

moss_agent-1.0.0/PKG-INFO

@@ -0,0 +1,108 @@
+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`.

moss_agent-1.0.0/README.md

@@ -0,0 +1,75 @@
+# 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`.

moss_agent-1.0.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moss-agent"
+version = "1.0.0"
+description = "Moss runtime for LiveKit voice agents - a hot index cache shared across rooms and a one-line attach per call."
+readme = "README.md"
+license-files = ["LICENSE.txt"]
+authors = [
+    { name = "InferEdge Inc.", email = "contact@usemoss.dev" }
+]
+keywords = ["livekit", "voice-agent", "semantic-search", "moss", "usemoss"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "typing-extensions>=4.0.0",
+    "inferedge-moss-core==0.12.0",
+]
+
+[project.optional-dependencies]
+livekit = [
+    "livekit-agents>=0.10.0",
+]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "black>=25.9.0",
+    "isort>=7.0.0",
+    "mypy>=1.18.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/usemoss/moss-samples"
+Repository = "https://github.com/usemoss/moss-samples"
+Documentation = "https://docs.usemoss.dev/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.package-data]
+"moss_agent" = [
+    "py.typed",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = true
+ignore_missing_imports = true

moss_agent-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moss_agent-1.0.0/src/moss_agent/__init__.py

@@ -0,0 +1,82 @@
+"""
+Moss Agent SDK - Moss for LiveKit voice agents.
+
+A single :class:`MossAgent` lives at the process level, holding a hot
+index cache that every room the worker handles queries against - no
+per-call cold start, no duplicated state, one warm in-memory index
+serving hundreds of concurrent rooms.
+
+Two query surfaces share the same agent:
+
+* **Voice / LiveKit**: :meth:`MossAgent.attach` binds a
+  :class:`MossCall` to the room; queries via :meth:`MossCall.query`.
+* **Text / HTTP / chat**: :meth:`MossAgent.query` directly.
+
+Example - voice agent::
+
+    from moss_agent import MossAgent
+
+    # In prewarm():
+    agent = MossAgent("project-id", "project-key")
+    await agent.load_indexes(["kb1", "kb2"])
+    proc.userdata["moss_agent"] = agent
+
+    # In handle_visit(ctx):
+    await ctx.connect()
+    call = agent.attach(ctx)
+    results = await call.query("kb1", question)
+
+Example - text agent::
+
+    agent = MossAgent("project-id", "project-key")
+    await agent.load_indexes(["kb1"])
+
+    # In an HTTP handler or chat message handler:
+    results = await agent.query("kb1", user_message)
+"""
+
+from moss_core import (
+    DocumentInfo,
+    GetDocumentsOptions,
+    IndexInfo,
+    IndexStatus,
+    IndexStatusValues,
+    JobPhase,
+    JobProgress,
+    JobStatus,
+    JobStatusResponse,
+    LoadIndexesResult,
+    ModelRef,
+    MutationOptions,
+    MutationResult,
+    QueryOptions,
+    QueryResultDocumentInfo,
+    SearchResult,
+)
+
+from .client import MossAgent, MossCall, ParseFileInput
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "MossAgent",
+    "MossCall",
+    "ParseFileInput",
+    # Re-exports from moss_core
+    "DocumentInfo",
+    "GetDocumentsOptions",
+    "IndexInfo",
+    "IndexStatus",
+    "IndexStatusValues",
+    "JobPhase",
+    "JobProgress",
+    "JobStatus",
+    "JobStatusResponse",
+    "LoadIndexesResult",
+    "ModelRef",
+    "MutationOptions",
+    "MutationResult",
+    "QueryOptions",
+    "QueryResultDocumentInfo",
+    "SearchResult",
+]

moss_agent-1.0.0/src/moss_agent/client.py

@@ -0,0 +1,404 @@
+"""
+Python wrappers over the Rust ``moss_core`` Agent + CallScope.
+
+This module is intentionally thin: each method either delegates to the
+underlying Rust binding via :func:`asyncio.to_thread` (so the sync Rust
+call doesn't block the asyncio event loop) or unpacks framework-specific
+inputs (a LiveKit ``JobContext``) into the opaque correlation strings the
+Rust layer expects.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+from moss_core import (
+    Agent as _Agent,
+    DocumentInfo,
+    GetDocumentsOptions,
+    IndexInfo,
+    JobStatusResponse,
+    LoadIndexesResult,
+    MutationOptions,
+    MutationResult,
+    QueryOptions,
+    SearchResult,
+)
+
+
+@dataclass
+class ParseFileInput:
+    """
+    Input descriptor for a single file in the parse pipeline.
+
+    Either ``path`` (filesystem path) or ``data`` (raw bytes) must be
+    provided. Both ``name`` and ``content_type`` are required. Only
+    ``"application/pdf"`` is currently supported as ``content_type``.
+    """
+
+    name: str
+    content_type: str
+    path: Optional[str] = None
+    data: Optional[bytes] = None
+
+
+class MossAgent:
+    """
+    Process-wide Moss runtime for an agent process.
+
+    Owns the local index cache and auth. One per process - typically
+    constructed in LiveKit's ``prewarm()`` and stashed on
+    ``proc.userdata`` for every room handler to share.
+
+    Two query surfaces, one object:
+
+    * Voice / LiveKit: call :meth:`attach` with a ``JobContext`` to get a
+      :class:`MossCall`, then use :meth:`MossCall.query`.
+
+    * Text / HTTP / chat: call :meth:`query` (or :meth:`query_multi_index`)
+      directly on the agent.
+    """
+
+    DEFAULT_MODEL_ID = "moss-minilm"
+
+    def __init__(
+        self,
+        project_id: str,
+        project_key: str,
+        base_url: Optional[str] = None,
+        client_id: Optional[str] = None,
+    ) -> None:
+        self._inner = _Agent(
+            project_id,
+            project_key,
+            base_url=base_url,
+            client_id=client_id,
+        )
+
+    @property
+    def client_id(self) -> str:
+        return self._inner.client_id()
+
+    async def active_call_count(self) -> int:
+        """Number of currently-active call scopes (across all rooms)."""
+        return await asyncio.to_thread(self._inner.active_call_count)
+
+    # -- Index CRUD ---------------------------------------------------
+
+    async def create_index(
+        self,
+        name: str,
+        docs: List[DocumentInfo],
+        model_id: Optional[str] = None,
+    ) -> MutationResult:
+        resolved = self._resolve_model_id(docs, model_id)
+        return await asyncio.to_thread(self._inner.create_index, name, docs, resolved)
+
+    async def create_index_from_files(
+        self,
+        name: str,
+        files: List[ParseFileInput],
+        model_id: Optional[str] = None,
+    ) -> MutationResult:
+        resolved = model_id or self.DEFAULT_MODEL_ID
+        if resolved == "custom":
+            raise ValueError(
+                "create_index_from_files does not support model_id='custom' - "
+                "the parse pipeline generates embeddings server-side."
+            )
+        from moss_core import ParseFileInput as CoreParseFileInput
+
+        core_files = [
+            CoreParseFileInput(f.name, f.content_type, path=f.path, data=f.data)
+            for f in files
+        ]
+        return await asyncio.to_thread(
+            self._inner.create_index_from_files, name, core_files, resolved
+        )
+
+    async def add_docs(
+        self,
+        name: str,
+        docs: List[DocumentInfo],
+        options: Optional[MutationOptions] = None,
+    ) -> MutationResult:
+        return await asyncio.to_thread(self._inner.add_docs, name, docs, options)
+
+    async def delete_docs(self, name: str, doc_ids: List[str]) -> MutationResult:
+        return await asyncio.to_thread(self._inner.delete_docs, name, doc_ids)
+
+    async def delete_index(self, name: str) -> bool:
+        return await asyncio.to_thread(self._inner.delete_index, name)
+
+    async def list_indexes(self) -> List[IndexInfo]:
+        return await asyncio.to_thread(self._inner.list_indexes)
+
+    async def get_index(self, name: str) -> IndexInfo:
+        return await asyncio.to_thread(self._inner.get_index, name)
+
+    async def get_docs(
+        self,
+        name: str,
+        options: Optional[GetDocumentsOptions] = None,
+    ) -> List[DocumentInfo]:
+        return await asyncio.to_thread(self._inner.get_docs, name, options)
+
+    async def get_job_status(self, job_id: str) -> JobStatusResponse:
+        return await asyncio.to_thread(self._inner.get_job_status, job_id)
+
+    # -- Index lifecycle ----------------------------------------------
+
+    async def load_index(
+        self,
+        name: str,
+        auto_refresh: bool = False,
+        polling_interval_in_seconds: int = 600,
+        cache_path: Optional[str] = None,
+    ) -> IndexInfo:
+        return await asyncio.to_thread(
+            self._inner.load_index,
+            name,
+            auto_refresh,
+            polling_interval_in_seconds,
+            cache_path,
+        )
+
+    async def load_indexes(
+        self,
+        names: List[str],
+        auto_refresh: bool = False,
+        polling_interval_in_seconds: int = 600,
+        cache_path: Optional[str] = None,
+    ) -> LoadIndexesResult:
+        return await asyncio.to_thread(
+            self._inner.load_indexes,
+            names,
+            auto_refresh,
+            polling_interval_in_seconds,
+            cache_path,
+        )
+
+    async def unload_index(self, name: str) -> None:
+        await asyncio.to_thread(self._inner.unload_index, name)
+
+    async def unload_indexes(self, names: List[str]) -> None:
+        await asyncio.to_thread(self._inner.unload_indexes, names)
+
+    # -- Call lifecycle -----------------------------------------------
+
+    def attach(self, ctx: Any) -> "MossCall":
+        """
+        Bind a Moss call scope to a LiveKit ``JobContext``.
+
+        Idempotent on ``ctx.room.name`` - calling ``attach`` twice for the
+        same room returns scopes pointing at the same underlying call.
+        """
+        room = ctx.room
+        room_id: str = room.name
+        session_id: Optional[str] = None
+        job = getattr(ctx, "job", None)
+        if job is not None:
+            session_id = getattr(job, "id", None)
+
+        # `room.creation_time` is a UTC datetime; convert to ms-since-epoch.
+        creation_dt = room.creation_time
+        start_ms = int(creation_dt.timestamp() * 1000)
+
+        scope = self._inner.start_call(
+            room_id,
+            start_ms,
+            livekit_session_id=session_id,
+        )
+
+        call = MossCall(scope)
+
+        async def _on_shutdown(reason: Optional[str] = None) -> None:
+            await asyncio.to_thread(scope.end)
+
+        ctx.add_shutdown_callback(_on_shutdown)
+        return call
+
+    # -- Text-mode queries --------------------------------------------
+
+    async def query(
+        self,
+        name: str,
+        query: str,
+        *,
+        options: Optional[QueryOptions] = None,
+    ) -> SearchResult:
+        """
+        Run a text-mode query.
+
+        For voice agents serving a LiveKit room, prefer
+        :meth:`attach` + :meth:`MossCall.query` instead.
+        """
+        top_k = getattr(options, "top_k", None) or 5
+        alpha = getattr(options, "alpha", None) or 0.8
+        embedding = getattr(options, "embedding", None)
+        filter = getattr(options, "filter", None)
+
+        if embedding is None:
+            return await asyncio.to_thread(
+                self._inner.query_text,
+                name,
+                query,
+                top_k,
+                alpha,
+                filter,
+            )
+        return await asyncio.to_thread(
+            self._inner.query,
+            name,
+            query,
+            list(embedding),
+            top_k,
+            alpha,
+            filter,
+        )
+
+    async def query_multi_index(
+        self,
+        names: List[str],
+        query: str,
+        *,
+        options: Optional[QueryOptions] = None,
+    ) -> SearchResult:
+        """
+        Text-mode multi-index search. ``options.alpha`` is ignored
+        (multi-index search is embedding-only).
+        """
+        top_k = getattr(options, "top_k", None) or 10
+        embedding = getattr(options, "embedding", None)
+        filter = getattr(options, "filter", None)
+
+        if embedding is None:
+            return await asyncio.to_thread(
+                self._inner.query_multi_index_text,
+                names,
+                query,
+                top_k,
+                filter,
+            )
+        return await asyncio.to_thread(
+            self._inner.query_multi_index,
+            names,
+            query,
+            list(embedding),
+            top_k,
+            filter,
+        )
+
+    # -- Internal ------------------------------------------------------
+
+    def _resolve_model_id(
+        self, docs: List[DocumentInfo], model_id: Optional[str]
+    ) -> str:
+        if model_id is not None:
+            return model_id
+        has_embeddings = any(
+            getattr(doc, "embedding", None) is not None for doc in docs
+        )
+        return "custom" if has_embeddings else self.DEFAULT_MODEL_ID
+
+
+class MossCall:
+    """
+    Per-call handle returned by :meth:`MossAgent.attach`.
+    """
+
+    def __init__(self, scope: Any) -> None:
+        self._scope = scope
+
+    @property
+    def call_id(self) -> str:
+        return self._scope.call_id
+
+    @property
+    def livekit_room_id(self) -> str:
+        return self._scope.livekit_room_id
+
+    @property
+    def livekit_session_id(self) -> Optional[str]:
+        return self._scope.livekit_session_id
+
+    @property
+    def start_at_unix_ms(self) -> int:
+        return self._scope.start_at_unix_ms
+
+    @property
+    def has_ended(self) -> bool:
+        return self._scope.has_ended
+
+    async def query(
+        self,
+        name: str,
+        query: str,
+        options: Optional[QueryOptions] = None,
+    ) -> SearchResult:
+        """
+        Run a tagged query against a loaded index.
+
+        Matches the semantics of ``moss.MossClient.query``: if
+        ``options.embedding`` is provided we use it directly, otherwise
+        we embed the query text using the index's own model.
+        """
+        top_k = getattr(options, "top_k", None) or 5
+        alpha = getattr(options, "alpha", None) or 0.8
+        embedding = getattr(options, "embedding", None)
+        filter = getattr(options, "filter", None)
+
+        if embedding is None:
+            return await asyncio.to_thread(
+                self._scope.query_text, name, query, top_k, alpha, filter
+            )
+        return await asyncio.to_thread(
+            self._scope.query,
+            name,
+            query,
+            list(embedding),
+            top_k,
+            alpha,
+            filter,
+        )
+
+    async def query_multi_index(
+        self,
+        names: List[str],
+        query: str,
+        options: Optional[QueryOptions] = None,
+    ) -> SearchResult:
+        """
+        Search across multiple loaded indexes. ``alpha`` is ignored
+        (multi-index search is embedding-only - see the underlying
+        ``moss.MossClient.query_multi_index`` docs for why).
+        """
+        top_k = getattr(options, "top_k", None) or 10
+        embedding = getattr(options, "embedding", None)
+        filter = getattr(options, "filter", None)
+
+        if embedding is None:
+            return await asyncio.to_thread(
+                self._scope.query_multi_index_text, names, query, top_k, filter
+            )
+        return await asyncio.to_thread(
+            self._scope.query_multi_index,
+            names,
+            query,
+            list(embedding),
+            top_k,
+            filter,
+        )
+
+    async def end(self) -> None:
+        """
+        End the call scope explicitly. Idempotent.
+
+        Normally you don't need to call this - ``attach`` registers a
+        shutdown callback on the LiveKit ``JobContext`` that calls
+        ``end`` for you when the room tears down. Call it manually only
+        if you need the scope closed before the room ends.
+        """
+        await asyncio.to_thread(self._scope.end)

moss_agent-1.0.0/src/moss_agent.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+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`.

moss_agent-1.0.0/src/moss_agent.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE.txt
+README.md
+pyproject.toml
+src/moss_agent/__init__.py
+src/moss_agent/client.py
+src/moss_agent/py.typed
+src/moss_agent.egg-info/PKG-INFO
+src/moss_agent.egg-info/SOURCES.txt
+src/moss_agent.egg-info/dependency_links.txt
+src/moss_agent.egg-info/requires.txt
+src/moss_agent.egg-info/top_level.txt
+tests/test_client.py

moss_agent-1.0.0/src/moss_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moss_agent-1.0.0/src/moss_agent.egg-info/requires.txt

@@ -0,0 +1,12 @@
+typing-extensions>=4.0.0
+inferedge-moss-core==0.12.0
+
+[dev]
+pytest>=8.4.2
+pytest-asyncio>=1.2.0
+black>=25.9.0
+isort>=7.0.0
+mypy>=1.18.2
+
+[livekit]
+livekit-agents>=0.10.0

moss_agent-1.0.0/src/moss_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+moss_agent

moss_agent-1.0.0/tests/test_client.py

@@ -0,0 +1,304 @@
+"""
+Unit tests for the ``moss_agent`` Python wrapper layer.
+
+Scope: behaviors implemented in Python - constructor argument forwarding,
+LiveKit ``JobContext`` unpacking in ``attach``, query-method routing
+between embedding and text variants, asyncio bridging via
+``asyncio.to_thread``. Rust-side semantics (idempotency, lifecycle,
+concurrency, text-mode delay floor) are covered by the moss_core test
+suite.
+"""
+
+from __future__ import annotations
+
+import datetime
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ---------- Helpers ----------
+
+def _make_fake_ctx(
+    *,
+    room_name: str = "rm_1",
+    job_id: str | None = "job_1",
+    creation_time: datetime.datetime | None = None,
+):
+    """Build a minimal stand-in for ``livekit.agents.JobContext``."""
+    if creation_time is None:
+        creation_time = datetime.datetime(
+            2024, 1, 1, 0, 0, 0, tzinfo=datetime.timezone.utc
+        )
+    callbacks: list = []
+
+    ctx = MagicMock()
+    ctx.room.name = room_name
+    ctx.room.creation_time = creation_time
+    if job_id is None:
+        ctx.job = None
+    else:
+        ctx.job.id = job_id
+    ctx.add_shutdown_callback = callbacks.append
+    return ctx, callbacks
+
+
+# ---------- MossAgent constructor ----------
+
+@patch("moss_agent.client._Agent")
+def test_constructor_forwards_credentials_only(
+    mock_agent_class: MagicMock,
+) -> None:
+    from moss_agent import MossAgent
+
+    MossAgent("p", "k")
+    mock_agent_class.assert_called_once_with(
+        "p", "k", base_url=None, client_id=None
+    )
+
+
+@patch("moss_agent.client._Agent")
+def test_constructor_forwards_base_url_and_client_id(
+    mock_agent_class: MagicMock,
+) -> None:
+    from moss_agent import MossAgent
+
+    MossAgent("p", "k", base_url="http://x", client_id="cid")
+    mock_agent_class.assert_called_once_with(
+        "p", "k", base_url="http://x", client_id="cid"
+    )
+
+
+@patch("moss_agent.client._Agent")
+def test_client_id_property_reads_from_rust(mock_agent_class: MagicMock) -> None:
+    mock_agent_class.return_value.client_id.return_value = "cid-xyz"
+
+    from moss_agent import MossAgent
+
+    assert MossAgent("p", "k").client_id == "cid-xyz"
+
+
+# ---------- attach() ctx unpacking ----------
+
+@patch("moss_agent.client._Agent")
+def test_attach_converts_creation_time_to_unix_ms(
+    mock_agent_class: MagicMock,
+) -> None:
+    mock_agent_class.return_value.start_call.return_value = MagicMock()
+
+    from moss_agent import MossAgent
+
+    creation = datetime.datetime(
+        2024, 6, 15, 12, 0, 0, tzinfo=datetime.timezone.utc
+    )
+    expected_ms = int(creation.timestamp() * 1000)
+
+    ctx, _ = _make_fake_ctx(creation_time=creation)
+    MossAgent("p", "k").attach(ctx)
+
+    mock_agent_class.return_value.start_call.assert_called_once_with(
+        "rm_1",
+        expected_ms,
+        livekit_session_id="job_1",
+    )
+
+
+@patch("moss_agent.client._Agent")
+def test_attach_handles_missing_job(mock_agent_class: MagicMock) -> None:
+    mock_agent_class.return_value.start_call.return_value = MagicMock()
+
+    from moss_agent import MossAgent
+
+    ctx, _ = _make_fake_ctx(job_id=None)
+    MossAgent("p", "k").attach(ctx)
+
+    _, kwargs = mock_agent_class.return_value.start_call.call_args
+    assert kwargs["livekit_session_id"] is None
+
+
+@patch("moss_agent.client._Agent")
+def test_attach_registers_shutdown_callback(
+    mock_agent_class: MagicMock,
+) -> None:
+    mock_agent_class.return_value.start_call.return_value = MagicMock()
+
+    from moss_agent import MossAgent
+
+    ctx, callbacks = _make_fake_ctx()
+    MossAgent("p", "k").attach(ctx)
+
+    assert len(callbacks) == 1
+
+
+@pytest.mark.asyncio
+@patch("moss_agent.client._Agent")
+async def test_attach_shutdown_callback_invokes_scope_end(
+    mock_agent_class: MagicMock,
+) -> None:
+    scope = MagicMock()
+    mock_agent_class.return_value.start_call.return_value = scope
+
+    from moss_agent import MossAgent
+
+    ctx, callbacks = _make_fake_ctx()
+    MossAgent("p", "k").attach(ctx)
+
+    await callbacks[0]("test reason")
+    scope.end.assert_called_once()
+
+
+# ---------- MossAgent text-mode query routing ----------
+
+@pytest.mark.asyncio
+@patch("moss_agent.client._Agent")
+async def test_text_query_without_embedding_uses_query_text(
+    mock_agent_class: MagicMock,
+) -> None:
+    inner = mock_agent_class.return_value
+
+    from moss_agent import MossAgent
+
+    await MossAgent("p", "k").query("kb1", "hello")
+    inner.query_text.assert_called_once_with("kb1", "hello", 5, 0.8, None)
+    inner.query.assert_not_called()
+
+
+@pytest.mark.asyncio
+@patch("moss_agent.client._Agent")
+async def test_text_query_with_embedding_uses_embedding_path(
+    mock_agent_class: MagicMock,
+) -> None:
+    inner = mock_agent_class.return_value
+    options = SimpleNamespace(
+        top_k=10, alpha=0.7, embedding=[0.1, 0.2, 0.3], filter=None
+    )
+
+    from moss_agent import MossAgent
+
+    await MossAgent("p", "k").query("kb1", "hello", options=options)
+    inner.query.assert_called_once_with(
+        "kb1", "hello", [0.1, 0.2, 0.3], 10, 0.7, None
+    )
+    inner.query_text.assert_not_called()
+
+
+@pytest.mark.asyncio
+@patch("moss_agent.client._Agent")
+async def test_text_multi_index_without_embedding_uses_text_variant(
+    mock_agent_class: MagicMock,
+) -> None:
+    inner = mock_agent_class.return_value
+
+    from moss_agent import MossAgent
+
+    await MossAgent("p", "k").query_multi_index(["kb1", "kb2"], "hello")
+    inner.query_multi_index_text.assert_called_once_with(
+        ["kb1", "kb2"], "hello", 10, None
+    )
+    inner.query_multi_index.assert_not_called()
+
+
+@pytest.mark.asyncio
+@patch("moss_agent.client._Agent")
+async def test_text_multi_index_with_embedding_uses_embedding_variant(
+    mock_agent_class: MagicMock,
+) -> None:
+    inner = mock_agent_class.return_value
+    options = SimpleNamespace(top_k=5, embedding=[0.1, 0.2], filter=None)
+
+    from moss_agent import MossAgent
+
+    await MossAgent("p", "k").query_multi_index(
+        ["kb1", "kb2"], "hello", options=options
+    )
+    inner.query_multi_index.assert_called_once_with(
+        ["kb1", "kb2"], "hello", [0.1, 0.2], 5, None
+    )
+    inner.query_multi_index_text.assert_not_called()
+
+
+# ---------- MossCall accessors ----------
+
+def test_moss_call_passthrough_properties() -> None:
+    scope = MagicMock()
+    scope.call_id = "cid"
+    scope.livekit_room_id = "rm_1"
+    scope.livekit_session_id = "sess"
+    scope.start_at_unix_ms = 12345
+    scope.has_ended = False
+
+    from moss_agent import MossCall
+
+    call = MossCall(scope)
+    assert call.call_id == "cid"
+    assert call.livekit_room_id == "rm_1"
+    assert call.livekit_session_id == "sess"
+    assert call.start_at_unix_ms == 12345
+    assert call.has_ended is False
+
+
+# ---------- MossCall.query routing (voice) ----------
+
+@pytest.mark.asyncio
+async def test_call_query_without_embedding_uses_query_text() -> None:
+    scope = MagicMock()
+
+    from moss_agent import MossCall
+
+    await MossCall(scope).query("kb1", "hello")
+    scope.query_text.assert_called_once_with("kb1", "hello", 5, 0.8, None)
+    scope.query.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_call_query_with_embedding_uses_embedding_path() -> None:
+    scope = MagicMock()
+    options = SimpleNamespace(
+        top_k=10, alpha=0.7, embedding=[0.1, 0.2, 0.3], filter=None
+    )
+
+    from moss_agent import MossCall
+
+    await MossCall(scope).query("kb1", "hello", options)
+    scope.query.assert_called_once_with(
+        "kb1", "hello", [0.1, 0.2, 0.3], 10, 0.7, None
+    )
+    scope.query_text.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_call_query_multi_index_without_embedding_uses_text_variant() -> None:
+    scope = MagicMock()
+
+    from moss_agent import MossCall
+
+    await MossCall(scope).query_multi_index(["kb1", "kb2"], "hello")
+    scope.query_multi_index_text.assert_called_once_with(
+        ["kb1", "kb2"], "hello", 10, None
+    )
+    scope.query_multi_index.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_call_query_multi_index_with_embedding_uses_embedding_variant() -> None:
+    scope = MagicMock()
+    options = SimpleNamespace(top_k=5, embedding=[0.1, 0.2], filter=None)
+
+    from moss_agent import MossCall
+
+    await MossCall(scope).query_multi_index(["kb1", "kb2"], "hello", options)
+    scope.query_multi_index.assert_called_once_with(
+        ["kb1", "kb2"], "hello", [0.1, 0.2], 5, None
+    )
+    scope.query_multi_index_text.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_call_end_invokes_scope_end() -> None:
+    scope = MagicMock()
+
+    from moss_agent import MossCall
+
+    await MossCall(scope).end()
+    scope.end.assert_called_once()