Skip to content

v0.1.2

Choose a tag to compare

View all tags
@ruslanmv ruslanmv released this 17 Aug 12:16
· 36 commits to master since this release
v0.1.2
2205422

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.

Assets 4
Loading