OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
"""OpenRAG SDK documents client."""
import asyncio
from pathlib import Path
from typing import TYPE_CHECKING, BinaryIO
from .exceptions import NotFoundError
from .models import (
DeleteDocumentResponse,
FileRecord,
GetAllFilesResponse,
IngestResponse,
IngestTaskStatus,
ListFilesResponse,
)
if TYPE_CHECKING:
from .client import OpenRAGClient
class DocumentsClient:
"""Client for document operations."""
def __init__(self, client: "OpenRAGClient"):
self._client = client
async def ingest(
self,
file_path: str | Path | None = None,
*,
file: BinaryIO | None = None,
filename: str | None = None,
wait: bool = True,
poll_interval: float = 1.0,
timeout: float = 300.0,
) -> IngestResponse | IngestTaskStatus:
"""
Ingest a document into the knowledge base.
Args:
file_path: Path to the file to ingest.
file: File-like object to ingest (alternative to file_path).
filename: Filename to use when providing file object.
wait: If True, poll until ingestion completes. If False, return immediately.
poll_interval: Seconds between status checks when waiting.
timeout: Maximum seconds to wait for completion.
Returns:
IngestTaskStatus with final status if wait=True.
IngestResponse with task_id if wait=False.
Raises:
ValueError: If neither file_path nor file is provided.
TimeoutError: If ingestion doesn't complete within timeout.
"""
if file_path is not None:
path = Path(file_path)
with open(path, "rb") as f:
files = {"file": (path.name, f)}
response = await self._client._request(
"POST",
"/api/v1/documents/ingest",
files=files,
)
elif file is not None:
if filename is None:
raise ValueError("filename is required when providing file object")
files = {"file": (filename, file)}
response = await self._client._request(
"POST",
"/api/v1/documents/ingest",
files=files,
)
else:
raise ValueError("Either file_path or file must be provided")
data = response.json()
ingest_response = IngestResponse(**data)
if not wait:
return ingest_response
# Poll for completion
return await self.wait_for_task(
ingest_response.task_id,
poll_interval=poll_interval,
timeout=timeout,
)
async def get_task_status(self, task_id: str) -> IngestTaskStatus:
"""
Get the status of an ingestion task.
Args:
task_id: The task ID returned from ingest().
Returns:
IngestTaskStatus with current task status.
"""
response = await self._client._request(
"GET",
f"/api/v1/tasks/{task_id}",
)
data = response.json()
return IngestTaskStatus(**data)
async def wait_for_task(
self,
task_id: str,
poll_interval: float = 1.0,
timeout: float = 300.0,
) -> IngestTaskStatus:
"""
Wait for an ingestion task to complete.
Args:
task_id: The task ID to wait for.
poll_interval: Seconds between status checks.
timeout: Maximum seconds to wait.
Returns:
IngestTaskStatus with final status.
Raises:
TimeoutError: If task doesn't complete within timeout.
"""
elapsed = 0.0
while elapsed < timeout:
status = await self.get_task_status(task_id)
if status.status in ("completed", "failed"):
return status
await asyncio.sleep(poll_interval)
elapsed += poll_interval
raise TimeoutError(
f"Ingestion task {task_id} did not complete within {timeout}s"
)
async def delete(
self,
filename: str | None = None,
*,
filter_id: str | None = None,
) -> DeleteDocumentResponse:
"""
Delete document(s) from the knowledge base.
Provide exactly one of:
filename: delete all chunks for that filename.
filter_id: delete chunks for each filename in the filter's data_sources.
Returns:
DeleteDocumentResponse with deleted chunk count.
"""
if bool(filename) == bool(filter_id):
raise ValueError("Provide exactly one of `filename` or `filter_id`")
body: dict[str, str] = {}
if filename is not None:
body["filename"] = filename
if filter_id is not None:
body["filter_id"] = filter_id
try:
response = await self._client._request(
"DELETE",
"/api/v1/documents",
json=body,
)
except NotFoundError as e:
# Keep delete idempotent for SDK callers: a missing document is not
# an exception.
# Filter-not-found 404s still raise because the filter_id is caller input.
if filename is not None and getattr(e, "status_code", None) == 404:
return DeleteDocumentResponse(
success=False,
deleted_chunks=0,
filename=filename,
message=None,
error=getattr(e, "message", "Resource not found"),
)
raise
data = response.json()
return DeleteDocumentResponse(**data)
async def list_files(
self,
*,
page: int = 1,
page_size: int = 25,
sort_by: str = "filename",
sort_order: str = "asc",
connector_type: str | None = None,
mimetype: str | None = None,
owner: str | None = None,
search: str | None = None,
after_key: str | None = None,
created_after: str | None = None,
created_before: str | None = None,
) -> ListFilesResponse:
"""
List ingested files with cursor-based composite-aggregation pagination (v2).
Args:
page: Page number (display only; use after_key for cursor navigation).
page_size: Number of files per page (1–500, default 25).
sort_by: Field to sort by. One of: filename, file_size, mimetype,
indexed_time, connector_type, chunk_count, owner.
sort_order: "asc" or "desc".
connector_type: Filter to files from a specific connector type.
mimetype: Filter to files with a specific MIME type.
owner: Filter to files owned by a specific user ID.
search: Substring/prefix match against filename.
after_key: JSON-encoded composite cursor from a previous response's
after_key field. Pass to fetch the next page.
created_after: ISO 8601 timestamp; return only files indexed on or
after this instant (e.g. "2024-01-01" or "2024-01-01T00:00:00Z").
created_before: ISO 8601 timestamp; return only files indexed on or
before this instant.
Returns:
ListFilesResponse with files list, approximate total, and next
after_key cursor.
"""
params: dict[str, str | int] = {
"page": page,
"page_size": page_size,
"sort_by": sort_by,
"sort_order": sort_order,
}
if connector_type is not None:
params["connector_type"] = connector_type
if mimetype is not None:
params["mimetype"] = mimetype
if owner is not None:
params["owner"] = owner
if search is not None:
params["search"] = search
if after_key is not None:
params["after_key"] = after_key
if created_after is not None:
params["created_after"] = created_after
if created_before is not None:
params["created_before"] = created_before
response = await self._client._request(
"GET",
"/api/v2/files",
params=params,
)
data = response.json()
return ListFilesResponse(
files=[FileRecord(**f) for f in data.get("files", [])],
total=data.get("total", 0),
is_approximate=data.get("is_approximate", True),
page=data.get("page", page),
page_size=data.get("page_size", page_size),
after_key=data.get("after_key"),
)
async def get_all_files(self) -> GetAllFilesResponse:
"""
Return all ingested files (v1).
No parameters — just returns everything in the knowledge base.
Note:
Returns at most 500 files. If your knowledge base contains more
than 500 files, use ``list_files()`` with cursor pagination
(``after_key``) to page through the full set.
Returns:
GetAllFilesResponse with files list, total count, page, and page_size.
"""
response = await self._client._request(
"GET",
"/api/v1/files/get_all",
)
data = response.json()
return GetAllFilesResponse(
files=[FileRecord(**f) for f in data.get("files", [])],
total=data.get("total", 0),
page=data.get("page", 1),
page_size=data.get("page_size", 500),
)