Python SDK

The official Laghav Python SDK. Wraps the REST API with typed responses, error classes, streaming helpers, and async support.

Installation

bash

pip install laghav
# With all integrations (LangChain, LlamaIndex, CLI)
pip install laghav[all]
# Specific extras
pip install laghav[langchain]
pip install laghav[llama-index]
pip install laghav[cli]

LaghavClient

client.py

from laghav import LaghavClient
 
# Initialize
client = LaghavClient(
    api_key="lgh_live_xxx",        # or set LAGHAV_API_KEY env var
    base_url="https://api.laghav.ai",  # default
    timeout=30,                     # seconds
    max_retries=2,                  # auto-retry on 5xx
)
 
# Synchronous call
response = client.complete(
    messages=[{"role": "user", "content": "..."}],
    model="auto",
    max_tokens=1000,
    stream=False,
    laghav_options={"compress": True, "route": True, "cache": True, "score": True}
)
 
# Async call
import asyncio
async def main():
    response = await client.acomplete(
        messages=[{"role": "user", "content": "..."}],
        model="auto"
    )
asyncio.run(main())

Response object

Field	Type	Description
response.id	str	Unique request ID (lgh_req_xxx)
response.choices[0].message.content	str	LLM response text
response.model	str	Actual model used
response.laghav_meta	LaghavMeta	Savings metadata object
response.laghav_meta.quality_score	int	0–100 quality score
response.laghav_meta.saved_usd	float	USD saved on this call
response.laghav_meta.compression_ratio	float	Fraction of tokens removed
response.laghav_meta.cache_hit	bool	True if served from cache
response.laghav_meta.rules_applied	List[str]	Compression rules used

Streaming

stream.py

# Iterator-based streaming
for chunk in client.complete(messages=[...], model="auto", stream=True):
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)
 
# Context manager (auto-close)
with client.stream(messages=[...], model="auto") as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    meta = stream.get_final_message().laghav_meta

Usage & savings helpers

usage.py

# Get today's usage
usage = client.usage.today()
print("Calls:", usage.total_calls, "Saved:", usage.saved_usd)
 
# Monthly summary
monthly = client.usage.monthly(month="2025-06")
print("Monthly savings:", monthly.saved_usd)
 
# Model distribution
dist = client.models.distribution(period="today")
for model in dist.models:
    print(model.name, model.pct, "% (", model.calls, "calls)" )

Agent Cost Control TypeScript SDK