lithio-sdk 0.1.0

The Official Python SDK for the Lithio API

Lithio Python SDK

A Python SDK for the Lithio API, designed with an OpenAI/xAI/Anthropic-style interface.

Installation

pip install -e .

Or install from a directory:

cd /path/to/sdk
pip install .

Usage

Basic Usage

from lithio import Client

# Initialize the client
client = Client(
    api_key="your-api-key",
    base_url="https://api.example.com"
)

# Add a query
response = client.add(
    query="This is an example query",
    space="my-space",
    properties={"custom": "property"}
)
print(response.request)  # "processing"

# Search
results = client.search(
    query="search query",
    limit=10,
    match_threshold=0.5,
    rerank_alpha=0.3,
    space="my-space"
)
print(results.results)

Using Client Properties

You can set default properties on the client that will be included in all requests:

client = Client(
    api_key="your-api-key",
    base_url="https://api.example.com",
    properties={
        "environment": "production",
        "version": "1.0"
    }
)

# These properties will be automatically included
client.add(query="test query")
client.search(query="test search")

# You can override or add more properties per request
client.add(
    query="test query",
    properties={"additional": "property"}
)

Context Manager

The client can be used as a context manager to ensure proper cleanup:

with Client(api_key="your-api-key", base_url="https://api.example.com") as client:
    response = client.add(query="example")
    results = client.search(query="example")

Manual Cleanup

client = Client(api_key="your-api-key", base_url="https://api.example.com")
try:
    response = client.add(query="example")
finally:
    client.close()

API Reference

Client

Client.__init__(api_key, base_url="http://localhost:8000", properties=None, timeout=30.0)

Initialize the Lithio client.

Parameters:

• api_key (str): Your Lithio API key
• base_url (str): Base URL for the API (default: http://localhost:8000)
• properties (dict, optional): Default properties to include in all requests
• timeout (float): Request timeout in seconds (default: 30.0)

Client.add(query, space=None, properties=None) -> AddResponse

Add a query to the system.

Parameters:

• query (str): The query string to add
• space (str, optional): Optional space identifier
• properties (dict, optional): Optional properties (merged with client defaults)

Returns:

• AddResponse: Response containing the request status

Client.search(query, limit=None, match_threshold=None, rerank_alpha=None, space=None, properties=None) -> SearchResponse

Search for results.

Parameters:

• query (str): The search query string
• limit (int, optional): Maximum number of results (default: 5)
• match_threshold (float, optional): Minimum match threshold (default: 0.4)
• rerank_alpha (float, optional): Reranking alpha parameter (default: 0.2)
• space (str, optional): Optional space identifier
• properties (dict, optional): Optional properties (merged with client defaults)

Returns:

• SearchResponse: Response containing the search results

Error Handling

The SDK raises httpx.HTTPError for HTTP errors. You can handle them like this:

import httpx
from lithio import Client

client = Client(api_key="your-api-key", base_url="https://api.example.com")

try:
    response = client.add(query="example")
except httpx.HTTPStatusError as e:
    if e.response.status_code == 401:
        print("Invalid API key")
    else:
        print(f"HTTP error: {e}")
except httpx.RequestError as e:
    print(f"Request error: {e}")