Add Python SDK source and restructure bindings

[HarshaNalluru]

Description

Open-sources the moss Python SDK — private, on-device semantic search with cloud storage, hybrid search, and custom embedding support.

• sdk/ — Full Python SDK source. Buildable, testable, open for contributions.
• bindings/ — Rust/PyO3 bindings source for reference and debugging. Pre-built wheels on PyPI.

sdks/python/
├── sdk/          # moss (pure Python)
├── bindings/     # moss-core (Rust/PyO3)
└── README.md

What's included

• Async MossClient — create indexes, load, query, manage documents
• Semantic, keyword, and hybrid search (alpha blending)
• Metadata filtering ($eq, $gt, $in, $and/$or, geospatial $near)
• Bring your own embeddings (BYOE)
• Cloud fallback when index isn't loaded locally
• CI workflow (lint, type-check, tests across Python 3.10–3.14)

Quick start

import asyncio
from moss import MossClient, DocumentInfo, QueryOptions

async def main():
    client = MossClient("your-project-id", "your-project-key")

    docs = [
        DocumentInfo(id="1", text="Refunds are processed within 3-5 business days."),
        DocumentInfo(id="2", text="You can track your order on the dashboard."),
    ]

    await client.create_index("support-docs", docs)
    await client.load_index("support-docs")

    results = await client.query("support-docs", "how long do refunds take?", QueryOptions(top_k=3))

    for doc in results.docs:
        print(f"[{doc.score:.3f}] {doc.text}")

asyncio.run(main())

Test plan

• cd sdks/python/sdk && pip install -e ".[dev]" succeeds
• pytest tests/ -m "not e2e" passes
• from moss import MossClient works after install

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
moss_vitepress	Ready	Preview, Comment	Mar 25, 2026 11:12pm
moss-samples	Ready	Preview, Comment	Mar 25, 2026 11:12pm

[Copilot]

Pull request overview

This PR open-sources and restructures the Moss Python SDK by splitting the repository into a pure-Python moss package (sdks/python/sdk/) that depends on prebuilt inferedge-moss-core wheels, while keeping the Rust/PyO3 bindings source under sdks/python/bindings/ for reference/debugging. It also adds extensive unit + cloud/E2E tests for the new Python client and wires the SDK into CI.

Changes:

• Added the pure-Python moss SDK package (async MossClient, typing support, packaging, docs, changelog).
• Moved/trimmed Rust binding sources into sdks/python/bindings/ and removed old Rust binding crate scaffolding under sdks/python/src/.
• Added SDK test suite + pytest cloud-test skipping logic, and a CI job to lint/type-check/test the SDK.

Reviewed changes

Copilot reviewed 34 out of 39 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
sdks/python/src/utils.rs	Removed old Rust utils bindings (serialization helpers).
sdks/python/src/lib.rs	Removed old Rust moss_core module initializer (superseded by bindings/).
sdks/python/src/index.rs	Removed old Rust Index PyO3 bindings (no longer shipped here).
sdks/python/sdk/tests/test_search.py	Added multi-dataset benchmark-style test runner (cloud).
sdks/python/sdk/tests/test_metadata_filter_e2e.py	Added E2E tests for metadata filtering operators and $near.
sdks/python/sdk/tests/test_hot_reload.py	Added E2E tests for load_index hot reload / auto-refresh behavior.
sdks/python/sdk/tests/test_e2e.py	Added large-scale E2E coverage for create/add/delete/list/get job status.
sdks/python/sdk/tests/test_create_index_versions.py	Added create_index benchmark test across doc counts.
sdks/python/sdk/tests/test_cloud_fallback.py	Added E2E tests for cloud fallback querying when index isn’t loaded.
sdks/python/sdk/tests/test_client.py	Added unit tests for MossClient behavior (local vs cloud paths, defaults, filters).
sdks/python/sdk/tests/constants.py	Added shared test constants + helpers (creds, model id, docs).
sdks/python/sdk/tests/conftest.py	Added .env loading + auto-skip for cloud/E2E tests without real creds.
sdks/python/sdk/tests/init.py	Declared test package.
sdks/python/sdk/src/moss/services/init.py	Added internal services package marker.
sdks/python/sdk/src/moss/py.typed	Added PEP 561 typing marker.
sdks/python/sdk/src/moss/client/moss_client.py	Implemented async MossClient (ManageClient/IndexManager calls + cloud query fallback).
sdks/python/sdk/src/moss/init.pyi	Added public type stubs for SDK surface.
sdks/python/sdk/src/moss/init.py	Added public exports, version, and core type re-exports.
sdks/python/sdk/pyproject.toml	Added packaging metadata and dev tooling deps/config.
sdks/python/sdk/README.md	Added SDK documentation and usage examples.
sdks/python/sdk/LICENSE	Added BSD 2-Clause license for the Python SDK source.
sdks/python/sdk/CHANGELOG.md	Added changelog history for beta releases.
sdks/python/bindings/src/models.rs	Trimmed exposed binding models (removed some classes from registration).
sdks/python/bindings/src/manage/types.rs	Removed CredentialsInfo binding and related registration.
sdks/python/bindings/src/manage/mod.rs	Added manage module wiring/re-exports.
sdks/python/bindings/src/manage/client.rs	Updated manage client imports after type removals.
sdks/python/bindings/src/lib.rs	Added new moss_core module initializer for bindings layout.
sdks/python/bindings/src/indexmanager.rs	Removed refresh/get_index_info binding methods.
sdks/python/bindings/pyproject.toml	Updated bindings packaging metadata (version, python requirement, license classifiers).
sdks/python/bindings/README.md	Added bindings-layer README and contribution guidance.
sdks/python/bindings/Cargo.toml	Updated bindings crate metadata and added placeholder private moss crate path.
sdks/python/README.md	Rewrote Python SDK top-level README to describe new sdk/ + bindings/ layout.
sdks/python/Cargo.lock	Removed old Rust lockfile tied to removed crate layout.
packages/vitepress-plugin-moss/demo-site/documentation/docs/reference/python/README.md	Updated contact email to contact@moss.dev.
packages/vitepress-plugin-moss/demo-site/documentation/docs/index.md	Updated contact email to contact@moss.dev.
README.md	Added pointer to full Python SDK source under sdks/python/.
CONTRIBUTING.md	Added Python SDK development instructions (install + test).
.gitignore	Ignored *.egg-info.
.github/workflows/ci.yml	Added Python SDK CI job (ruff, mypy, pytest) across Python 3.10–3.13.

Comments suppressed due to low confidence (3)

sdks/python/bindings/Cargo.toml:7

• The bindings’ Python metadata declares a proprietary license (pyproject.toml classifier), but Cargo.toml still declares license = "BSD-2-Clause". Align these to avoid shipping conflicting license information (or add an explicit comment explaining why they differ).
  sdks/python/bindings/pyproject.toml:34
• The comment above module-name = "moss_core" says the import should be import moss, but the module name is moss_core. Update the comment to match the actual Python import to avoid confusion.
  sdks/python/bindings/pyproject.toml:18
• requires-python = ">=3.10" conflicts with the classifiers advertising Python 3.8 and 3.9 support. Adjust the classifiers (or requires-python) so package metadata is consistent for users and tooling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.