{"id":36964387,"url":"https://github.com/ivkond/lightrag-api","last_synced_at":"2026-01-13T19:31:40.949Z","repository":{"id":327965426,"uuid":"1113758082","full_name":"ivkond/lightrag-api","owner":"ivkond","description":"Simple LightRAG API client for Python.","archived":false,"fork":false,"pushed_at":"2026-01-13T14:54:33.000Z","size":171,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T17:16:39.758Z","etag":null,"topics":["api-client","lightrag","rag"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivkond.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T12:26:46.000Z","updated_at":"2026-01-13T14:54:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ivkond/lightrag-api","commit_stats":null,"previous_names":["ivkond/lightrag-api"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ivkond/lightrag-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivkond%2Flightrag-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivkond%2Flightrag-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivkond%2Flightrag-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivkond%2Flightrag-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivkond","download_url":"https://codeload.github.com/ivkond/lightrag-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivkond%2Flightrag-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28397826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","lightrag","rag"],"created_at":"2026-01-13T19:31:40.163Z","updated_at":"2026-01-13T19:31:40.943Z","avatar_url":"https://github.com/ivkond.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 lightrag-api\n\nSimple LightRAG API client for Python.\n\nThis library provides both synchronous and asynchronous clients for interacting with the LightRAG API, enabling document management, RAG queries, knowledge graph operations, and more.\n\n## 📦 Installation\n\nInstall from source using `uv` or `pip`:\n\n```bash\n# Using uv\nuv add lightrag-api\n\n# Using pip\npip install lightrag-api\n```\n\n**Requirements:**\n- 🐍 Python \u003e= 3.10\n- 📡 httpx \u003e= 0.28.1\n- ✅ pydantic \u003e= 2.12.5\n\n## ⚡ Quick Start\n\n### Synchronous Client\n\n```python\nfrom lightrag.api import SyncLightRagClient\n\n# Initialize client with API key\nclient = SyncLightRagClient(\n    base_url=\"https://your-lightrag-server.com\",\n    api_key=\"your-api-key\"\n)\n\n# Execute a query\nresponse = client.query(\"What is machine learning?\")\nprint(response.response)\n\n# Don't forget to close the client\nclient.close()\n```\n\n### Asynchronous Client\n\n```python\nfrom lightrag.api import AsyncLightRagClient\n\nasync def main():\n    # Initialize client with OAuth token\n    client = AsyncLightRagClient(\n        base_url=\"https://your-lightrag-server.com\",\n        oauth_token=\"your-oauth-token\"\n    )\n    \n    try:\n        # Execute a query\n        response = await client.query(\"What is machine learning?\")\n        print(response.response)\n    finally:\n        await client.close()\n\n# Run the async function\nimport asyncio\nasyncio.run(main())\n```\n\n## ✨ Features\n\n- 📄 **Document Management**: Upload documents, insert text, delete documents, and manage document pipelines\n- 🔍 **RAG Queries**: Execute queries with multiple modes (local, global, hybrid, naive, mix, bypass), streaming support, and conversation history\n- 🕸️ **Knowledge Graph Operations**: Create, update, merge, and delete entities and relations\n- ⚙️ **Pipeline Management**: Monitor and control document processing pipelines\n- 🔄 **Dual Client Support**: Both synchronous (`SyncLightRagClient`) and asynchronous (`AsyncLightRagClient`) clients\n- 🛡️ **Type Safety**: Full Pydantic model support for request/response validation\n\n## 💡 Usage Examples\n\n### 🔧 Initialize Client\n\n```python\nfrom lightrag.api import SyncLightRagClient, AsyncLightRagClient\n\n# Sync client with API key\nsync_client = SyncLightRagClient(\n    base_url=\"https://api.example.com\",\n    api_key=\"your-api-key\"\n)\n\n# Async client with OAuth token\nasync_client = AsyncLightRagClient(\n    base_url=\"https://api.example.com\",\n    oauth_token=\"your-oauth-token\"\n)\n```\n\n### ❓ Simple Query\n\n```python\n# Synchronous query\nresponse = sync_client.query(\n    query=\"Explain quantum computing\",\n    mode=\"mix\",\n    include_references=True\n)\nprint(response.response)\nprint(response.references)\n\n# Asynchronous query\nresponse = await async_client.query(\n    query=\"Explain quantum computing\",\n    mode=\"mix\",\n    include_references=True\n)\n```\n\n### 📤 Upload Document\n\n```python\n# Upload a file\nresponse = sync_client.upload_document(\"path/to/document.pdf\")\nprint(f\"Document ID: {response.doc_id}\")\n\n# Or upload from bytes\nwith open(\"document.pdf\", \"rb\") as f:\n    response = sync_client.upload_document(f.read())\n```\n\n### 📝 Insert Text\n\n```python\n# Insert single text\nresponse = sync_client.insert_text(\n    text=\"Your document content here...\",\n    file_source=\"manual_input.txt\"\n)\n\n# Insert multiple texts\nresponse = sync_client.insert_texts(\n    texts=[\"Text 1\", \"Text 2\", \"Text 3\"],\n    file_sources=[\"doc1.txt\", \"doc2.txt\", \"doc3.txt\"]\n)\n```\n\n## 📚 API Overview\n\n### 📄 Document Management\n\n- `upload_document(file)` - Upload a document file\n- `insert_text(text, file_source)` - Insert text into the system\n- `insert_texts(texts, file_sources)` - Insert multiple texts\n- `get_documents()` - Get statuses of all documents\n- `get_documents_paginated(page, page_size)` - Get paginated document list\n- `delete_document(doc_ids, delete_file, delete_llm_cache)` - Delete documents by ID\n- `clear_documents()` - Clear all documents\n- `get_pipeline_status()` - Get document processing pipeline status\n- `cancel_pipeline()` - Cancel current processing pipeline\n- `reprocess_failed()` - Reprocess failed documents\n- `get_status_counts()` - Get document status counts\n- `get_track_status(track_id)` - Track document processing status\n- `scan_documents()` - Scan for new documents\n\n### 🔍 Query Methods\n\n- `query(query, mode, include_references, ...)` - Execute RAG query\n- `query_stream(query, mode, ...)` - Execute streaming RAG query\n- `query_data(query, mode, ...)` - Execute query and return structured data\n\n### 🕸️ Knowledge Graph Operations\n\n- `create_entity(name, description, labels)` - Create a new entity\n- `update_entity(name, description, labels)` - Update an existing entity\n- `delete_entity(entity_name)` - Delete an entity\n- `merge_entities(source_name, target_name)` - Merge two entities\n- `create_relation(source, target, relation, description)` - Create a relation\n- `update_relation(source, target, relation, description)` - Update a relation\n- `delete_relation(source, target, relation)` - Delete a relation\n- `get_knowledge_graph(limit)` - Get knowledge graph data\n- `get_graph_labels()` - Get all graph labels\n- `get_popular_labels(limit)` - Get popular labels\n- `search_labels(q, limit)` - Search labels\n- `check_entity_exists(name)` - Check if entity exists\n\n### 🛠️ Utility Methods\n\n- `clear_cache()` - Clear LLM response cache\n- `get_version()` - Get API version\n- `get_tags()` - Get available tags\n- `get_running_models()` - Get running models\n- `get_health()` - Check API health status\n- `get_auth_status()` - Get authentication status\n- `login(username, password)` - Login and get token\n- `generate(**kwargs)` - Generate text\n- `chat(**kwargs)` - Chat with the API\n\nFor detailed method signatures and parameters, refer to the source code documentation in `src/lightrag/api/_sync_client.py` and `src/lightrag/api/_async_client.py`.\n\n## 🔐 Authentication\n\nThe client supports two authentication methods:\n\n### 🔑 API Key Authentication\n\n```python\nclient = SyncLightRagClient(\n    base_url=\"https://api.example.com\",\n    api_key=\"your-api-key\"\n)\n```\n\nThe API key is sent in the `X-API-Key` header.\n\n### 🎫 OAuth Token Authentication\n\n```python\nclient = SyncLightRagClient(\n    base_url=\"https://api.example.com\",\n    oauth_token=\"your-oauth-token\"\n)\n```\n\nThe OAuth token is sent in the `Authorization: Bearer` header.\n\n**Note:** ⚠️ If both are provided, OAuth token takes priority.\n\n## ⚠️ Error Handling\n\nThe library provides two exception types:\n\n- `LightRagError` - Base exception for all LightRAG API errors\n- `LightRagHttpError` - Exception for HTTP-related errors\n\n```python\nfrom lightrag.api import SyncLightRagClient, LightRagError, LightRagHttpError\n\nclient = SyncLightRagClient(base_url=\"https://api.example.com\", api_key=\"key\")\n\ntry:\n    response = client.query(\"test query\")\nexcept LightRagHttpError as e:\n    print(f\"HTTP error occurred: {e}\")\nexcept LightRagError as e:\n    print(f\"LightRAG error occurred: {e}\")\n```\n\n## 🔗 Links\n\n- 📖 [LightRAG Documentation](https://github.com/HKUDS/LightRAG) - Official LightRAG project documentation\n\n## ❓ FAQ\n\n\u003e Why do you write code manually? There is an `openapi-python-client` generator.\n\n`openapi-python-client` generates slop client code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivkond%2Flightrag-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivkond%2Flightrag-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivkond%2Flightrag-api/lists"}