docs(ten-moss): add create-index example, docs, and repo integration entry

Author: HarshaNalluru

AGENTS.md

@@ -62,6 +62,7 @@ packages/
   moss-md-indexer/       — Markdown docs → Moss index builder
   pipecat-moss/          — Pipecat Python integration package
   strands-agents-moss/   — AWS Strands Agents integration package
+  ten-moss/              — TEN Framework ambient Moss retrieval helper (MossRetrievalStore)
   vapi-moss/             — VAPI Custom Knowledge Base webhook adapter
   vercel-sdk/            — Vercel AI SDK tool wrappers (@moss-tools/vercel-sdk)
   vitepress-plugin-moss/ — VitePress search plugin (on-device fallback after cloud)
@@ -137,6 +138,7 @@ asks for an experimental landing spot.
 | `pipecat-moss/` | `pipecat-moss` | `MossPipecatTool` — retrieval tool for Pipecat pipeline services |
 | `sim-moss/` | `sim-moss` | `MossSimSearch` — knowledge base adapter for sim.ai workflow HTTP tool nodes |
 | `strands-agents-moss/` | `strands-agents-moss` | Moss tool for AWS Strands Agents |
+| `ten-moss/` | `ten-moss` | `MossRetrievalStore` — ambient Moss retrieval for TEN Framework control extensions |
 | `vapi-moss/` | `vapi-moss` | `MossVapiSearch` adapter + HMAC webhook verification for VAPI |
 | `vercel-sdk/` | `@moss-tools/vercel-sdk` | Vercel AI SDK 6 `tool()` wrappers: search, create index, manage documents |
 | `vitepress-plugin-moss/` | `vitepress-plugin-moss` | VitePress plugin: cloud search on first keystroke, on-device after index download |

packages/ten-moss/.env.example

@@ -0,0 +1,3 @@
+MOSS_PROJECT_ID=your_moss_project_id
+MOSS_PROJECT_KEY=your_moss_project_key
+MOSS_INDEX_NAME=ten-moss-demo

packages/ten-moss/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-07-14
+
+### Added
+- `MossRetrievalStore` — ambient Moss retrieval with `load`, `retrieve`, `format_context`, and `from_config`.
+- `MossRetrievalConfig` — standardized `moss_*` properties for TEN extensions.
+- `examples/create_index.py` — create and populate a demo index.

packages/ten-moss/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing to ten-moss
+
+## Setup
+
+```bash
+cd packages/ten-moss
+uv sync
+```
+
+## Test & lint
+
+```bash
+uv run pytest tests/ -v
+uv run ruff check .
+uv run ruff format --check .
+```
+
+Tests are offline (the Moss client is mocked) — no credentials required.

packages/ten-moss/README.md

@@ -0,0 +1,71 @@
+# ten-moss
+
+Ambient sub-10ms semantic retrieval for the [TEN Framework](https://github.com/ten-framework/ten-framework), powered by [Moss](https://moss.dev).
+
+`MossRetrievalStore` loads a Moss index once and returns a formatted context
+block for each user turn — drop it into a TEN control extension to ground your
+voice agent's answers. Retrieval failures degrade to an empty string, so the
+voice loop never stalls.
+
+See `apps/ten-moss/` for a full runnable TEN voice-assistant example.
+
+## Install
+
+```bash
+pip install ten-moss   # or: uv add ten-moss
+```
+
+## Usage
+
+```python
+from ten_moss import MossRetrievalStore
+
+store = MossRetrievalStore(
+    project_id="...", project_key="...", index_name="support-docs",
+    top_k=5, alpha=0.8,
+)
+await store.load()                          # once, at startup
+context = await store.retrieve(user_text)   # per turn; "" on no hits/error
+```
+
+Or build it from TEN properties:
+
+```python
+from ten_moss import MossRetrievalConfig, MossRetrievalStore
+
+config = MossRetrievalConfig(**props)          # moss_* fields from property.json
+store = MossRetrievalStore.from_config(config)
+```
+
+## Configuration (`MossRetrievalConfig`)
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `moss_project_id` | `""` | Moss project id |
+| `moss_project_key` | `""` | Moss project key |
+| `moss_index_name` | `""` | index to load and query |
+| `moss_top_k` | `5` | results per query |
+| `moss_alpha` | `0.8` | semantic/keyword blend (1.0 semantic, 0.0 keyword) |
+| `moss_context_header` | `"Relevant knowledge from Moss:"` | header of the injected block |
+| `enable_moss` | `true` | master toggle |
+
+## Create a demo index
+
+```bash
+cp .env.example .env   # fill in your Moss credentials
+python examples/create_index.py
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -v
+uv run ruff check .
+```
+
+Tests are offline (the Moss client is mocked) — no credentials required.
+
+## License
+
+BSD-2-Clause.

packages/ten-moss/examples/create_index.py

@@ -0,0 +1,83 @@
+"""Create and populate a demo Moss index for the ten-moss integration.
+
+Usage:
+    export MOSS_PROJECT_ID=... MOSS_PROJECT_KEY=... MOSS_INDEX_NAME=...
+    python examples/create_index.py
+"""
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+from loguru import logger
+from moss import DocumentInfo, MossClient
+
+
+def build_documents() -> list[DocumentInfo]:
+    """Return a small support knowledge base for the demo index."""
+    return [
+        DocumentInfo(
+            id="doc-1",
+            text="Refunds are processed within 3-5 business days once approved.",
+            metadata={"category": "billing"},
+        ),
+        DocumentInfo(
+            id="doc-2",
+            text="You can track your order from the dashboard under Order History.",
+            metadata={"category": "orders"},
+        ),
+        DocumentInfo(
+            id="doc-3",
+            text="We offer 24/7 live chat support from the Help menu.",
+            metadata={"category": "support"},
+        ),
+        DocumentInfo(
+            id="doc-4",
+            text="Standard shipping takes 3-5 business days; express takes 1-2.",
+            metadata={"category": "shipping"},
+        ),
+        DocumentInfo(
+            id="doc-5",
+            text="Reset your password using the Forgot Password link on the login page.",
+            metadata={"category": "account"},
+        ),
+        DocumentInfo(
+            id="doc-6",
+            text="We accept Visa, Mastercard, American Express, PayPal, and Apple Pay.",
+            metadata={"category": "billing"},
+        ),
+        DocumentInfo(
+            id="doc-7",
+            text="Orders can be cancelled within 1 hour of placement.",
+            metadata={"category": "orders"},
+        ),
+        DocumentInfo(
+            id="doc-8",
+            text="International shipping is available to most countries; rates vary.",
+            metadata={"category": "shipping"},
+        ),
+        DocumentInfo(
+            id="doc-9",
+            text="Gift wrapping is available at checkout for a small fee.",
+            metadata={"category": "services"},
+        ),
+        DocumentInfo(
+            id="doc-10",
+            text="We price-match authorized retailers within 14 days of purchase.",
+            metadata={"category": "billing"},
+        ),
+    ]
+
+
+async def main() -> None:
+    """Create the index named by MOSS_INDEX_NAME from build_documents()."""
+    load_dotenv()
+    client = MossClient(os.environ["MOSS_PROJECT_ID"], os.environ["MOSS_PROJECT_KEY"])
+    index_name = os.environ["MOSS_INDEX_NAME"]
+    logger.info("Creating index {}", index_name)
+    await client.create_index(name=index_name, docs=build_documents(), model_id="moss-minilm")
+    logger.success("Index {} created", index_name)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

packages/ten-moss/tests/test_retrieval_store.py

@@ -1,6 +1,8 @@
 """Offline tests for the ten-moss helper package."""
 
 import asyncio
+import importlib.util
+import pathlib
 import unittest
 from unittest.mock import AsyncMock, MagicMock, patch
 
@@ -129,5 +131,23 @@ async def test_from_config_builds_store(self, cls):
         self.assertEqual(store._context_header, "H")
 
 
+class TestCreateIndexExample(unittest.TestCase):
+    """The example script exposes a testable build_documents()."""
+
+    def _load_example(self):
+        path = pathlib.Path(__file__).parent.parent / "examples" / "create_index.py"
+        spec = importlib.util.spec_from_file_location("_ten_moss_create_index", path)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+
+    def test_build_documents_returns_ten_docs(self):
+        module = self._load_example()
+        docs = module.build_documents()
+        self.assertEqual(len(docs), 10)
+        self.assertTrue(all(d.text for d in docs))
+        self.assertEqual(len({d.id for d in docs}), 10)  # unique ids
+
+
 if __name__ == "__main__":
     unittest.main()