Python SDK

RAG Search

Query your indexed documents with semantic, keyword, hybrid, or graph-based search.

client.search() is the core method of the SDK. It queries your project's document index and returns ranked results with relevance scores.

Basic Search

from guidedmind import Client
 
client = Client()
 
response = client.search(query="What are the main features?")
 
print(f"Found {len(response.results)} results")
for result in response.results:
    print(f"  {result.score:.3f}  {result.content[:120]}...")

Advanced Options

from guidedmind import Client, SearchMethod
 
response = client.search(
    query="Explain the microservices architecture",
    limit=10,
    threshold=0.75,
    search_method=SearchMethod.HYBRID,
    include_metadata=True,
)
 
print(f"Method used : {response.metadata.search_method_used}")
print(f"Processing  : {response.metadata.processing_time_ms}ms")
 
for result in response.results:
    print(f"  [{result.score:.3f}] {result.content[:80]}")
    if result.metadata:
        print(f"           source: {result.metadata.get('source')}")

Search Parameters

Parameter	Type	Default	Description
`query`required	`str`	—	Natural language search query.
`limit`	`int`	`5`	Maximum number of results to return.
`threshold`	`float`	`0.70`	Minimum relevance score (0–1). Results below this are excluded.
`search_method`	`SearchMethod`	`HYBRID`	Algorithm to use. See table below.
`include_metadata`	`bool`	`False`	When true, each result includes source metadata (file name, chunk index, custom fields).

Search Methods

Method	Description	Best For
`SearchMethod.DENSE`	Vector-based semantic similarity (cosine distance)	Conceptual questions, natural language
`SearchMethod.SPARSE`	Keyword BM25 ranking	Exact terms, product names, codes
`SearchMethod.HYBRID`	Weighted combination of dense + sparse	Most production workloads — start here
`SearchMethod.GRAPH`	Knowledge graph traversal for multi-hop reasoning	Entity relationships, complex inference

Start with SearchMethod.HYBRID. It consistently outperforms single-method search across diverse query types without any additional cost. Switch to DENSE or SPARSE only after profiling your specific query distribution.

Response Shape

response.results          # List[SearchResult]
response.metadata         # SearchMetadata
 
# SearchResult fields
result.content            # str  — the matching chunk text
result.score              # float — relevance score (0–1)
result.document_id        # str  — source document ID
result.chunk_index        # int  — position within the document
result.metadata           # dict — custom metadata (when include_metadata=True)
 
# SearchMetadata fields
response.metadata.search_method_used   # str
response.metadata.processing_time_ms  # int
response.metadata.total_results        # int  — total matching chunks before limit

Async Version

async def search_docs(query: str):
    async with Client() as client:
        response = await client.asearch(
            query=query,
            limit=10,
            search_method=SearchMethod.HYBRID,
        )
    return response.results

← PreviousBasic Usage Next →Short Memory