moss 1.0.0__py3-none-any.whl

moss/__init__.py

@@ -0,0 +1,62 @@
+"""
+Moss Semantic Search SDK
+
+Powerful Python SDK for semantic search using state-of-the-art embedding models.
+
+Example:
+    ```python
+    from moss import MossClient, DocumentInfo
+
+    client = MossClient('your-project-id', 'your-project-key')
+
+    docs = [DocumentInfo(id="1", text="Example document")]
+
+    result = await client.create_index('my-index', docs, 'moss-minilm')
+
+    await client.load_index('my-index')
+    results = await client.query('my-index', 'search query')
+    ```
+"""
+
+from moss_core import (
+    DocumentInfo,
+    GetDocumentsOptions,
+    IndexInfo,
+    IndexStatus,
+    IndexStatusValues,
+    ModelRef,
+    MutationOptions,
+    MutationResult,
+    JobStatus,
+    JobPhase,
+    JobProgress,
+    JobStatusResponse,
+    QueryOptions,
+    QueryResultDocumentInfo,
+    SearchResult,
+)
+
+from .client.moss_client import MossClient
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "MossClient",
+    # Core data types
+    "DocumentInfo",
+    "GetDocumentsOptions",
+    "IndexInfo",
+    "SearchResult",
+    "QueryResultDocumentInfo",
+    "ModelRef",
+    "IndexStatus",
+    "IndexStatusValues",
+    "QueryOptions",
+    # Mutation types
+    "MutationResult",
+    "MutationOptions",
+    "JobStatus",
+    "JobPhase",
+    "JobProgress",
+    "JobStatusResponse",
+]

moss/__init__.pyi

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from typing import ClassVar, Dict, List, Optional, Sequence
+
+
+class MossClient:
+    """Semantic search client for vector similarity operations."""
+
+    DEFAULT_MODEL_ID: ClassVar[str]
+
+    def __init__(self, project_id: str, project_key: str) -> None: ...
+
+    async def create_index(
+        self,
+        name: str,
+        docs: List[DocumentInfo],
+        model_id: Optional[str] = ...,
+    ) -> MutationResult: ...
+
+    async def add_docs(
+        self,
+        name: str,
+        docs: List[DocumentInfo],
+        options: Optional[MutationOptions] = None,
+    ) -> MutationResult: ...
+
+    async def delete_docs(
+        self,
+        name: str,
+        doc_ids: List[str],
+    ) -> MutationResult: ...
+
+    async def get_job_status(self, job_id: str) -> JobStatusResponse: ...
+
+    async def get_index(self, name: str) -> IndexInfo: ...
+
+    async def list_indexes(self) -> List[IndexInfo]: ...
+
+    async def delete_index(self, name: str) -> bool: ...
+
+    async def get_docs(
+        self,
+        name: str,
+        options: Optional[GetDocumentsOptions] = None,
+    ) -> List[DocumentInfo]: ...
+
+    async def load_index(
+        self,
+        name: str,
+        auto_refresh: bool = False,
+        polling_interval_in_seconds: int = 600,
+    ) -> str: ...
+
+    async def unload_index(self, name: str) -> None: ...
+
+    async def query(
+        self,
+        name: str,
+        query: str,
+        options: Optional[QueryOptions] = None,
+    ) -> SearchResult: ...
+
+
+class MutationResult:
+    """Return value from create_index/add_docs/delete_docs."""
+
+    job_id: str
+    index_name: str
+    doc_count: int
+
+
+class MutationOptions:
+    """Options for add_docs (e.g. upsert behavior)."""
+
+    upsert: Optional[bool]
+
+    def __init__(self, upsert: Optional[bool] = None) -> None: ...
+
+
+class GetDocumentsOptions:
+    """Options for get_docs (e.g. filter by document IDs)."""
+
+    doc_ids: Optional[List[str]]
+
+    def __init__(self, doc_ids: Optional[List[str]] = None) -> None: ...
+
+
+class JobStatus:
+    """Enum-like class for job status values."""
+
+    PENDING_UPLOAD: ClassVar[str]
+    UPLOADING: ClassVar[str]
+    BUILDING: ClassVar[str]
+    COMPLETED: ClassVar[str]
+    FAILED: ClassVar[str]
+
+    value: str
+
+
+class JobPhase:
+    """Enum-like class for job phase values."""
+
+    DOWNLOADING: ClassVar[str]
+    DESERIALIZING: ClassVar[str]
+    GENERATING_EMBEDDINGS: ClassVar[str]
+    BUILDING_INDEX: ClassVar[str]
+    UPLOADING: ClassVar[str]
+    CLEANUP: ClassVar[str]
+
+    value: str
+
+
+class JobProgress:
+    """Progress update for a job."""
+
+    job_id: str
+    status: JobStatus
+    progress: float
+    current_phase: Optional[JobPhase]
+
+
+class JobStatusResponse:
+    """Full status response from get_job_status."""
+
+    job_id: str
+    status: JobStatus
+    progress: float
+    current_phase: Optional[JobPhase]
+    error: Optional[str]
+    created_at: str
+    updated_at: str
+    completed_at: Optional[str]
+
+
+class ModelRef:
+    id: str
+    version: str
+    def __init__(self, id: str, version: str) -> None: ...
+
+
+class QueryResultDocumentInfo:
+    id: str
+    text: str
+    metadata: Optional[Dict[str, str]]
+    score: float
+    def __init__(
+        self,
+        id: str,
+        text: str,
+        metadata: Optional[Dict[str, str]] = ...,
+        score: float = ...,
+    ) -> None: ...
+
+
+class DocumentInfo:
+    id: str
+    text: str
+    metadata: Optional[Dict[str, str]]
+    embedding: Optional[Sequence[float]]
+    def __init__(
+        self,
+        id: str,
+        text: str,
+        metadata: Optional[Dict[str, str]] = ...,
+        embedding: Optional[Sequence[float]] = ...,
+    ) -> None: ...
+
+
+class QueryOptions:
+    embedding: Optional[Sequence[float]]
+    top_k: Optional[int]
+    alpha: Optional[float]
+    filter: Optional[dict]
+    def __init__(
+        self,
+        embedding: Optional[Sequence[float]] = ...,
+        top_k: Optional[int] = ...,
+        alpha: Optional[float] = ...,
+        filter: Optional[dict] = ...,
+    ) -> None: ...
+
+
+class IndexInfo:
+    id: str
+    name: str
+    version: str
+    status: str
+    doc_count: int
+    created_at: str
+    updated_at: str
+    model: ModelRef
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        version: str,
+        status: str,
+        doc_count: int,
+        created_at: str,
+        updated_at: str,
+        model: ModelRef,
+    ) -> None: ...
+
+
+class SearchResult:
+    docs: List[QueryResultDocumentInfo]
+    query: str
+    index_name: Optional[str]
+    time_taken_ms: Optional[int]
+    def __init__(
+        self,
+        docs: List[QueryResultDocumentInfo],
+        query: str,
+        index_name: Optional[str] = None,
+        time_taken_ms: Optional[int] = None,
+    ) -> None: ...
+
+
+class IndexStatus:
+    NotStarted: ClassVar[str]
+    Building: ClassVar[str]
+    Ready: ClassVar[str]
+    Failed: ClassVar[str]
+    def __init__(self, value: str) -> None: ...
+
+
+IndexStatusValues: Dict[str, str]
+
+__version__: str
+
+__all__ = [
+    "MossClient",
+    "DocumentInfo",
+    "GetDocumentsOptions",
+    "IndexInfo",
+    "SearchResult",
+    "QueryResultDocumentInfo",
+    "ModelRef",
+    "IndexStatus",
+    "IndexStatusValues",
+    "QueryOptions",
+    "MutationResult",
+    "MutationOptions",
+    "JobStatus",
+    "JobPhase",
+    "JobProgress",
+    "JobStatusResponse",
+]

moss/client/moss_client.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import uuid
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+from moss_core import (
+    CLOUD_API_MANAGE_URL,
+    ManageClient,
+    DocumentInfo,
+    GetDocumentsOptions,
+    IndexInfo,
+    IndexManager,
+    MutationOptions,
+    MutationResult,
+    JobStatusResponse,
+    QueryOptions,
+    QueryResultDocumentInfo,
+    SearchResult,
+)
+
+
+def _get_manage_url() -> str:
+    """Manage URL, overridable via env for local development."""
+    return os.getenv("MOSS_CLOUD_API_MANAGE_URL", CLOUD_API_MANAGE_URL)
+
+
+def _get_query_url() -> str:
+    """Query URL, derived from manage URL or overridable via env."""
+    explicit = os.getenv("MOSS_CLOUD_QUERY_URL")
+    if explicit:
+        return explicit
+    return _get_manage_url().replace("/v1/manage", "/query")
+
+
+class MossClient:
+    """
+    Semantic search client for vector similarity operations.
+
+    All mutations and reads go through the Rust ManageClient.
+    Querying uses the local IndexManager when the index is loaded,
+    otherwise falls back to the cloud query API.
+
+    Example:
+        ```python
+        from moss import MossClient, DocumentInfo
+
+        client = MossClient("project-id", "project-key")
+
+        docs = [DocumentInfo(id="1", text="Machine learning fundamentals")]
+        result = await client.create_index("my-index", docs, "moss-minilm")
+
+        await client.load_index("my-index")
+        results = await client.query("my-index", "AI and neural networks")
+        ```
+    """
+
+    DEFAULT_MODEL_ID = "moss-minilm"
+
+    def __init__(self, project_id: str, project_key: str) -> None:
+        self._project_id = project_id
+        self._project_key = project_key
+        self._client_id = str(uuid.uuid4())
+        manage_url = _get_manage_url()
+        self._manage = ManageClient(project_id, project_key, manage_url, self._client_id)
+        self._manager = IndexManager(project_id, project_key, manage_url, self._client_id)
+
+    # -- Mutations (via Rust ManageClient) --------------------------
+
+    async def create_index(
+        self,
+        name: str,
+        docs: List[DocumentInfo],
+        model_id: Optional[str] = None,
+    ) -> MutationResult:
+        """Create a new index and populate it with documents."""
+        resolved_model_id = self._resolve_model_id(docs, model_id)
+        return await asyncio.to_thread(
+            self._manage.create_index, name, docs, resolved_model_id,
+        )
+
+    async def add_docs(
+        self,
+        name: str,
+        docs: List[DocumentInfo],
+        options: Optional[MutationOptions] = None,
+    ) -> MutationResult:
+        """Add or update documents in an index."""
+        return await asyncio.to_thread(
+            self._manage.add_docs, name, docs, options,
+        )
+
+    async def delete_docs(
+        self,
+        name: str,
+        doc_ids: List[str],
+    ) -> MutationResult:
+        """Delete documents from an index by their IDs."""
+        return await asyncio.to_thread(
+            self._manage.delete_docs, name, doc_ids,
+        )
+
+    async def get_job_status(self, job_id: str) -> JobStatusResponse:
+        """Get the status of a bulk operation job."""
+        return await asyncio.to_thread(self._manage.get_job_status, job_id)
+
+    # -- Read operations (via Rust ManageClient) --------------------
+
+    async def get_index(self, name: str) -> IndexInfo:
+        """Get information about a specific index."""
+        return await asyncio.to_thread(self._manage.get_index, name)
+
+    async def list_indexes(self) -> List[IndexInfo]:
+        """List all indexes with their information."""
+        return await asyncio.to_thread(self._manage.list_indexes)
+
+    async def delete_index(self, name: str) -> bool:
+        """Delete an index and all its data."""
+        return await asyncio.to_thread(self._manage.delete_index, name)
+
+    async def get_docs(
+        self,
+        name: str,
+        options: Optional[GetDocumentsOptions] = None,
+    ) -> List[DocumentInfo]:
+        """Retrieve documents from an index."""
+        return await asyncio.to_thread(self._manage.get_docs, name, options)
+
+    # -- Index loading & querying -----------------------------------
+
+    async def load_index(
+        self,
+        name: str,
+        auto_refresh: bool = False,
+        polling_interval_in_seconds: int = 600,
+    ) -> str:
+        """
+        Downloads an index from the cloud into memory for fast local querying.
+
+        Without load_index(), query() falls back to the cloud API (~100-500ms).
+        With load_index(), queries run entirely in-memory (~1-10ms).
+        """
+        try:
+            await asyncio.to_thread(
+                self._manager.load_index, name, auto_refresh, polling_interval_in_seconds,
+            )
+            await asyncio.to_thread(self._manager.load_query_model, name)
+            return name
+        except RuntimeError as e:
+            raise RuntimeError(f"Failed to load index '{name}': {e}") from e
+
+    async def unload_index(self, name: str) -> None:
+        """Unload an index from memory."""
+        try:
+            await asyncio.to_thread(self._manager.unload_index, name)
+        except RuntimeError as e:
+            raise RuntimeError(f"Failed to unload index '{name}': {e}") from e
+
+    async def query(
+        self,
+        name: str,
+        query: str,
+        options: Optional[QueryOptions] = None,
+    ) -> SearchResult:
+        """
+        Perform a semantic similarity search.
+
+        If the index is loaded locally (via load_index), queries run in-memory.
+        Otherwise, falls back to the cloud query API.
+
+        Args:
+            options: Query options (top_k, alpha, embedding, filter). Example filter:
+                QueryOptions(filter={"$and": [
+                    {"field": "city", "condition": {"$eq": "NYC"}},
+                    {"field": "price", "condition": {"$lt": "50"}},
+                ]})
+        """
+        is_loaded = await asyncio.to_thread(self._manager.has_index, name)
+
+        if is_loaded:
+            return await self._query_local(name, query, options)
+
+        if getattr(options, "filter", None) is not None:
+            logger.warning(
+                "Metadata filter ignored: filtering is only supported for locally loaded indexes. "
+                "Call load_index('%s') first.",
+                name,
+            )
+        return await self._query_cloud(name, query, options)
+
+    # -- Internal ---------------------------------------------------
+
+    async def _query_local(
+        self,
+        name: str,
+        query: str,
+        options: Optional[QueryOptions],
+    ) -> SearchResult:
+        top_k = getattr(options, "top_k", None) or 5
+        alpha = getattr(options, "alpha", None) or 0.8
+        query_embedding = getattr(options, "embedding", None)
+        filter = getattr(options, "filter", None)
+
+        if query_embedding is None:
+            try:
+                return await asyncio.to_thread(
+                    self._manager.query_text, name, query, top_k, alpha, filter,
+                )
+            except RuntimeError as e:
+                if "requires explicit query embeddings" in str(e):
+                    raise ValueError(
+                        "This index uses custom embeddings. "
+                        "Query embeddings must be provided via QueryOptions.embedding."
+                    ) from e
+                raise
+
+        return await asyncio.to_thread(
+            self._manager.query, name, query, list(query_embedding), top_k, alpha, filter,
+        )
+
+    async def _query_cloud(
+        self,
+        name: str,
+        query: str,
+        options: Optional[QueryOptions],
+    ) -> SearchResult:
+        """Fallback: query via the cloud API when the index is not loaded locally."""
+        top_k = getattr(options, "top_k", None) or 10
+        query_embedding = getattr(options, "embedding", None)
+
+        request_body: Dict[str, Any] = {
+            "query": query,
+            "indexName": name,
+            "projectId": self._project_id,
+            "projectKey": self._project_key,
+            "topK": top_k,
+        }
+        if query_embedding is not None:
+            request_body["queryEmbedding"] = list(query_embedding)
+
+        try:
+            async with httpx.AsyncClient(timeout=60.0) as client:
+                response = await client.post(
+                    _get_query_url(),
+                    headers={"Content-Type": "application/json"},
+                    json=request_body,
+                )
+                if not response.is_success:
+                    raise Exception(f"HTTP error! status: {response.status_code}")
+                data = response.json()
+        except httpx.RequestError as error:
+            raise Exception(f"Cloud query request failed: {str(error)}")
+
+        return self._dict_to_search_result(data)
+
+    @staticmethod
+    def _dict_to_search_result(data: dict) -> SearchResult:
+        docs = [
+            QueryResultDocumentInfo(
+                id=d.get("id", ""),
+                text=d.get("text", ""),
+                metadata=d.get("metadata"),
+                score=float(d.get("score", 0.0)),
+            )
+            for d in data.get("docs", [])
+        ]
+        return SearchResult(
+            docs=docs,
+            query=data.get("query", ""),
+            index_name=data.get("indexName"),
+            time_taken_ms=data.get("timeTakenMs"),
+        )
+
+    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

moss/services/__init__.py

@@ -0,0 +1 @@
+"""Internal services package."""

moss-1.0.0.dist-info/METADATA

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: moss
+Version: 1.0.0
+Summary: Python SDK for semantic search with on-device AI capabilities
+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: search,semantic,embeddings,vector,usemoss,moss
+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: Programming Language :: Python :: 3.14
+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: httpx>=0.25.0
+Requires-Dist: inferedge-moss-core==0.8.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.2.0; extra == "dev"
+Requires-Dist: tox>=4.0.0; extra == "dev"
+Requires-Dist: black>=25.9.0; extra == "dev"
+Requires-Dist: isort>=7.0.0; extra == "dev"
+Requires-Dist: flake8>=7.3.0; extra == "dev"
+Requires-Dist: mypy>=1.18.2; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
+Requires-Dist: pdoc>=15.0.4; extra == "dev"
+Requires-Dist: pydoc-markdown>=4.8.2; extra == "dev"
+Requires-Dist: griffe>=0.40.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Dynamic: license-file
+
+# Moss client library for Python
+
+`moss` enables **private, on-device semantic search** in your Python applications with cloud storage capabilities.
+
+Built for developers who want **instant, memory-efficient, privacy-first AI features** with seamless cloud integration.
+
+## ✨ Features
+
+- ⚡ **On-Device Vector Search** - Sub-millisecond retrieval with zero network latency
+- 🔍 **Semantic, Keyword & Hybrid Search** - Embedding search blended with Keyword matching
+- ☁️ **Cloud Storage Integration** - Automatic index synchronization with cloud storage
+- 📦 **Multi-Index Support** - Manage multiple isolated search spaces
+- 🛡️ **Privacy-First by Design** - Computation happens locally, only indexes sync to cloud
+- 🚀 **High-Performance Rust Core** - Built on optimized Rust bindings for maximum speed
+- 🧠 **Custom Embedding Overrides** - Provide your own document and query vectors when you need full control
+
+## 📦 Installation
+
+```bash
+pip install moss
+```
+
+## 🚀 Quick Start
+
+```python
+import asyncio
+from moss import MossClient, DocumentInfo, QueryOptions
+
+async def main():
+    # Initialize search client with project credentials
+    client = MossClient("your-project-id", "your-project-key")
+
+    # Prepare documents to index
+    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"}
+        )
+    ]
+
+    # Create an index with documents (syncs to cloud)
+    index_name = "faqs"
+    await client.create_index(index_name, documents)  # Defaults to moss-minilm
+    print("Index created and synced to cloud!")
+
+    # Load the index (from cloud or local cache)
+    await client.load_index(index_name)
+
+    # Search the index
+    result = await client.query(
+        index_name,
+        "How do I return a damaged product?",
+        QueryOptions(top_k=3, alpha=0.6),
+    )
+
+    # Display results
+    print(f"Query: {result.query}")
+    for doc in result.docs:
+        print(f"Score: {doc.score:.4f}")
+        print(f"ID: {doc.id}")
+        print(f"Text: {doc.text}")
+        print("---")
+
+asyncio.run(main())
+```
+
+## 🔥 Example Use Cases
+
+- Smart knowledge base search with cloud backup
+- Realtime Voice AI agents with persistent indexes
+- Personal note-taking search with sync across devices
+- Private in-app AI features with cloud storage
+- Local semantic search in edge devices with cloud fallback
+
+## Available Models
+
+- `moss-minilm`: Lightweight model optimized for speed and efficiency
+- `moss-mediumlm`: Balanced model offering higher accuracy with reasonable performance
+
+## 🔧 Getting Started
+
+### Prerequisites
+
+- Python 3.8 or higher
+- Valid InferEdge project credentials
+
+### Environment Setup
+
+1. **Install the package:**
+
+```bash
+pip install moss
+```
+
+2. **Get your credentials:**
+
+Sign up at [InferEdge Platform](https://platform.inferedge.dev) to get your `project_id` and `project_key`.
+
+3. **Set up environment variables (optional):**
+
+```bash
+export MOSS_PROJECT_ID="your-project-id"
+export MOSS_PROJECT_KEY="your-project-key"
+```
+
+### Basic Usage
+
+```python
+import asyncio
+from moss import MossClient, DocumentInfo, QueryOptions
+
+async def main():
+    # Initialize client
+    client = MossClient("your-project-id", "your-project-key")
+    
+    # Create and populate an index
+    documents = [
+        DocumentInfo(id="1", text="Python is a programming language"),
+        DocumentInfo(id="2", text="Machine learning with Python is popular"),
+    ]
+    
+    await client.create_index("my-docs", documents)
+    await client.load_index("my-docs")
+    
+    # Search
+    results = await client.query(
+        "my-docs",
+        "programming language",
+        QueryOptions(alpha=1.0),
+    )
+    for doc in results.docs:
+        print(f"{doc.id}: {doc.text} (score: {doc.score:.3f})")
+
+asyncio.run(main())
+```
+
+### Hybrid Search Controls
+
+`alpha` lets you decide how much weight to give semantic similarity versus keyword relevance when running `query()`:
+
+```python
+# Pure keyword search
+await client.query("my-docs", "programming language", QueryOptions(alpha=0.0))
+
+# Mixed results (default 0.8 => semantic heavy)
+await client.query("my-docs", "programming language")
+
+# Pure embedding search
+await client.query("my-docs", "programming language", QueryOptions(alpha=1.0))
+```
+
+Pick any value between 0.0 and 1.0 to tune the blend for your use case.
+
+### Metadata filtering
+
+You can pass a metadata filter directly to `query()` after loading an index locally:
+
+```python
+results = await client.query(
+    "my-docs",
+    "running shoes",
+    QueryOptions(top_k=5, alpha=0.6),
+    filter={
+        "$and": [
+            {"field": "category", "condition": {"$eq": "shoes"}},
+            {"field": "price", "condition": {"$lt": "100"}},
+        ]
+    },
+)
+```
+
+For a complete runnable example, see `python/user-facing-sdk/samples/metadata_filtering.py`.
+
+## 🧠 Providing custom embeddings
+
+Already using your own embedding model? Supply vectors directly when managing
+indexes and queries:
+
+```python
+import asyncio
+
+from moss import DocumentInfo, MossClient, QueryOptions
+
+
+def my_embedding_model(text: str) -> list[float]:
+    """Placeholder for your custom embedding generator."""
+    ...
+
+
+async def main() -> None:
+    client = MossClient("your-project-id", "your-project-key")
+
+    documents = [
+        DocumentInfo(
+            id="doc-1",
+            text="Attach a caller-provided embedding.",
+            embedding=my_embedding_model("doc-1"),
+        ),
+        DocumentInfo(
+            id="doc-2",
+            text="Fallback to the built-in model when the field is omitted.",
+            embedding=my_embedding_model("doc-2"),
+        ),
+    ]
+
+    await client.create_index("custom-embeddings", documents)  # Defaults to moss-minilm
+    await client.load_index("custom-embeddings")
+
+    results = await client.query(
+        "custom-embeddings",
+        "<query text>",
+        QueryOptions(embedding=my_embedding_model("<query text>"), top_k=10),
+    )
+
+    print(results.docs[0].id, results.docs[0].score)
+
+
+asyncio.run(main())
+```
+
+Leaving the model argument undefined defaults to `moss-minilm`.
+Pass `QueryOptions` to reuse your own embeddings or to override `top_k` on a per-query basis.
+
+## 📄 License
+
+This package is licensed under the [PolyForm Shield License 1.0.0](./LICENSE.txt).
+
+- ✅ Free for testing, evaluation, internal use, and modifications.
+- ❌ Not permitted for production or competing commercial use.
+- 📩 For commercial licenses, contact: <contact@usemoss.dev>
+
+## 📬 Contact
+
+For support, commercial licensing, or partnership inquiries, contact us: [contact@usemoss.dev](mailto:contact@usemoss.dev)

moss-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+moss/__init__.py,sha256=nDKEGYA-_subR84YyGeyWpSraqbbia6qRUVkn6I4UXw,1266
+moss/__init__.pyi,sha256=PQGokkArNzroFjpGvMKFSCQDlzNgePqu4EYtRoX2yfs,5339
+moss/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moss/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moss/client/moss_client.py,sha256=_UM9PclligFxChkZ0UreNi3e0MvyQXo50kWRL8BucdE,9829
+moss/services/__init__.py,sha256=VbNr33QCf-t2exytCmtZt0JpaZdvv_pihNvFDRROwvM,33
+moss-1.0.0.dist-info/licenses/LICENSE.txt,sha256=nHPtyobLLM12cc5izwX4NMoIzLf35_0Z9LI3dlCUhF4,5923
+moss-1.0.0.dist-info/METADATA,sha256=1OZoZxUiKnbhmTijDHjO-NgOukMRMnu8_gEkk-P8OmM,8894
+moss-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+moss-1.0.0.dist-info/top_level.txt,sha256=Ukhq5EDBYCpv9V5DNk9r4qcWGtmf4g4xt-rY1fFdbaQ,5
+moss-1.0.0.dist-info/RECORD,,

moss-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

moss-1.0.0.dist-info/licenses/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-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+moss