lightrag-client

Python SDK for the InfraX RAGservicer — hybrid knowledge-base (vector + graph + keyword) retrieval over REST.

Install

pip install lightrag-client

Quick Start

from lightrag_client import LightRAGClient

rs = LightRAGClient(base_url="http://localhost:9721", api_key="lr_xxx", tenant_id="market")

# Insert documents (async by default → returns {task_id, status, doc_id})
rs.insert("market", "BTC 走势受美联储利率政策影响", "doc-1")
rs.insert_batch("market", [
    {"text": "DeFi TVL 回升", "doc_id": "doc-2"},
    {"text": "链上巨鲸增持", "doc_id": "doc-3"},
])
# ⚠️ 写入为异步：后台完成「抽实体建图 + 向量化」后才可检索到。
# 写入后建议轮询 GET /api/v1/namespaces/<ns>/tasks/<task_id> 至 index_status=indexed
# （任务 status=success 仅代表写入完成，不代表索引完成；index_status=error 表示索引失败需重放）
# （端到端样例见 examples/lightrag_store_and_query.py）

# Query (context retrieval, no LLM answer)
result = rs.query("market", "比特币走势")
print(result["context"])
print(result["sources"])      # [{"id": "doc-1", "name": "doc-1", "score": 0.82}, ...]
print(result["topScore"])     # 0.82（可用于置信度路由；无分数时为 None）
print(result["scoreSource"])  # "embedding" | "unavailable"

# Context-only retrieval with top_k（with_scores=False 可省掉补算分数的 embedding 调用）
ctx = rs.retrieve("market", "利率", top_k=5)
fast = rs.retrieve("market", "利率", top_k=5, with_scores=False)

# Documents
rs.list_documents("market", page=1, limit=20)
print(rs.get_document("market", "doc-1"))   # {doc_id, status, chunks, updated_at, error, ...}
rs.delete("market", "doc-1")

Admin

# Tenants & API keys
rs.create_tenant("market", "Market Data", "default tenant")  # 幂等：已存在返回 created=False
rs.get_tenant("market")        # 租户详情 + namespaces/documents/indexed/failed 计数
rs.generate_api_key("market", "prod", expires_days=90)
rs.list_api_keys("market")

# Hot-reload LLM / Embedding config (no restart needed)
rs.update_config(llm={"api_key": "sk-new", "model": "deepseek-chat"})

All methods talk the standard InfraX envelope {code, message, data} and return the data payload on success; API failures raise LightRAGClientError with .status / .code / .message.

Requirements

• Python >= 3.9
• requests

License

MIT