Skip to content

v0.1.4

Choose a tag to compare

View all tags
@ruslanmv ruslanmv released this 17 Aug 22:43
· 77 commits to master since this release
v0.1.4
2ca6590

Matrix Hub v0.1.4 — First Public Release 🎉

Release date: 2025-08-18
Production API: https://api.matrixhub.io/

This is the first public GitHub release of Matrix Hub — a production-ready catalog & installer for AI agents, tools, and MCP servers. It includes a stable Top-5 Meta Search API, safe installer workflows, and clean docs you can put behind your site/CDN.

Highlights

  • Top-5 Search (public contract): GET /catalog/search returns the best five matches across agents/tools/MCP servers.
  • One-click friendly results: every hit includes manifest_url and install_url (additive fields).
  • Snippets on demand: with_snippets=true returns a short preview from summary/description.
  • Prod-safe: backward compatible, no DB migrations; SQLite works for dev, Postgres recommended for prod.

What’s New

APIs

  • GET /catalog/search

    • New param: with_snippets (bool, default false).
    • type=any searches across all types.
    • Public default Top-5 (limit=5); response remains backward compatible.
    • Items include manifest_url, install_url, snippet (all optional/additive).

  • (Optional) GET /catalog/manifest/{entity_id}
    Redirects to the entity’s external manifest (source_url) when available.

Configuration

  • PUBLIC_BASE_URL — used to build absolute links in API responses.

    • Default: http://127.0.0.1:7300
    • Production: PUBLIC_BASE_URL=https://api.matrixhub.io

Code Changes (additive only)

  • src/config.py — added PUBLIC_BASE_URL.
  • src/schemas.py — SearchItem extended with manifest_url, install_url, snippet.
  • src/services/search/util.py — serialize_hit(...) enriched; supports with_snippets.
  • src/routes/catalog.py — Top-5 defaults; type=any; wires with_snippets; optional manifest redirect.

Docs & DX

  • New: docs/api/search-api.md — public Top-5 Search contract.
  • README: “Official Search API (Top-5)” quickstart added.
  • MkDocs nav: API → Top-5 Search API.
  • Tests: tests/test_search_top5.py guards the public contract (example run: 13 passed).

Compatibility & Deployment

  • Breaking changes: none (all fields/params are additive).

  • Database migrations: none.

  • Production recommendation: Postgres with pg_trgm for strong keyword ranking; enable pgvector later for semantic.

  • Key env:

    • PUBLIC_BASE_URL=https://api.matrixhub.io
    • (Optional) SEARCH_LEXICAL_BACKEND=pgtrgm
    • (Optional) SEARCH_VECTOR_BACKEND=pgvector

Quickstart (Search & Install)

# Top-5 search (public)
curl -s 'https://api.matrixhub.io/catalog/search?q=extract%20pdf%20tables&type=any&limit=5&with_snippets=true' | jq
# Install a selected item (canonical flow)
curl -s -X POST 'https://api.matrixhub.io/catalog/install' \
  -H 'Content-Type: application/json' \
  -d '{"id":"tool:pdf_table_extractor@1.1.0","target":"./"}' | jq

Known Limitations (v0.1.4)

  • Semantic-only returns no results unless embeddings + a vector backend (e.g., pgvector) are enabled.
  • Hyphenated tokens (e.g., Hello-World) may match less robustly on SQLite; Postgres pg_trgm improves fuzziness.
  • ETag caching may not appear unless enabled in your stack; consider short CDN caching on /catalog/search.

Changelog

  • Add PUBLIC_BASE_URL setting.
  • Add manifest_url, install_url, snippet to SearchItem.
  • Add with_snippets param; support type=any; default Top-5 on /catalog/search.
  • Add optional GET /catalog/manifest/{entity_id} redirect.
  • Add docs/api/search-api.md and README “Official Search API.”
  • Add tests/test_search_top5.py.
  • Polish: backward compatible; zero DB changes.

— Ready for api.matrixhub.io 🚀

Assets 2
Loading