v0.1.10

Matrix Python SDK — v0.1.10 Release Notes

v0.1.10 is a stability + DX release focused on reliable local installs, better runner discovery, and safer defaults (especially on macOS). It’s fully backward-compatible with existing entry points.

---

Highlights

• Auto-clone from manifest
  If a Hub plan comes back with plan.artifacts: [], the installer now synthesizes git artifacts from repository/repositories declared in the manifest (embedded or discovered via provenance/lockfile). Repositories are cloned by default without requiring the Hub to list them explicitly.

• Default branch safety
  When a manifest repo omits ref, we don’t force master—we let git use the repo’s default branch. This avoids errors like “invalid ref (unsafe characters)” and works with repos that default to main or a protected branch.

• Smarter runner discovery
  A deterministic strategy pipeline now covers:

  • Embedded runner_b64 / runner_url (relative URLs resolved against provenance).
  • runner objects present in the plan.
  • Embedded manifests (v2 direct runner, v1 connector synthesis from server URL).
  • Local runner.json (with shallow search up to a small depth).
  • Connector synthesis when MCP server URLs are present (mcp_registration.server.url) or discoverable via manifest URLs.
  • GitHub URL normalization (blob → raw, refs/heads/<branch> → <branch>).

• Hardened networking (macOS-friendly)
  HTTP GETs prefer system trust via truststore and fall back to certifi, reducing corporate CA and Keychain issues on macOS. Strict timeouts and conservative headers are used.

• Cleaner, more actionable logs
  New INFO/DEBUG logs make the workflow obvious:

  • Plan summary and planner outcome (DEBUG prints the full object).
  • Artifact decisions (“plan reports 0 artifact(s)”, “synthesized N git artifact(s)”).
  • Runner-discovery strategy attempts and successes.
  • File system safety decisions (path traversal blocks, atomic writes).

• Production-grade error surfacing
  Git/HTTP fetch failures are escalated as ManifestResolutionError, giving clear, typed failures instead of silent no-ops.

---

What Changed

Added

• Automatic repository cloning from manifest declarations when plan.artifacts is empty.

• Connector runner synthesis from:

  • Embedded MCP registration.
  • Manifest fetched via provenance/lockfile URLs.

• URL normalization for common GitHub shapes in both runner and manifest fetch paths.

• Atomic runner.json writes and traversal-safe path joins.

• Shallow search for runner.json that skips noisy directories (node_modules, .venv, .git, __pycache__).

Changed

• Omit ref in git specs when not provided by the manifest → git uses the repo’s default branch.
• More conservative network behavior with allow-lists and toggles (see Env Vars below).

Fixed

• Cases where no repos were cloned because the Hub plan didn’t enumerate artifacts.
• Fetch failures not clearly propagated to callers/tests.
• Relative runner_url not resolving against provenance base URLs in some scenarios.
• Logging nits (no stray %s in formatted messages; consistent INFO/DEBUG levels).

Security / Robustness

• Manifest domain allow-list before network fetch.
• TLS hardening via truststore (preferred) and certifi fallback.
• Atomic file writes and directory traversal protection.

---

Environment Variables (advanced)

• MATRIX_SDK_DEBUG=1 — enable detailed DEBUG output (planner outcome, strategy traces).
• MATRIX_SDK_HTTP_TIMEOUT=15 — network timeout in seconds.
• MATRIX_SDK_MANIFEST_DOMAINS=raw.githubusercontent.com,github.com,codeload.github.com — allow-list for manifest fetches.
• MATRIX_SDK_ENABLE_CONNECTOR=1 — enable connector synthesis strategies (default on).
• MATRIX_SDK_RUNNER_SEARCH_DEPTH=2 — depth for shallow runner.json search.
• MATRIX_INSTALL_SEND_ABS_TARGET=0 — send server-safe target labels (default) vs absolute paths.

---

macOS Notes

• TLS trust: Uses macOS system trust when available; certifi fallback covers custom roots.
• Filesystem: Atomic writes behave correctly on APFS; shallow search avoids large node_modules.
• Developer ergonomics: Better logs + safer defaults make local installs predictable on dev machines.

---

Upgrade Notes

No API changes to LocalInstaller or the public dataclasses (BuildReport, EnvReport, BuildResult).
Most teams can upgrade without code changes. If you previously hard-coded ref: master in manifests, you may keep doing so; otherwise, allowing the default branch is now the safer default.

---

Acknowledgements

Thanks to everyone who reported issues around empty artifacts, runner discovery with relative URLs, and macOS truststore problems—this release addresses those pain points directly.

---

Enjoy v0.1.10! If you hit anything surprising, enable MATRIX_SDK_DEBUG=1 and share the logs; they now pinpoint exactly where planning, artifact materialization, or runner discovery took a different path than expected.

Release v0.1.11

matrix-python-sdk v0.1.11 — Release Notes

Highlights

• Windows stability: fixed PID probing and eliminated noisy venv symlink failures.
• Cross-platform parity: identical behavior on Windows, macOS, Linux (incl. WSL).
• No breaking changes: APIs and on-disk formats remain compatible.

Changes

Runtime

• Cross-platform PID check
  Replaced POSIX-only os.kill(pid, 0) with a portable helper:

  • Windows: OpenProcess + GetExitCodeProcess (STILL_ACTIVE=259) via ctypes.
  • POSIX: keeps os.kill(pid, 0).
    Affects:
  • runtime.status() — no crashes on Windows when listing processes.
  • runtime.doctor() — resilient “process not found” handling instead of tracebacks.

• Connector visibility in status
  runtime.status() now consistently includes connector entries (pid <= 0) so dashboards and CLIs can show remote endpoints even without a local PID.

• Logging
  Honors MATRIX_SDK_DEBUG for granular debug output without affecting default verbosity.

Installer (Python envs)

• Venv creation hardened
  Uses venv.EnvBuilder with OS-sensible defaults:

  • Windows: defaults to no symlinks (prevents permission errors).
  • macOS/Linux: defaults to symlinks.
  • If symlinked create fails, automatically retries without symlinks.

• Opt-in symlinks
  New env var: MATRIX_SYMLINKS=1 forces symlinks where supported.

• Quieter Windows installs
  Avoids repeated “Unable to symlink …” messages; installs proceed cleanly.

• Pip bootstrap
  Still upgrades pip, setuptools, wheel post-venv creation.

• Index configuration
  Honors MATRIX_SDK_PIP_INDEX_URL and MATRIX_SDK_PIP_EXTRA_INDEX_URL for private mirrors.

• Editable installs switch
  MATRIX_SDK_PIP_EDITABLE (default on) controls pip install -e . vs non-editable.

Bug Fixes

• Fixed WinError 87 crash in matrix ps/consumers of runtime.status() (Windows only).
• Eliminated spurious symlink errors during installation on Windows hosts lacking Developer Mode/admin privileges.

Compatibility

• No breaking API changes.
• On-disk runner.lock.json remains unchanged and backward compatible.
• Works with existing runner.json manifests; connector mode unchanged.

Upgrade Notes

• No action required for macOS/Linux users.
• Windows users no longer need Developer Mode/admin for routine installs.
• To re-enable symlinks on Windows (optional): set MATRIX_SYMLINKS=1.

Environment Variables (recap)

• MATRIX_SDK_DEBUG — enable SDK debug logs (1/true/on).
• MATRIX_SYMLINKS — force venv symlinks when 1 (Windows off by default).
• MATRIX_SDK_PIP_INDEX_URL, MATRIX_SDK_PIP_EXTRA_INDEX_URL — pip indexes.
• MATRIX_SDK_PIP_EDITABLE — toggle editable install (1 default).

v0.1.9

Release notes — matrix-python-sdk v0.1.9

Python SDK for Matrix Hub — catalog search, entity detail, install, and remote management for agents, tools, and MCP servers.

Highlights

• ✅ Installer refactor with 100% legacy compatibility

  • The legacy matrix_sdk.installer module has been refactored into a proper subpackage: matrix_sdk/installer/.

  • Backwards-compatible facade: from matrix_sdk.installer import LocalInstaller still works as before.

  • Clear separation of concerns:

    • installer/core.py – orchestration & public API (LocalInstaller, BuildReport, EnvReport, BuildResult)
    • installer/files.py – file writes & artifact fetching (git/http)
    • installer/runner_discovery.py – robust runner discovery strategies
    • installer/runner_schema.py – pure validation & URL helpers
    • installer/envs.py – Python/Node environment preparation
    • installer/util.py – shared helpers & logging

• 🔁 Runner discovery restored (and improved)

  • Strategy order mirrors the original installer:

    1. plan.runner_b64 → decode & write
    2. plan.runner_url → fetch & validate
    3. plan.runner (object) → validate & write
    4. Embedded manifest v2 (manifest.runner) → validate & write
    5. Embedded manifest v1 (server URL) → synthesize “connector”
    6. File (runner_file or runner.json)
    7. Shallow BFS search (depth env-configurable)
    8. Manifest URL fetch (opt-in allow-listed)
    9. Structure inference (e.g., server.py, package.json)
    10. URL hint fallback → minimal connector

  • New pure schema helpers (runner_schema.py) + best-effort normalization:

    • _is_valid_runner_schema, _ensure_sse_url, _url_from_manifest,
      _extract_mcp_sse_url, _coerce_runner_to_legacy_process

• 📦 Artifacts & files parity

  • Multi-source file scan: plan.files, results[].files, outcome.files
  • Supports content (utf-8 text) and content_b64 (binary)
  • Git artifacts (kind: git) and HTTP/archive artifacts (with sha256 and unpack) restored
  • Errors normalized to ManifestResolutionError (as before)

• 🐍 Environment preparation parity

  • Python: creates venv, upgrades pip/setuptools/wheel, installs dependencies from:

    • runner.python.requirements (supports ["-r", "requirements.txt"])
    • requirements.txt
    • pyproject.toml / setup.py (editable by default; opt-out)
    • Optional integration with a python_builder module if present

  • Node: detects package manager (pnpm > yarn > npm) and runs install

• 🔧 Operational knobs (env vars)

  • Discovery & network:

    • MATRIX_SDK_ALLOW_MANIFEST_FETCH (default 1)
    • MATRIX_SDK_MANIFEST_DOMAINS (CSV allow-list)
    • MATRIX_SDK_ENABLE_CONNECTOR (default 1)
    • MATRIX_SDK_HTTP_TIMEOUT (default 15)
    • MATRIX_SDK_RUNNER_SEARCH_DEPTH (default 2)

  • Planning & logging:

    • MATRIX_INSTALL_SEND_ABS_TARGET (default off) — send absolute path vs safe label
    • MATRIX_SDK_DEBUG — enable verbose DEBUG logs

  • Python packaging:

    • MATRIX_SDK_PIP_INDEX_URL, MATRIX_SDK_PIP_EXTRA_INDEX_URL
    • MATRIX_SDK_PIP_EDITABLE (default true)

Compatibility

• Public API matches the legacy installer exactly:

  • Dataclasses: BuildReport, EnvReport, BuildResult (same fields & types)
  • Methods & semantics: LocalInstaller.plan, materialize, prepare_env, build, _load_runner_from_report
  • Import path unchanged for callers: from matrix_sdk.installer import LocalInstaller

• Python versions: 3.11–3.12 (aligned with pyproject.toml)

Bug fixes

• Fixed missing runner.json scenarios via a resilient discovery chain.
• Prevented path traversal when writing declared files (secure join).
• More robust normalization of connector URLs to /sse.

Deprecations

• None. Legacy public surface remains intact.

Upgrading

pip install --upgrade matrix-python-sdk

No code changes are required for callers that do:

from matrix_sdk.installer import LocalInstaller

If you vendor or import internals, prefer the new stable helpers in:
matrix_sdk.installer.runner_schema and matrix_sdk.installer.util.

Thank you

Thanks to everyone testing the installer with real-world MCP servers and reporting edge cases. Your feedback directly shaped this refactor. ♥️

v0.1.8

Release Notes: Matrix SDK Installer v0.1.8

This release focuses on a major overhaul of the installer's robustness, reliability, and debuggability. The failover logic for both runner discovery and dependency installation has been significantly enhanced to handle a wider variety of project configurations automatically, ensuring a smoother and more predictable installation experience.

Key Enhancements

🚀 Greatly Improved Installation Reliability

• Guaranteed Environment Isolation: The installer now creates a fresh, fully isolated Python virtual environment for every single run (clear=True, system_site_packages=False). This prevents errors caused by corrupted states from previous failed installations and guarantees that the host system's environment is never affected.
• Intelligent Runner Discovery Failover: Fixed a critical bug where installations would fail if a runner.json was not explicitly defined. The installer now includes a final failover step:
  • If no runner is found in the manifest or a runner.json file, the installer will now detect the presence of pyproject.toml or requirements.txt.
  • Upon detection, it synthesizes a placeholder runner configuration. This allows the installation to proceed to the dependency installation phase, resolving the "runner not found" class of errors.

🧠 Smarter and More Flexible Dependency Management

The dependency installation logic has been redesigned to follow a more intelligent, multi-layered failover procedure that respects modern Python packaging standards:

1. Runner Instructions First: Strictly adheres to any dependency instructions found in the discovered runner.json (from the manifest or a file).
2. requirements.txt Fallback: If the runner provides no instructions, it automatically looks for and uses a requirements.txt file.
3. Comprehensive pyproject.toml Handling: As a final fallback, it now correctly handles projects managed with pyproject.toml:
   • Poetry Application Support: Intelligently detects "non-package mode" Poetry projects and correctly runs poetry install to manage their dependencies.
   • Standard Packages: For all other standard packages, it uses a robust editable install (pip install -e .) with an automatic retry to a non-editable install (pip install .) upon failure.

🛠️ Enhanced Debugging and Diagnostics

• Verbose Logging: The entire installation process is now instrumented with extensive debug logging.
• Easy Debug Mode: To see a full step-by-step trace of the installer's logic, simply set the environment variable MATRIX_SDK_DEBUG=1 before running your script. This makes it significantly easier to diagnose any installation issues.

v0.1.7

Matrix Python SDK v0.1.7

Date: 2025-08-31

A small but important release focused on manifest ingestion, runner materialization, and more reliable Python environment setup. If you’re installing MCP servers from manifests (v2) and want the SDK to “just work” without a hand-crafted runner.json, this one’s for you.

✨ Highlights

• v2 manifest ingestion: understands embedded runner definitions and pulls runner data from the manifest/provenance when available.
• Deterministic runner materialization: a clear, prioritized set of strategies to find, fetch, or synthesize runner.json.
• Smarter Python env setup: integrates an optional python_builder pathway with a robust pip fallback.
• New environment switches to make CI/CD repeatable and easier to debug.

---

🔧 Changes

Runner materialization (installer)

The SDK now attempts runner discovery using a predictable priority order (first match wins):

1. Embedded base-64 runner
2. Explicit runner URL
3. Runner object provided in the plan
4. Embedded v2 manifest runner (or v1 synth)
5. Known file locations
6. Shallow search
7. Synthesize from manifest_url / provenance.source_url
8. Fallback connector synthesis

This means many installs no longer require a local runner.json. If your manifest embeds a valid runner (or points to one), the SDK will use it automatically.

Python environment preparation

• Attempts python_builder first (when available), then falls back to a standard pip flow.
• Always ensures pip, setuptools, and wheel are up to date before installing.
• Honors optional indexes via environment variables (see below).

New / documented environment variables

• MATRIX_SDK_ALLOW_MANIFEST_FETCH=1
  Allow the installer to fetch and use runner details from the provided manifest URL/provenance.
• MATRIX_SDK_RUNNER_SEARCH_DEPTH=3
  Control how far the SDK will look for a runner file when doing shallow searches.
• MATRIX_SDK_PIP_INDEX_URL and MATRIX_SDK_PIP_EXTRA_INDEX_URL
  Point installs at private indexes/mirrors in CI.

Logging & UX

• Clearer log messages for each runner-discovery strategy.
• More explicit warnings when a runner cannot be found or synthesized.

---

⚠️ Notes & compatibility

• Behavioral change: the refined priority order can cause the SDK to pick a different runner source than previous versions if multiple options were available. If you rely on an older inference path, pin a runner explicitly (embedded, URL, or runner.json).
• Connector vs process/python runners: if your manifest declares a connector that points to a local SSE URL, the SDK will honor that. If you intend to launch a server, prefer a python/process runner in the manifest or ship a runner.json.

---

✅ Recommended usage

• Prefer v2 manifests with an embedded runner (or a provenance.source_url) so installs are reproducible.

• In CI, set:

  export MATRIX_SDK_ALLOW_MANIFEST_FETCH=1
  export MATRIX_SDK_RUNNER_SEARCH_DEPTH=3
  # Optional:
  export MATRIX_SDK_PIP_INDEX_URL=...
  export MATRIX_SDK_PIP_EXTRA_INDEX_URL=...

---

🐞 Fixes & reliability

• More resilient venv creation across platforms (retries without symlinks when needed).
• Better error surfaces when no dependency files are present (skips gracefully instead of failing silently).

---

🙏 Thanks

Thanks to everyone testing manifest-based installs and sharing feedback around runner discovery and env setup—this release folds many of those lessons into the default flow.

---

📦 Installing / upgrading

If published to your index:

pip install -U matrix-python-sdk==0.1.7

Or install from source in editable mode:

pip install -e .

---

🔗 Changelog

• Compare: v0.1.6...v0.1.7
• Key modules touched: matrix_sdk/installer.py (runner strategies & env setup)

---

v0.1.6

matrix-python-sdk 0.1.6 — Release Notes (2025-08-29)

Highlights

• Inline manifest installs
  New MatrixClient.install_manifest(...) lets you install from an in-memory manifest when the Hub doesn’t have a source_url.

• Connector/attach runtime (MCP/SSE)
  runtime.start() now supports connector runners (no local process) by writing a lock with pid=0, port=None, and a remote url.
  runtime.stop() becomes a no-op for connectors (just remove the lock).
  runtime.doctor() returns ok for connectors and can optionally probe the remote /sse endpoint.

• Installer quality of life

  • If no runner is produced and the manifest exposes an MCP/SSE URL, the installer can synthesize a lightweight connector runner (gated by MATRIX_SDK_ENABLE_CONNECTOR=1, default on).
  • Windows venv robustness: venv creation retries without symlinks if symlinks=True fails.
  • Keeps strict no absolute target paths sent to Hub.

• TLS trust stays robust (unchanged behavior)
  Honors system trust / REQUESTS_CA_BUNDLE / SSL_CERT_FILE.

Compatibility

• Backward-compatible with existing Python/Node process runners.
• Existing install() calls unchanged.
• matrix-cli will display URL for connector locks (pid=0), and traditional host/port for process locks.

---

API Additions

MatrixClient.install_manifest(...)

def install_manifest(
    self,
    fqid: str,
    *,
    manifest: dict,
    target: str,
    provenance: dict | None = None,
) -> Any:
    """
    POST /catalog/install with body:
    {
      "id": fqid,
      "target": target,
      "manifest": <dict>,
      "provenance": { "source_url": ... }?
    }
    """

Use when your Hub lacks a source_url but you want to drive an install with a trusted manifest you already have.

---

How to build & test locally

# from the sdk repo root
python3.11 -m venv .venv
source .venv/bin/activate
pip install -U pip build

# build artifacts
python -m build  # creates dist/matrix_python_sdk-0.1.6-*.whl and .tar.gz

# (optional) smoke test in a clean venv or another project
pip install --force-reinstall dist/matrix_python_sdk-0.1.6-py3-none-any.whl
python -c "import matrix_sdk, inspect; print('OK', getattr(matrix_sdk, '__version__', 'unknown'))"

If you’re testing alongside matrix-cli, in the CLI project do:

# (inside matrix-cli venv)
pip install --force-reinstall /path/to/sdk/dist/matrix_python_sdk-0.1.6-py3-none-any.whl
matrix version   # should show matrix-python-sdk: 0.1.6

---

Changelog (since 0.1.5)

• Added MatrixClient.install_manifest(...) to allow inline-manifest installs.

• Runtime

  • Added LockInfo.url: Optional[str].
  • start(): if runner.type == "connector" with a url, write lock with pid=0, port=None, url=<runner.url>; no process spawned.
  • stop(): if pid <= 0, just remove lock.
  • doctor(): for connectors, report ok with a friendly message (and optionally short probe).

• Installer

  • Connector synthesis when no runner produced and manifest exposes MCP/SSE url (guarded by MATRIX_SDK_ENABLE_CONNECTOR=1, default on).
  • Windows venv: retry venv creation with symlinks=False when needed.
  • Continues to avoid sending absolute paths to Hub in install plans.

• Misc

  • Small robustness fixes and logging polish; no breaking API removals.

v0.1.5

v0.1.5 — Fix: safer install planning & HuggingFace-style paths

Release date: 2025-08-25
Type: Patch (robustness & DX)

✨ Summary

This release fixes a server-side 500 seen during installs when a client’s absolute local path was sent to the Hub. We now send only a relative label (<alias>/<version>), keep using your local cache under ~/.matrix/runners/..., and add small quality-of-life improvements: a writeability preflight, a Windows/non-Windows venv path fix, and a HuggingFace-style MATRIX_HOME knob with safe path sanitization.

---

✅ What changed

Installer hardening

• Do not leak local paths: plan() now sends a relative label (<alias>/<version>) to the Hub instead of a client absolute path.
  Prevents server attempts to access /home/... and eliminates “Permission denied” 500s.
• New helper: _plan_target_for_server(...).
• Fail fast: _ensure_local_writable(...) runs in build() to clearly error if the local target isn’t writable.
• Venv path fix: _python_bin() now correctly resolves venv_path / "bin/python" on non-Windows (and Scripts/python.exe on Windows).
• Local layout unchanged: installs still live at ~/.matrix/runners/<alias>/<version>.
• Escape hatch (advanced): set MATRIX_INSTALL_SEND_ABS_TARGET=true to restore the old (unsafe) behavior if you absolutely need it.

Path policy (HuggingFace-style app home)

• Default target remains: ~/.matrix/runners/<alias>/<version>.
• Relocation supported: MATRIX_HOME=/path/to/dir moves the entire tree (e.g., to a larger disk, CI workspace, or container volume).
• Portable & safe: path segments (alias/version) are sanitized to be cross-platform friendly.

---

🔄 Backwards compatibility

• No breaking API changes.
• Existing installs under ~/.matrix/runners continue to work.
• Server behavior improves without requiring any user action.

---

🧩 Configuration tips

Relocate cache (HuggingFace style):

export MATRIX_HOME="/data/matrix"
# installs → /data/matrix/runners/<alias>/<version>

(Discouraged) revert to legacy absolute-path planning:

export MATRIX_INSTALL_SEND_ABS_TARGET=true

---

⬆️ Upgrade

pip install -U matrix-python-sdk

---

📝 Notes

This patch focuses on robustness and developer ergonomics during frequent test cycles. Thanks to everyone who reported install 500s and helped validate the fix.

v0.1.4

matrix-python-sdk v0.1.4 — Hotfix: Cross‑platform TLS trust (default OS store)

Release date: 2025‑08‑25
Type: Hotfix (security/robustness)

Summary

This release resolves SSL: CERTIFICATE_VERIFY_FAILED errors observed in certain virtualenv/WSL/CI setups by making OS trust the default across Windows, macOS, and Linux. The SDK now installs truststore>=0.8 by default and integrates a minimal, production‑safe TLS hardening step on client initialization.

What changed

• Default to OS trust store using https://pypi.org/project/truststore/ on all platforms.

• New helper: matrix_sdk.ssl_compat.configure_ssl_trust() is invoked once at MatrixClient.__init__, before any network I/O.

• Respect user overrides: if SSL_CERT_FILE or REQUESTS_CA_BUNDLE are set, the SDK does nothing and defers to your configuration.

• Runtime control via env:

  • MATRIX_SSL_TRUST=auto (default)
  • MATRIX_SSL_TRUST=truststore (force OS store)
  • MATRIX_SSL_TRUST=system (Unix/mac fallback to known CA bundle files)
  • MATRIX_SSL_TRUST=off (disable adjustments)
  • Debug: MATRIX_SSL_TRUST_DEBUG=1

• Packaging: truststore>=0.8 is now a hard dependency (installed automatically from PyPI). No other runtime deps changed.

• CI/Testing: Added network‑free tests (tests/test_ssl_compat.py) and a tox.ini matrix to validate behavior with different TLS modes.

Why this matters

Some environments used certifi's bundled CA file, which may lack intermediates or corporate roots. Root/system Python often works because it uses the OS store. This hotfix standardizes behavior so virtualenvs and CI match system reliability—without disabling TLS verification.

Backwards compatibility

• No API breaks.
• User‑provided CA settings are preserved; the SDK will not override SSL_CERT_FILE / REQUESTS_CA_BUNDLE.
• You can opt out at runtime with MATRIX_SSL_TRUST=off.

Upgrading

pip install -U matrix-python-sdk

Nothing else required. If you previously installed the optional extra matrix-python-sdk[truststore], you can now remove the extra—the dependency is first‑class.

Configuration examples

# Default (auto): OS trust via truststore
export MATRIX_SSL_TRUST=auto

# Force OS trust explicitly
export MATRIX_SSL_TRUST=truststore

# Force system bundle path on Unix/macOS (if you prefer files over OS store)
export MATRIX_SSL_TRUST=system

# Disable adjustments entirely (use your own CA settings)
export MATRIX_SSL_TRUST=off

# Respect explicit CA bundle (SDK will not override this)
export REQUESTS_CA_BUNDLE=/path/to/corp-root-bundle.pem

Notes for enterprise/proxy environments

If your network performs TLS inspection (MITM), ensure the proxy’s root CA is present in the OS trust store or pointed to via REQUESTS_CA_BUNDLE/SSL_CERT_FILE. The SDK keeps verification enabled and will not bypass certificate checks.

Acknowledgements

Thanks to users who reported venv/WSL TLS issues and helped validate fixes.

---

Hashes/Artifacts: No binary changes in this release aside from packaging metadata.

Python compatibility: >=3.11,<3.13 unchanged.

v0.1.3

Release Notes — v0.1.3

Date: 2025-08-24
Focus: Move default Hub endpoint from local dev to production

---

✨ What changed

We’ve switched the default Hub base URL from a local development address to the public, production API:

• Old: http://127.0.0.1:7300
• New (default): https://api.matrixhub.io

This affects examples, docs, and any helper defaults that previously assumed a local Hub. There are no API surface changes in the SDK itself—only the default endpoint changed.

---

🧩 Why this matters

• One-line getting started: New users can install and search the catalog without running a local Hub first.
• Consistent environment: The default points to a stable, globally available service.
• No breaking APIs: All client method signatures are unchanged.

---

🔄 Backwards compatibility

If you rely on a local Matrix Hub for development or testing, explicitly point the SDK to your local endpoint.

Option A — Code (recommended for tests/dev scripts):

from matrix_sdk import MatrixClient
client = MatrixClient(base_url="http://127.0.0.1:7300")

Option B — Environment variable (used by your own glue/CLIs):

export MATRIX_HUB_BASE="http://127.0.0.1:7300"

If you already pass base_url in your code, nothing changes for you.

---

✅ What to expect

• Default behavior: New samples and helper defaults use https://api.matrixhub.io.
• TLS/CA trust: Ensure your environment can reach *.matrixhub.io over HTTPS with a standard trust store.
• No data migration: This release does not introduce schema or file layout changes.

---

🔍 Quick verification

from matrix_sdk import MatrixClient

# Uses the new production endpoint (if you pass it explicitly)
hub = MatrixClient(base_url="https://api.matrixhub.io")

res = hub.search(q="hello world", type="any", limit=3)
print([it.get("id") for it in res.get("items", [])])

To verify against local dev:

hub = MatrixClient(base_url="http://127.0.0.1:7300")

---

🧪 Impacted docs & examples

• Updated all getting-started snippets to use the production endpoint.
• Notes added to usage docs about overriding via code or MATRIX_HUB_BASE.

---

🧯 Known considerations

• Corporate proxies / strict egress: allowlist api.matrixhub.io.
• Mixed environments: be explicit in CI and local scripts to avoid accidental cross-environment tests.

---

Thanks for building with Matrix! If you run into any hiccups with the new default, please open an issue with your environment details (OS, Python version, network constraints).

v0.1.2

Release date: 2025-08-17
Package: matrix-python-sdk
Tagline: A focused release that makes search first-class, improves developer ergonomics, and keeps production guardrails tight.

Highlights

• New search helpers (matrix_sdk.search): thin, defensive wrappers over /catalog/search with:

  • filter normalization (lists/sets → CSV), limit clamping
  • tiny retries with jittered exponential backoff
  • smart mode fallbacks (semantic → hybrid → keyword) to avoid empty results in dev
  • optional typed responses (SearchResponse) via SearchOptions(as_model=True)

• Client parity: MatrixClient.search now supports with_rag and rerank (none | llm) in addition to existing parameters.

• CLI (optional): a minimal matrix_sdk.cli.search command for quick, scriptable searches (table or --json).

No breaking changes; Bulk remains fully supported.

---

Added

• matrix_sdk.search module:

  • search(client, q, ...)
  • SearchOptions(allow_fallback, fallback_order, max_attempts, backoff_base, as_model)
  • search_try_modes(client, q, modes=...) (diagnostics/benchmarks)

• MatrixClient.search parameters:

  • with_rag: bool | str | None (request short “fit reasons” if the hub supports it)
  • rerank: str | None = "none" (server-side reranking policy)

---

Improved

• Resilience: transient 5xx/network failures in search helpers auto-retry with jittered backoff.
• Ergonomics: consistent parameter normalization (e.g., iterable filters → CSV), strict limit clamping (1..100).
• Error handling: MatrixError surfaces both status and status_code if present.
• Code quality: reduced complexity in search helper internals without changing behavior.

---

Docs

• Updated Usage, API Reference, and Index for 0.1.2:

  • clear search examples (client + helper)
  • explicit with_rag and rerank usage
  • reinforced installer/runtime quickstarts

• Added CLI examples and pytest snippets for search behavior.

---

Compatibility

• Python: 3.11+
• Breaking changes: none
• Deprecated APIs: none removed in this release. (Bulk remains supported.)

---

Upgrade

pip install -U matrix-python-sdk

---

Quick snippets

Search (helper; robust & typed)

from matrix_sdk.client import MatrixClient
from matrix_sdk.search import search, SearchOptions

hub = MatrixClient("http://127.0.0.1:7300")

res = search(
    hub, "summarize pdfs",
    type="any",
    with_snippets=True,
    options=SearchOptions(as_model=True, max_attempts=3),
)
print(res.total, [it.id for it in res.items])

Search (client)

from matrix_sdk.client import MatrixClient

hub = MatrixClient("http://127.0.0.1:7300")
res = hub.search(
    q="extract pdf tables",
    type="any",
    mode="hybrid",
    limit=5,
    with_snippets=True,
    with_rag=False,
    rerank="none",
)
print([it["id"] for it in res.get("items", [])])

CLI (optional)

python -m matrix_sdk.cli.search run "Hello World" --type mcp_server --mode keyword --limit 5 --json

---

Thank you

Huge thanks to everyone trying the SDK and sharing feedback. If you run into anything, please open an issue or PR — we’re building this for reliability at scale, together.