openrag-sdk 0.3.1__tar.gz → 0.7.0.dev1__tar.gz

{openrag_sdk-0.3.1 → openrag_sdk-0.7.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrag-sdk
-Version: 0.3.1
+Version: 0.7.0.dev1
 Summary: Official Python SDK for OpenRAG API
 Author: OpenRAG Team
 License-Expression: MIT
@@ -24,6 +24,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: idna>=3.15
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -102,7 +103,8 @@ async for event in await client.chat.create(message="Explain RAG", stream=True):
         print(event.delta, end="", flush=True)
     elif event.type == "sources":
         for source in event.sources:
-            print(f"\nSource: {source.filename}")
+            page_info = f" (page {source.page})" if source.page else ""
+            print(f"\nSource: {source.filename}{page_info}")
     elif event.type == "done":
         chat_id = event.chat_id
 ```
@@ -200,6 +202,64 @@ result = await client.documents.delete("report.pdf")
 print(f"Success: {result.success}")
 ```
 
+## Listing Files
+
+`client.documents.list_files()` inventories everything in the knowledge base and
+returns the metadata needed to drive knowledge filters and search.
+
+```python
+import json
+
+# List the first page of files
+page = await client.documents.list_files(page_size=50)
+for f in page.files:
+    print(f"{f.filename}  ({f.mimetype}, {f.chunk_count} chunks)")
+
+# Cursor-paginate through all files
+after_key = None
+while True:
+    page = await client.documents.list_files(page_size=100, after_key=after_key)
+    for f in page.files:
+        print(f.filename)
+    if page.after_key is None:
+        break
+    after_key = json.dumps(page.after_key)
+
+# Filter and sort
+page = await client.documents.list_files(
+    connector_type="sharepoint",
+    sort_by="indexed_time",
+    sort_order="desc",
+)
+
+# List → create knowledge filter workflow
+page = await client.documents.list_files(connector_type="sharepoint")
+filenames = [f.filename for f in page.files]
+result = await client.knowledge_filters.create({
+    "name": "SharePoint docs",
+    "queryData": {"filters": {"data_sources": filenames}},
+})
+filter_id = result.id
+
+# Use the filter in search and chat
+results = await client.search.query("quarterly report", filter_id=filter_id)
+response = await client.chat.create(message="Summarise Q3", filter_id=filter_id)
+```
+
+For a one-shot listing without managing a cursor, `client.documents.get_all_files()`
+returns all files in a single call — no parameters needed.
+
+> **Note:** `get_all_files()` 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.
+
+```python
+# Get all files in a single call (no cursor to track)
+page = await client.documents.get_all_files()
+for f in page.files:
+    print(f.filename)
+```
+
 ## Settings
 
 ```python

{openrag_sdk-0.3.1 → openrag_sdk-0.7.0.dev1}/README.md

@@ -72,7 +72,8 @@ async for event in await client.chat.create(message="Explain RAG", stream=True):
         print(event.delta, end="", flush=True)
     elif event.type == "sources":
         for source in event.sources:
-            print(f"\nSource: {source.filename}")
+            page_info = f" (page {source.page})" if source.page else ""
+            print(f"\nSource: {source.filename}{page_info}")
     elif event.type == "done":
         chat_id = event.chat_id
 ```
@@ -170,6 +171,64 @@ result = await client.documents.delete("report.pdf")
 print(f"Success: {result.success}")
 ```
 
+## Listing Files
+
+`client.documents.list_files()` inventories everything in the knowledge base and
+returns the metadata needed to drive knowledge filters and search.
+
+```python
+import json
+
+# List the first page of files
+page = await client.documents.list_files(page_size=50)
+for f in page.files:
+    print(f"{f.filename}  ({f.mimetype}, {f.chunk_count} chunks)")
+
+# Cursor-paginate through all files
+after_key = None
+while True:
+    page = await client.documents.list_files(page_size=100, after_key=after_key)
+    for f in page.files:
+        print(f.filename)
+    if page.after_key is None:
+        break
+    after_key = json.dumps(page.after_key)
+
+# Filter and sort
+page = await client.documents.list_files(
+    connector_type="sharepoint",
+    sort_by="indexed_time",
+    sort_order="desc",
+)
+
+# List → create knowledge filter workflow
+page = await client.documents.list_files(connector_type="sharepoint")
+filenames = [f.filename for f in page.files]
+result = await client.knowledge_filters.create({
+    "name": "SharePoint docs",
+    "queryData": {"filters": {"data_sources": filenames}},
+})
+filter_id = result.id
+
+# Use the filter in search and chat
+results = await client.search.query("quarterly report", filter_id=filter_id)
+response = await client.chat.create(message="Summarise Q3", filter_id=filter_id)
+```
+
+For a one-shot listing without managing a cursor, `client.documents.get_all_files()`
+returns all files in a single call — no parameters needed.
+
+> **Note:** `get_all_files()` 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.
+
+```python
+# Get all files in a single call (no cursor to track)
+page = await client.documents.get_all_files()
+for f in page.files:
+    print(f.filename)
+```
+
 ## Settings
 
 ```python

{openrag_sdk-0.3.1 → openrag_sdk-0.7.0.dev1}/openrag_sdk/__init__.py

@@ -49,13 +49,17 @@ from .models import (
     DeleteDocumentResponse,
     DeleteKnowledgeFilterResponse,
     DoneEvent,
+    FileRecord,
+    GetAllFilesResponse,
     GetKnowledgeFilterResponse,
     IngestResponse,
     KnowledgeFilter,
     KnowledgeFilterQueryData,
     KnowledgeFilterSearchResponse,
     KnowledgeSettings,
+    ListFilesResponse,
     Message,
+    PrincipalLabel,
     SearchFilters,
     SearchResponse,
     SearchResult,
@@ -68,7 +72,7 @@ from .models import (
     UpdateKnowledgeFilterOptions,
 )
 
-__version__ = "0.2.2"
+__version__ = "0.7.0"
 
 __all__ = [
     # Main client
@@ -82,6 +86,11 @@ __all__ = [
     "NotFoundError",
     "ValidationError",
     "ServerError",
+    # File models
+    "FileRecord",
+    "GetAllFilesResponse",
+    "ListFilesResponse",
+    "PrincipalLabel",
     # Models
     "ChatResponse",
     "ContentEvent",

{openrag_sdk-0.3.1 → openrag_sdk-0.7.0.dev1}/openrag_sdk/documents.py

@@ -5,7 +5,14 @@ from pathlib import Path
 from typing import TYPE_CHECKING, BinaryIO
 
 from .exceptions import NotFoundError
-from .models import DeleteDocumentResponse, IngestResponse, IngestTaskStatus
+from .models import (
+    DeleteDocumentResponse,
+    FileRecord,
+    GetAllFilesResponse,
+    IngestResponse,
+    IngestTaskStatus,
+    ListFilesResponse,
+)
 
 if TYPE_CHECKING:
     from .client import OpenRAGClient
@@ -125,27 +132,46 @@ class DocumentsClient:
             await asyncio.sleep(poll_interval)
             elapsed += poll_interval
 
-        raise TimeoutError(f"Ingestion task {task_id} did not complete within {timeout}s")
+        raise TimeoutError(
+            f"Ingestion task {task_id} did not complete within {timeout}s"
+        )
 
-    async def delete(self, filename: str) -> DeleteDocumentResponse:
+    async def delete(
+        self,
+        filename: str | None = None,
+        *,
+        filter_id: str | None = None,
+    ) -> DeleteDocumentResponse:
         """
-        Delete a document from the knowledge base.
+        Delete document(s) from the knowledge base.
 
-        Args:
-            filename: Name of the file to delete.
+        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={"filename": filename},
+                json=body,
             )
         except NotFoundError as e:
-            # Keep delete idempotent for SDK callers: a missing document is not an exception.
-            if getattr(e, "status_code", None) == 404:
+            # 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,
@@ -157,3 +183,94 @@ class DocumentsClient:
 
         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,
+    ) -> 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.
+
+        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
+
+        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),
+        )

{openrag_sdk-0.3.1 → openrag_sdk-0.7.0.dev1}/openrag_sdk/models.py

@@ -1,7 +1,6 @@
 """OpenRAG SDK data models."""
 
-from datetime import datetime
-from typing import Any, Literal
+from typing import Literal
 
 from pydantic import BaseModel, Field
 
@@ -98,6 +97,10 @@ class DeleteDocumentResponse(BaseModel):
     filename: str | None = None
     message: str | None = None
     error: str | None = None
+    # Populated when deleting by filter_id — one entry per resolved data_source.
+    filenames: list[str] | None = None
+    filter_id: str | None = None
+    per_file: list[dict] | None = None
 
 
 # Chat history models
@@ -281,3 +284,55 @@ class DeleteKnowledgeFilterResponse(BaseModel):
 
     success: bool
     error: str | None = None
+
+
+class PrincipalLabel(BaseModel):
+    """A principal label entry in a file's ACL (connector-ingested files only)."""
+
+    principal: str
+    kind: str
+    provider: str
+    display_name: str = ""
+    email: str = ""
+    external_id: str = ""
+
+
+class FileRecord(BaseModel):
+    """A single ingested file record returned by the list-files endpoint."""
+
+    filename: str
+    document_id: str
+    mimetype: str
+    file_size: int
+    source_url: str
+    owner: str
+    owner_name: str
+    owner_email: str
+    connector_type: str
+    embedding_model: str
+    embedding_dimensions: int | None = None
+    indexed_time: str
+    chunk_count: int
+    allowed_users: list[str] = Field(default_factory=list)
+    allowed_groups: list[str] = Field(default_factory=list)
+    allowed_principal_labels: list[PrincipalLabel] = Field(default_factory=list)
+
+
+class GetAllFilesResponse(BaseModel):
+    """Response from GET /v1/files/get_all — offset pagination, no cursor."""
+
+    files: list[FileRecord]
+    total: int
+    page: int
+    page_size: int
+
+
+class ListFilesResponse(BaseModel):
+    """Response from GET /v2/files — cursor-based composite-aggregation pagination."""
+
+    files: list[FileRecord]
+    total: int
+    is_approximate: bool
+    page: int
+    page_size: int
+    after_key: dict | None = None

{openrag_sdk-0.3.1 → openrag_sdk-0.7.0.dev1}/openrag_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrag-sdk
-Version: 0.3.1
+Version: 0.7.0.dev1
 Summary: Official Python SDK for OpenRAG API
 Author: OpenRAG Team
 License-Expression: MIT
@@ -24,6 +24,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: idna>=3.15
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -102,7 +103,8 @@ async for event in await client.chat.create(message="Explain RAG", stream=True):
         print(event.delta, end="", flush=True)
     elif event.type == "sources":
         for source in event.sources:
-            print(f"\nSource: {source.filename}")
+            page_info = f" (page {source.page})" if source.page else ""
+            print(f"\nSource: {source.filename}{page_info}")
     elif event.type == "done":
         chat_id = event.chat_id
 ```
@@ -200,6 +202,64 @@ result = await client.documents.delete("report.pdf")
 print(f"Success: {result.success}")
 ```
 
+## Listing Files
+
+`client.documents.list_files()` inventories everything in the knowledge base and
+returns the metadata needed to drive knowledge filters and search.
+
+```python
+import json
+
+# List the first page of files
+page = await client.documents.list_files(page_size=50)
+for f in page.files:
+    print(f"{f.filename}  ({f.mimetype}, {f.chunk_count} chunks)")
+
+# Cursor-paginate through all files
+after_key = None
+while True:
+    page = await client.documents.list_files(page_size=100, after_key=after_key)
+    for f in page.files:
+        print(f.filename)
+    if page.after_key is None:
+        break
+    after_key = json.dumps(page.after_key)
+
+# Filter and sort
+page = await client.documents.list_files(
+    connector_type="sharepoint",
+    sort_by="indexed_time",
+    sort_order="desc",
+)
+
+# List → create knowledge filter workflow
+page = await client.documents.list_files(connector_type="sharepoint")
+filenames = [f.filename for f in page.files]
+result = await client.knowledge_filters.create({
+    "name": "SharePoint docs",
+    "queryData": {"filters": {"data_sources": filenames}},
+})
+filter_id = result.id
+
+# Use the filter in search and chat
+results = await client.search.query("quarterly report", filter_id=filter_id)
+response = await client.chat.create(message="Summarise Q3", filter_id=filter_id)
+```
+
+For a one-shot listing without managing a cursor, `client.documents.get_all_files()`
+returns all files in a single call — no parameters needed.
+
+> **Note:** `get_all_files()` 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.
+
+```python
+# Get all files in a single call (no cursor to track)
+page = await client.documents.get_all_files()
+for f in page.files:
+    print(f.filename)
+```
+
 ## Settings
 
 ```python

{openrag_sdk-0.3.1 → openrag_sdk-0.7.0.dev1}/openrag_sdk.egg-info/requires.txt

@@ -1,5 +1,6 @@
 httpx>=0.25.0
 pydantic>=2.0.0
+idna>=3.15
 
 [dev]
 pytest>=7.0.0

{openrag_sdk-0.3.1 → openrag_sdk-0.7.0.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openrag-sdk"
-version = "0.3.1"
+version = "0.7.0.dev1"
 description = "Official Python SDK for OpenRAG API"
 readme = "README.md"
 license = "MIT"
@@ -29,6 +29,7 @@ classifiers = [
 dependencies = [
     "httpx>=0.25.0",
     "pydantic>=2.0.0",
+    "idna>=3.15",
 ]
 
 [project.optional-dependencies]