Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Search stored items by semantic similarity and return ranked results with scores and relevance labels.
  • Text query — pass a string; query is embedded via Ollama; search text namespaces
  • Vector query — pass a numeric array; search vector namespaces (length must match each namespace’s vector_dimension)
Search errors return "status": "error" (not "failure") with HTTP 400. Non-2xx responses raise MoorchehApiError.

​
Method

client.search(payload: dict) -> dict

​
API

POST /search — see Search

​
Payload

​
query
string | array
required
Text string or array of numbers. Text queries are embedded with Ollama. Vector queries must be non-empty and match namespace dimension.
​
namespaces
array
required
Non-empty list of namespace names to search. Each namespace must exist and match the query type (text vs vector).
​
top_k
number
default:"10"
Maximum number of results to return. Clamped to 1–100. Default is 10 if omitted.
​
threshold
number
default:"0"
Minimum score threshold (0–1). Used when kiosk_mode is true.
​
metadata
object
Optional metadata filter. Only items whose metadata matches all key/value pairs exactly are considered.
​
kiosk_mode
boolean
default:"false"
When true, threshold is required and results below the threshold are filtered out.

​
Example — text search

from moorcheh import MoorchehApiClient, MoorchehApiError

client = MoorchehApiClient("http://localhost:8080")

response = client.search({
    "query": "on prem retrieval",
    "namespaces": ["my-documents"],
    "top_k": 5,
    "metadata": {"team": "ai"},
})

for hit in response["results"]:
    print(hit["id"], hit["score"], hit["label"], hit.get("text"))

response = client.search({
    "query": [0.1, 0.2, 0.3, 0.4, 0.5],  # length must match vector namespaces
    "namespaces": ["my-embeddings"],
    "top_k": 5,
})

for hit in response["results"]:
    print(hit["id"], hit["score"], hit["label"], hit["metadata"])

​
Example — kiosk mode

response = client.search({
    "query": "on prem retrieval",
    "namespaces": ["my-documents"],
    "top_k": 10,
    "kiosk_mode": True,
    "threshold": 0.4,
})

​
Returns

​
results
array
Ranked search hits, highest score first. Empty array when nothing matches (including strict metadata filters).
​
results[].id
string
Item id in the namespace.
​
results[].score
number
Similarity score between 0 and 1, rounded to 6 decimal places.
​
results[].label
string
Human-readable relevance label derived from the score (see table below).
​
results[].metadata
object
Metadata stored with the item.
​
results[].text
string
Document text for text namespace hits. Empty string "" for vector namespace hits.
​
execution_time
number
Total request time in seconds.
​
timings
object
Detailed timing breakdown for each search phase, in seconds.
​
status
string
"error" on validation or search failures (HTTP 400). Present in MoorchehApiError.body, not in successful responses.
​
message
string
Error description when the request fails.
Example return value (text search)
{
  "results": [
    {
      "id": "doc-1",
      "score": 0.566222,
      "label": "High Relevance",
      "metadata": {"team": "ai"},
      "text": "Get items test document",
    },
  ],
  "execution_time": 0.108234,
  "timings": {
    "parse_validate": 0.0,
    "prepare_vector": 0.107252,
    "fetch_data": 0.0,
    "calculate_distance": 0.000336,
    "select_candidates": 0.0,
    "calculate_scores": 0.000072,
    "reorder": 0.0,
    "format_response": 0.0,
    "total": 0.108234,
  },
}
Example return value (vector search)
{
  "results": [
    {
      "id": "vec-1",
      "score": 1.0,
      "label": "Close Match",
      "metadata": {"source": "demo"},
      "text": "",
    },
  ],
  "execution_time": 0.000015,
  "timings": {
    "parse_validate": 0.0,
    "prepare_vector": 0.0,
    "fetch_data": 0.0,
    "calculate_distance": 0.0,
    "select_candidates": 0.0,
    "calculate_scores": 0.0,
    "reorder": 0.0,
    "format_response": 0.0,
    "total": 0.000015,
  },
}

​
Relevance labels

Score rangeLabel
≥ 0.894Close Match
≥ 0.632Very High Relevance
≥ 0.447High Relevance
≥ 0.316Good Relevance
≥ 0.224Low Relevance
≥ 0.1Very Low Relevance
< 0.1Irrelevant

​
Errors

Non-2xx responses raise MoorchehApiError. Search validation errors use HTTP 400 with "status": "error" in the body. 
from moorcheh import MoorchehApiError

try:
    response = client.search({"query": "test", "namespaces": ["my-documents"]})
except MoorchehApiError as e:
    print(e.status_code, e.body)  # e.body may include status: "error"
StatusCause
400Empty query or namespaces, namespace not found, query type mismatch, vector dimension mismatch, invalid top_k, or kiosk_mode without threshold
  • Text search requires Ollama running for embeddings
  • You cannot search text namespaces with a vector query or vice versa
  • metadata filter uses exact key/value matching — typos or extra keys in stored metadata will exclude items
  • With kiosk_mode: True, set threshold (0–1) to control minimum relevance