Python SDK

API Reference

Complete method signatures and return types for all Python SDK clients.

Client

The root client. All sub-clients are accessed as attributes.

from guidedmind import Client
 
client = Client(
    api_key: str | None = None,
    base_url: str = "https://api.guidedmind.ai",
    timeout: float = 30.0,
    max_retries: int = 3,
)

client.search()

Parameter	Type	Default	Description
`query`required	`str`	—	Natural language search query.
`limit`	`int`	`5`	Maximum results to return.
`threshold`	`float`	`0.70`	Minimum relevance score (0–1).
`search_method`	`SearchMethod`	`HYBRID`	Search algorithm. See SearchMethod enum below.
`include_metadata`	`bool`	`False`	Include source metadata on each result.

Returns SearchResponse

client.asearch()

Async version of search(). Same parameters, returns Awaitable[SearchResponse].

client.close() / client.aclose()

Close the underlying HTTP connection pool. Called automatically when using the client as a context manager.

client.documents

upload()

Parameter	Type	Default	Description
`file_path`required	`str`	—	Path to the file on disk.
`metadata`	`dict \| None`	`None`	Key-value metadata attached to every chunk from this document.

Returns UploadResponse — { document_id: str, status: str }

upload_and_process()

Same parameters as upload().

Returns ProcessResponse — { document_id: str, chunks_created: int, status: str }

aupload() / aupload_and_process()

Async versions. Same parameters, return Awaitable[UploadResponse | ProcessResponse].

client.memory.short

add_record()

Parameter	Type	Default	Description
`session_id`required	`str`	—	Unique conversation session identifier.
`role`required	`str`	—	"user" or "assistant".
`content`required	`str`	—	Message text.

Returns MemoryRecord — { id: str, session_id: str, role: str, content: str, created_at: datetime }

get_records()

Parameter	Type	Default	Description
`session_id`required	`str`	—	Session to retrieve records for.

Returns RecordList — { records: list[MemoryRecord], total: int }

aadd_record() / aget_records()

Async versions. Same parameters.

client.memory.long

store_record()

Parameter	Type	Default	Description
`user_id`required	`str`	—	Unique identifier for the user.
`role`required	`str`	—	"user" or "assistant".
`content`required	`str`	—	Message text to persist.

Returns MemoryRecord

search()

Parameter	Type	Default	Description
`query`required	`str`	—	Semantic search query.
`limit`	`int`	`10`	Maximum results to return.
`threshold`	`float`	`0.70`	Minimum relevance score.

Returns SearchResponse — same shape as client.search()

astore_record() / asearch()

Async versions. Same parameters.

SearchMethod Enum

from guidedmind import SearchMethod
 
SearchMethod.DENSE   # Vector-based semantic search
SearchMethod.SPARSE  # Keyword BM25 search
SearchMethod.HYBRID  # Combined dense + sparse (recommended default)
SearchMethod.GRAPH   # Knowledge graph traversal

Exceptions

Exception	HTTP	Description
`AuthenticationError`	401, 403	Invalid or expired API key
`RateLimitError`	429	Rate limit exceeded after all retries
`NotFoundError`	404	Resource not found
`ValidationError`	422	Invalid request parameters
`APIError`	4xx / 5xx	All other API errors — check `e.status_code`
`ConfigurationError`	—	Bad client config (e.g. HTTP base URL, missing key)
`GuidedMindError`	—	Base class for all SDK exceptions

Type Definitions

# Key return types — all are Pydantic v2 models
from guidedmind.types import (
    SearchResponse,   # .results: list[SearchResult], .metadata: SearchMetadata
    SearchResult,     # .content, .score, .document_id, .chunk_index, .metadata
    SearchMetadata,   # .search_method_used, .processing_time_ms, .total_results
    UploadResponse,   # .document_id, .status
    ProcessResponse,  # .document_id, .chunks_created, .status
    MemoryRecord,     # .id, .session_id | .user_id, .role, .content, .created_at
    RecordList,       # .records: list[MemoryRecord], .total: int
)

← PreviousSecurity Next →Examples