lyzr-rag-client

Typed sync/async Python client for the Lyzr RAG /v1 API. Use it from PepGenX (Okta bearer + API key + tenant headers, or key-only) and from Lyzr-hosted deployments (x-api-key). Built on httpx and pydantic.

Install

pip install lyzr-rag-client
# or
uv add lyzr-rag-client

Requires Python 3.10+. Runtime dependencies: httpx and pydantic only.

PepGenX quick start

Composite posture: Okta client-credentials token plus the five house-style headers.

import os

from lyzr_rag_client import ClientCredentials, ModelSpec, RagClient, SourceInput, VectorStoreSpec

tokens = ClientCredentials(
    issuer=os.environ["LYZR_OAUTH_ISSUER"],
    client_id=os.environ["LYZR_OAUTH_CLIENT_ID"],
    client_secret=os.environ["LYZR_OAUTH_CLIENT_SECRET"],
    scope=os.environ.get("LYZR_OAUTH_SCOPE"),
)

client = RagClient.for_pepgenx(
    os.environ["LYZR_RAG_BASE_URL"],  # APIM base + RAG route from onboarding
    api_key=os.environ["PEPGENX_API_KEY"],
    team_id=os.environ["PEPGENX_TEAM_ID"],
    project_id=os.environ["PEPGENX_PROJECT_ID"],
    user_id=os.environ["PEPGENX_USER_ID"],
    token_provider=tokens,
)

me = client.auth.whoami()
print(me.subject, me.org_id, me.roles)

kb = client.knowledge_bases.create(
    "demo",
    vector_store=VectorStoreSpec(provider="qdrant", credential_id="qdrant-prod"),
    # Or: VectorStoreSpec(provider="astra", credential_id="astra-prod")
    embedding=ModelSpec(model="text-embedding-3-small"),
)

job = client.documents.ingest(
    kb.id,
    [SourceInput(kind="text", text="PepsiCo Q3 margin notes…", title="notes")],
)
client.jobs.wait(job.id)

hits = client.query.retrieve(kb.id, "What changed in Q3?")
answer = client.query.answer(kb.id, "What changed in Q3?")
print(answer.answer, len(hits.results))

Key-only (no Okta)

When the deployment runs without bearer auth, omit token and tenant headers:

client = RagClient.for_pepgenx(
    os.environ["LYZR_RAG_BASE_URL"],
    api_key=os.environ["PEPGENX_API_KEY"],
    team_id=None,
    project_id=None,
)

Only x-pepgenx-apikey is sent. See docs/AUTH.md and docs/PEPGENX.md.

Lyzr-hosted quick start

import os

from lyzr_rag_client import RagClient

client = RagClient.for_lyzr(
    base_url=os.environ["LYZR_RAG_BASE_URL"],
    api_key=os.environ["LYZR_API_KEY"],
)

base_url is always explicit or taken from LYZR_RAG_BASE_URL. There is deliberately no built-in default hostname.

Environment variables

When constructing RagClient(base_url=None, auth=None), auth auto-resolves in this order: PEPGENX_* → LYZR_API_KEY → LYZR_RAG_TOKEN.

Async

from lyzr_rag_client import AsyncRagClient

async with AsyncRagClient.for_lyzr(base_url=..., api_key=...) as client:
    me = await client.auth.whoami()

AsyncRagClient mirrors RagClient; call await client.aclose() if you are not using the context manager.

Streaming answers

from lyzr_rag_client import CitationsEvent, DeltaEvent, DoneEvent, ErrorEvent

for event in client.query.stream(kb_id, "Summarize the margin notes"):
    match event:
        case CitationsEvent(citations=cites):
            ...
        case DeltaEvent(text=chunk):
            print(chunk, end="", flush=True)
        case DoneEvent(answer=final):
            print("\n", final)
        case ErrorEvent(code=code, detail=detail):
            raise RuntimeError(f"{code}: {detail}")

Jobs and uploads

• documents.ingest(...) and documents.upload(...) return 202 + a JobOut.
• An Idempotency-Key is generated automatically (pass idempotency_key= to reuse one).
• Poll with client.jobs.wait(job.id) (default 1 s interval, 600 s timeout).
• Multipart upload: client.documents.upload(kb.id, files=["./report.pdf"]).

Retries and timeouts

Defaults: 60 s total timeout, 5 s connect; 3 attempts with exponential backoff 1 s → 30 s (jitter); Retry-After is honoured when present.

Which requests retry (idempotent methods, bodies with an Idempotency-Key, transport connect failures, 429/503, and 502-504 on idempotent calls) is documented in docs/ERRORS.md.

Error handling

from lyzr_rag_client import NotFoundError

try:
    client.knowledge_bases.get(kb_id)
except NotFoundError as e:
    print(e.code, e.request_id, e.detail)

See docs/ERRORS.md for the full hierarchy and .code vocabulary.

Transaction ids

Pass transaction_id= on any resource call. The SDK sends it as the transaction_id header; the service echoes the correlation id in X-Request-Id (available as APIError.request_id).

Security

• Auth credentials are wrapped in Secret; minted/imported API-key material is redacted in model/RequestSpec repr/str. Neither appears in logs.
• TLS verification is on by default (verify=True).
• Corporate CA: RagClient(..., verify="/path/to/ca.pem").
• HTTP proxies follow httpx trust_env (standard HTTP_PROXY / HTTPS_PROXY / NO_PROXY).

Compatibility

SDK 0.1.x targets Lyzr RAG API v1 as frozen in spec/SOURCE (OpenAPI pin: spec/openapi.json).

Development

License

MIT. See LICENSE.