similarity-search-api-sdk

Ranks a corpus of items against a query vector using a calibrated fusion score (alpha * cosine + (1-alpha) * NMI_normalizado), where alpha is auto-derived from the corpus's marginal entropy unless overridden. Results are identified by their 0-indexed position in corpus_vectors (this tool does not accept explicit item IDs). Use this when you need semantically-calibrated similarity over a stateless corpus of up to 500k items without a vector database. Do NOT use for purely geometric nearest-neighbor search where NMI overhead is unnecessary, nor for corpora larger than 500k items per call. Requires an x402 payment.

{
  "type": "object",
  "properties": {
    "query_vector": {
      "description": "Dense numeric vector representing the query item. Must have the same dimensionality as all corpus_vectors entries.",
      "items": {
        "type": "number"
      },
      "maxItems": 4096,
      "minItems": 2,
      "title": "Query Vector",
      "type": "array"
    },
    "corpus_vectors": {
      "description": "List of dense numeric vectors forming the corpus to rank against. Each inner array must match query_vector dimensionality. Maximum 500000 entries.",
      "items": {
        "items": {
          "type": "number"
        },
        "type": "array"
      },
      "maxItems": 500000,
      "minItems": 1,
      "title": "Corpus Vectors",
      "type": "array"
    },
    "top_k": {
      "default": 10,
      "description": "Number of top-ranked results to return, ordered by descending fusion score. Capped at 1000 by the core service regardless of corpus size.",
      "maximum": 1000,
      "minimum": 1,
      "title": "Top K",
      "type": "number"
    },
    "alpha_override": {
      "default": null,
      "description": "Fixed alpha weight for cosine component in [0.0, 1.0]. If omitted, alpha is auto-calibrated from corpus entropy. Set to 1.0 to use pure cosine; 0.0 for pure NMI.",
      "maximum": 1,
      "minimum": 0,
      "title": "Alpha Override",
      "type": "number"
    },
    "n_bins": {
      "default": 16,
      "description": "Number of histogram bins used to discretize continuous dimensions when estimating NMI. Must be between 3 and 50.",
      "maximum": 50,
      "minimum": 3,
      "title": "N Bins",
      "type": "number"
    }
  },
  "required": [
    "query_vector",
    "corpus_vectors"
  ],
  "title": "rank_items_by_nmi_cosine_fusionArguments"
}

Computes the aggregate entropy-calibrated alpha for a corpus without running a full search -- useful to inspect before committing to a large rank_items_by_nmi_cosine_fusion call. Returns a single aggregate corpus_entropy value, NOT a per-dimension breakdown -- the real logic only exposes the mean marginal entropy across dimensions, not H(X_d) per individual dimension. Do NOT use expecting per-dimension granularity. Requires an x402 payment.

{
  "type": "object",
  "properties": {
    "corpus_vectors": {
      "description": "List of dense numeric vectors for which to compute the aggregate entropy and calibrated alpha. Each inner array must be the same length. Maximum 500000 entries.",
      "items": {
        "items": {
          "type": "number"
        },
        "type": "array"
      },
      "maxItems": 500000,
      "minItems": 1,
      "title": "Corpus Vectors",
      "type": "array"
    },
    "n_bins": {
      "default": 16,
      "description": "Number of histogram bins for entropy discretization. Must be between 3 and 50; should match the n_bins used in rank_items_by_nmi_cosine_fusion for the profile to be consistent.",
      "maximum": 50,
      "minimum": 3,
      "title": "N Bins",
      "type": "number"
    }
  },
  "required": [
    "corpus_vectors"
  ],
  "title": "estimate_corpus_entropy_profileArguments"
}

Computes the NMI-cosine fusion score for exactly one (query, target) vector pair at a fixed alpha. Use for explainability, debugging, or unit-level validation of fusion scores before running full corpus ranking. Unlike corpus-level ranking, alpha is NOT auto-calibrated for a single pair -- the real logic requires a fixed alpha (default 0.5); pass alpha explicitly for a specific blend. Do NOT use in a loop to score many pairs; batch them into rank_items_by_nmi_cosine_fusion instead. Requires an x402 payment.

{
  "type": "object",
  "properties": {
    "vector_a": {
      "description": "First dense numeric vector of the pair. Must have the same dimensionality as vector_b.",
      "items": {
        "type": "number"
      },
      "maxItems": 4096,
      "minItems": 2,
      "title": "Vector A",
      "type": "array"
    },
    "vector_b": {
      "description": "Second dense numeric vector of the pair. Must have the same dimensionality as vector_a.",
      "items": {
        "type": "number"
      },
      "maxItems": 4096,
      "minItems": 2,
      "title": "Vector B",
      "type": "array"
    },
    "n_bins": {
      "default": 16,
      "description": "Histogram bins for NMI discretization. Must be between 3 and 50.",
      "maximum": 50,
      "minimum": 3,
      "title": "N Bins",
      "type": "number"
    },
    "alpha": {
      "default": 0.5,
      "description": "Fixed alpha weight for the cosine component in [0.0, 1.0], applied as-is -- not auto-calibrated. Default 0.5 matches the core service default.",
      "maximum": 1,
      "minimum": 0,
      "title": "Alpha",
      "type": "number"
    }
  },
  "required": [
    "vector_a",
    "vector_b"
  ],
  "title": "score_pair_nmi_cosineArguments"
}