OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
feat: expose GET /v1/files on public API surface with SDK support and case-insensitive filename search fix (#2215)
Jason Dongb0c77d0fdb8a
diff --git a/sdks/python/README.md b/sdks/python/README.mdindex d3c0b11ad..a818f4f07 100644--- a/sdks/python/README.md+++ b/sdks/python/README.md@@ -171,6 +171,50 @@ 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)+```+## Settings```pythondiff --git a/sdks/python/openrag_sdk/__init__.py b/sdks/python/openrag_sdk/__init__.pyindex 86bddffc2..86921232c 100644--- a/sdks/python/openrag_sdk/__init__.py+++ b/sdks/python/openrag_sdk/__init__.py@@ -49,13 +49,16 @@ from .models import (DeleteDocumentResponse,DeleteKnowledgeFilterResponse,DoneEvent,+ FileRecord,GetKnowledgeFilterResponse,IngestResponse,KnowledgeFilter,KnowledgeFilterQueryData,KnowledgeFilterSearchResponse,KnowledgeSettings,+ ListFilesResponse,Message,+ PrincipalLabel,SearchFilters,SearchResponse,SearchResult,@@ -82,6 +85,10 @@ __all__ = ["NotFoundError","ValidationError","ServerError",+ # File models+ "FileRecord",+ "ListFilesResponse",+ "PrincipalLabel",# Models"ChatResponse","ContentEvent",diff --git a/sdks/python/openrag_sdk/documents.py b/sdks/python/openrag_sdk/documents.pyindex 414144c3d..964e39f5b 100644--- a/sdks/python/openrag_sdk/documents.py+++ b/sdks/python/openrag_sdk/documents.py@@ -5,7 +5,13 @@ from pathlib import Pathfrom typing import TYPE_CHECKING, BinaryIOfrom .exceptions import NotFoundError-from .models import DeleteDocumentResponse, IngestResponse, IngestTaskStatus+from .models import (+ DeleteDocumentResponse,+ FileRecord,+ IngestResponse,+ IngestTaskStatus,+ ListFilesResponse,+)if TYPE_CHECKING:from .client import OpenRAGClient@@ -176,3 +182,67 @@ 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 in the knowledge base.++ 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, total count, and next after_key.+ """+ 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/v1/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"),+ )diff --git a/sdks/python/openrag_sdk/models.py b/sdks/python/openrag_sdk/models.pyindex b0eee0864..d7915267d 100644--- a/sdks/python/openrag_sdk/models.py+++ b/sdks/python/openrag_sdk/models.py@@ -284,3 +284,46 @@ class DeleteKnowledgeFilterResponse(BaseModel):success: boolerror: 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 ListFilesResponse(BaseModel):+ """Response from the list-files endpoint."""++ files: list[FileRecord]+ total: int+ is_approximate: bool+ page: int+ page_size: int+ after_key: dict | None = Nonediff --git a/sdks/typescript/README.md b/sdks/typescript/README.mdindex 6488d1f72..6645f1b13 100644--- a/sdks/typescript/README.md+++ b/sdks/typescript/README.md@@ -201,6 +201,46 @@ const result = await client.documents.delete("report.pdf");console.log(`Success: ${result.success}`);```+## Listing Files++`client.documents.listFiles()` inventories everything in the knowledge base and+returns the metadata needed to drive knowledge filters and search.++```typescript+// List the first page of files+const firstPage = await client.documents.listFiles({ page_size: 50 });+for (const f of firstPage.files) {+ console.log(`${f.filename} (${f.mimetype}, ${f.chunk_count} chunks)`);+}++// Cursor-paginate through all files+let afterKey: string | undefined;+do {+ const page = await client.documents.listFiles({ page_size: 100, after_key: afterKey });+ for (const f of page.files) console.log(f.filename);+ afterKey = page.after_key ? JSON.stringify(page.after_key) : undefined;+} while (afterKey);++// Filter and sort+const sortedPage = await client.documents.listFiles({+ connector_type: "sharepoint",+ sort_by: "indexed_time",+ sort_order: "desc",+});++// List → create knowledge filter workflow+const sharepointPage = await client.documents.listFiles({ connector_type: "sharepoint" });+const filenames = sharepointPage.files.map(f => f.filename);+const { id: filterId } = await client.knowledgeFilters.create({+ name: "SharePoint docs",+ queryData: { filters: { data_sources: filenames } },+});++// Use the filter in search and chat+const results = await client.search.query("quarterly report", { filterId });+const response = await client.chat.create({ message: "Summarise Q3", filterId });+```+## Settings```typescriptdiff --git a/sdks/typescript/src/documents.ts b/sdks/typescript/src/documents.tsindex 274fce9a2..9cf3fb211 100644--- a/sdks/typescript/src/documents.ts+++ b/sdks/typescript/src/documents.ts@@ -6,8 +6,11 @@ import type { OpenRAGClient } from "./client";import type {DeleteDocumentOptions,DeleteDocumentResponse,+ FileRecord,IngestResponse,IngestTaskStatus,+ ListFilesOptions,+ ListFilesResponse,NotFoundError,} from "./types";@@ -144,6 +147,39 @@ export class DocumentsClient {return new Promise((resolve) => setTimeout(resolve, ms));}+ /**+ * List ingested files in the knowledge base.+ *+ * @param options - Filtering, sorting, and pagination options.+ * @returns ListFilesResponse with files list, total count, and next after_key.+ */+ async listFiles(options: ListFilesOptions = {}): Promise<ListFilesResponse> {+ const params = new URLSearchParams();+ if (options.page !== undefined) params.set("page", String(options.page));+ if (options.page_size !== undefined) params.set("page_size", String(options.page_size));+ if (options.sort_by !== undefined) params.set("sort_by", options.sort_by);+ if (options.sort_order !== undefined) params.set("sort_order", options.sort_order);+ if (options.connector_type !== undefined) params.set("connector_type", options.connector_type);+ if (options.mimetype !== undefined) params.set("mimetype", options.mimetype);+ if (options.owner !== undefined) params.set("owner", options.owner);+ if (options.search !== undefined) params.set("search", options.search);+ if (options.after_key !== undefined) params.set("after_key", options.after_key);++ const qs = params.toString();+ const path = qs ? `/api/v1/files?${qs}` : "/api/v1/files";+ const response = await this.client._request("GET", path);+ const data = await response.json();++ return {+ files: (data.files ?? []) as FileRecord[],+ total: data.total ?? 0,+ is_approximate: data.is_approximate ?? true,+ page: data.page ?? 1,+ page_size: data.page_size ?? 25,+ after_key: data.after_key ?? null,+ };+ }+/*** Delete document(s) from the knowledge base.*diff --git a/sdks/typescript/src/index.ts b/sdks/typescript/src/index.tsindex 3283f118c..0b438b360 100644--- a/sdks/typescript/src/index.ts+++ b/sdks/typescript/src/index.ts@@ -65,6 +65,10 @@ export {// Document typesIngestResponse,DeleteDocumentResponse,+ PrincipalLabel,+ FileRecord,+ ListFilesResponse,+ ListFilesOptions,// Conversation typesConversation,ConversationDetail,diff --git a/sdks/typescript/src/types.ts b/sdks/typescript/src/types.tsindex 44b7c9acd..941ab9b55 100644--- a/sdks/typescript/src/types.ts+++ b/sdks/typescript/src/types.ts@@ -88,6 +88,68 @@ export interface DeleteDocumentOptions {filterId?: string;}+/** A principal label entry in a file's ACL (connector-ingested files only). */+export interface PrincipalLabel {+ principal: string;+ kind: string;+ provider: string;+ display_name?: string;+ email?: string;+ external_id?: string;+}++// File structure type+export interface FileRecord {+ filename: string;+ document_id: string;+ mimetype: string;+ file_size: number;+ source_url: string;+ owner: string;+ owner_name: string;+ owner_email: string;+ connector_type: string;+ embedding_model: string;+ embedding_dimensions: number | null;+ indexed_time: string;+ chunk_count: number;+ allowed_users: string[];+ allowed_groups: string[];+ allowed_principal_labels: PrincipalLabel[];+}++//Response from the list-files endpoint+export interface ListFilesResponse {+ files: FileRecord[];+ total: number;+ is_approximate: boolean;+ page: number;+ page_size: number;+ after_key: Record<string, unknown> | null;+}++/** Options for listing files. */+export interface ListFilesOptions {+ /** Page number (display only; use after_key for cursor navigation). Default: 1. */+ page?: number;+ /** Files per page (1–500). Default: 25. */+ page_size?: number;+ /** Sort field: filename | file_size | mimetype | indexed_time | connector_type | chunk_count | owner. */+ sort_by?: string;+ /** Sort direction. Default: "asc". */+ sort_order?: "asc" | "desc";+ /** Filter by connector type. */+ connector_type?: string;+ /** Filter by MIME type. */+ mimetype?: string;+ /** Filter by owner user ID. */+ owner?: string;+ /** Substring/prefix filename search. */+ search?: string;+ /** JSON-encoded composite cursor from a previous response's after_key. */+ after_key?: string;+}+// Chat history typesexport interface Message {role: string;diff --git a/sdks/typescript/tests/integration.test.ts b/sdks/typescript/tests/integration.test.tsindex b0fff1991..fe21325c4 100644--- a/sdks/typescript/tests/integration.test.ts+++ b/sdks/typescript/tests/integration.test.ts@@ -943,4 +943,107 @@ describe.skipIf(SKIP_TESTS)("OpenRAG TypeScript SDK Integration", () => {).rejects.toThrow(NotFoundError);});});++ describe("Files (listFiles)", () => {+ it("returns a valid ListFilesResponse shape", async () => {+ const result = await client.documents.listFiles({ page_size: 10 });++ expect(typeof result.total).toBe("number");+ expect(result.total).toBeGreaterThanOrEqual(0);+ expect(typeof result.is_approximate).toBe("boolean");+ expect(result.page).toBe(1);+ expect(result.page_size).toBe(10);+ expect(Array.isArray(result.files)).toBe(true);+ // after_key is null on a single page or a cursor dict on multi-page+ expect(result.after_key === null || typeof result.after_key === "object").toBe(true);+ });++ it("each FileRecord contains fields required for knowledge filter construction", async () => {+ // Ingest a known file so there is at least one record+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-lf-"));+ const fname = `lf_test_${Date.now()}.md`;+ const fpath = path.join(tmpDir, fname);+ fs.writeFileSync(fpath, "# List Files Test\n\nUnique content about silver foxes.\n");+ await client.documents.ingest({ filePath: fpath });++ try {+ const result = await client.documents.listFiles({ search: fname });+ const match = result.files.find((r) => r.filename === fname);+ expect(match).toBeDefined();++ const f = match!;+ // Core identity+ expect(typeof f.filename).toBe("string");+ expect(f.filename.length).toBeGreaterThan(0);+ expect(typeof f.document_id).toBe("string");+ // Knowledge-filter fields+ expect(typeof f.connector_type).toBe("string");+ expect(typeof f.mimetype).toBe("string");+ expect(typeof f.owner).toBe("string");+ // Pagination / metadata+ expect(typeof f.chunk_count).toBe("number");+ expect(f.chunk_count).toBeGreaterThanOrEqual(0);+ expect(typeof f.file_size).toBe("number");+ expect(typeof f.indexed_time).toBe("string");+ // ACL fields+ expect(Array.isArray(f.allowed_users)).toBe(true);+ expect(Array.isArray(f.allowed_groups)).toBe(true);+ expect(Array.isArray(f.allowed_principal_labels)).toBe(true);+ } finally {+ await client.documents.delete(fname);+ }+ }, 120_000);++ it("cursor pagination returns non-overlapping pages", async () => {+ const page1 = await client.documents.listFiles({ page_size: 1 });+ expect(page1.files.length).toBeLessThanOrEqual(1);++ if (page1.after_key !== null && page1.total > 1) {+ const page2 = await client.documents.listFiles({+ page_size: 1,+ after_key: JSON.stringify(page1.after_key),+ });+ const p1Names = new Set(page1.files.map((f) => f.filename));+ const p2Names = new Set(page2.files.map((f) => f.filename));+ for (const n of p2Names) {+ expect(p1Names.has(n)).toBe(false);+ }+ }+ });++ it("list → create filter workflow produces a usable filter", async () => {+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-lf-wf-"));+ const fname = `lf_wf_${Date.now()}.md`;+ const fpath = path.join(tmpDir, fname);+ fs.writeFileSync(fpath, "# Workflow Test\n\nContent about crimson crabs.\n");+ await client.documents.ingest({ filePath: fpath });+ let filterId: string | undefined;++ try {+ const page = await client.documents.listFiles({ search: fname });+ const match = page.files.find((f) => f.filename === fname);+ expect(match).toBeDefined();++ const createResult = await client.knowledgeFilters.create({+ name: `TS list-files workflow ${Date.now()}`,+ queryData: {+ filters: {+ data_sources: [match!.filename],+ document_types: ["*"],+ owners: ["*"],+ connector_types: ["*"],+ },+ limit: 10,+ scoreThreshold: 0,+ },+ });+ expect(createResult.success).toBe(true);+ expect(createResult.id).toBeDefined();+ filterId = createResult.id!;+ } finally {+ if (filterId) await client.knowledgeFilters.delete(filterId);+ await client.documents.delete(fname);+ }+ }, 120_000);+ });});diff --git a/src/api/v1/files.py b/src/api/v1/files.pynew file mode 100644index 000000000..cdce9382d--- /dev/null+++ b/src/api/v1/files.py@@ -0,0 +1,80 @@+"""+Public API v1 Files endpoints.++Provides file listing and search over the ingested knowledge base.+Uses API key authentication — delegates to the api/v2/files.py handlers+but overrides the user dependency to use API keys.+"""++from fastapi import Depends, Query++from api.v2 import files as files_v2+from dependencies import get_file_service_v2, require_api_key_permission+from session_manager import User+from utils.logging_config import get_logger++logger = get_logger(__name__)+++async def list_files(+ page: int = Query(+ 1, ge=1, description="Page number (for display only; navigation uses after_key cursor)"+ ),+ page_size: int = Query(25, ge=1, le=500, description="Items per page"),+ sort_by: str = Query("filename", description="Sort field"),+ sort_order: str = Query("asc", pattern="^(asc|desc)$", description="Sort order"),+ connector_type: str | None = Query(None, description="Filter by connector type"),+ mimetype: str | None = Query(None, description="Filter by MIME type"),+ owner: str | None = Query(None, description="Filter by owner"),+ search: str | None = Query(None, description="Search filename"),+ after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),+ file_service=Depends(get_file_service_v2),+ user: User = Depends(require_api_key_permission("knowledge:read:own")),+):+ """+ List all ingested files.++ GET /v1/files+ """+ return await files_v2.list_files(+ page=page,+ page_size=page_size,+ sort_by=sort_by,+ sort_order=sort_order,+ connector_type=connector_type,+ mimetype=mimetype,+ owner=owner,+ search=search,+ after_key=after_key,+ file_service=file_service,+ user=user,+ )+++async def search_files(+ q: str = Query(..., min_length=1, description="Search query"),+ page: int = Query(1, ge=1, description="Page number"),+ page_size: int = Query(25, ge=1, le=500, description="Items per page"),+ connector_type: str | None = Query(None, description="Filter by connector type"),+ mimetype: str | None = Query(None, description="Filter by MIME type"),+ owner: str | None = Query(None, description="Filter by owner"),+ after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),+ file_service=Depends(get_file_service_v2),+ user: User = Depends(require_api_key_permission("knowledge:read:own")),+):+ """+ Search ingested files by name with fuzzy/partial matching.++ GET /v1/files/search+ """+ return await files_v2.search_files(+ q=q,+ page=page,+ page_size=page_size,+ connector_type=connector_type,+ mimetype=mimetype,+ owner=owner,+ after_key=after_key,+ file_service=file_service,+ user=user,+ )diff --git a/src/app/routes/public_v1.py b/src/app/routes/public_v1.pyindex 557745e2c..d3063c39f 100644--- a/src/app/routes/public_v1.py+++ b/src/app/routes/public_v1.py@@ -8,6 +8,9 @@ from api.v1 import (from api.v1 import (documents as v1_documents,)+from api.v1 import (+ files as v1_files,+)from api.v1 import (knowledge_filters as v1_knowledge_filters,)@@ -130,3 +133,17 @@ def register_public_v1_routes(app: FastAPI):methods=["DELETE"],tags=["public"],)+ # Files endpoints+ # /v1/files/search must be registered before /v1/files to avoid path shadowing+ app.add_api_route(+ "/v1/files/search",+ v1_files.search_files,+ methods=["GET"],+ tags=["public"],+ )+ app.add_api_route(+ "/v1/files",+ v1_files.list_files,+ methods=["GET"],+ tags=["public"],+ )diff --git a/src/mcp_http/server.py b/src/mcp_http/server.pyindex ec35ade22..c248dab5a 100644--- a/src/mcp_http/server.py+++ b/src/mcp_http/server.py@@ -188,6 +188,15 @@ COMPONENT_CUSTOMIZATIONS: dict[tuple[str, str], dict[str, str]] = {"name": "openrag_delete_knowledge_filter","description": "Delete a knowledge filter by ID.",},+ # files endpoints+ ("/v1/files", "GET"): {+ "name": "openrag_list_files",+ "description": "List all ingested files",+ },+ ("/v1/files/search", "GET"): {+ "name": "openrag_search_files",+ "description": "Search files by query parameters.",+ },}diff --git a/src/services/file_service.py b/src/services/file_service.pyindex dc5f620d7..f18b5269e 100644--- a/src/services/file_service.py+++ b/src/services/file_service.py@@ -123,13 +123,25 @@ class FileService:filter_clauses.append({"term": {"owner": owner}})if search:- # Combine wildcard (partial), prefix, and fuzzy for flexible matching+ # Combine wildcard (partial) and prefix for flexible matching.+ # case_insensitive=True so "jason" matches "JASON_RESUME.pdf".must.append({"bool": {"should": [- {"wildcard": {"filename": {"value": f"*{search.lower()}*"}}},- {"prefix": {"filename": search.lower()}},+ {+ "wildcard": {+ "filename": {+ "value": f"*{search.lower()}*",+ "case_insensitive": True,+ }+ }+ },+ {+ "prefix": {+ "filename": {"value": search.lower(), "case_insensitive": True}+ }+ },],"minimum_should_match": 1,}diff --git a/src/services/file_service_v2.py b/src/services/file_service_v2.pyindex 6a4607dd0..fc78e24d6 100644--- a/src/services/file_service_v2.py+++ b/src/services/file_service_v2.py@@ -242,8 +242,19 @@ class FileServiceV2:{"bool": {"should": [- {"wildcard": {"filename": {"value": f"*{search.lower()}*"}}},- {"prefix": {"filename": search.lower()}},+ {+ "wildcard": {+ "filename": {+ "value": f"*{search.lower()}*",+ "case_insensitive": True,+ }+ }+ },+ {+ "prefix": {+ "filename": {"value": search.lower(), "case_insensitive": True}+ }+ },],"minimum_should_match": 1,}@@ -398,7 +409,7 @@ class FileServiceV2:"""Approximate unique-filename count via cardinality aggregation (O(1)).Returns (count, is_approximate). is_approximate is always True on- success (cardinality agg is inherently approximate) and False when the+ success (cardinality agg is inherently approximate) and True when theaggregation fails and 0 is returned as a fallback."""body = {diff --git a/tests/integration/sdk/test_list_files.py b/tests/integration/sdk/test_list_files.pynew file mode 100644index 000000000..ac36228fb--- /dev/null+++ b/tests/integration/sdk/test_list_files.py@@ -0,0 +1,178 @@+"""Integration tests for client.documents.list_files().++These tests require a running OpenRAG instance and at least one ingested file.+They are skipped when SKIP_SDK_INTEGRATION_TESTS=true (CI without a live stack).+"""++import json+import os+import uuid+from pathlib import Path++import pytest++pytestmark = pytest.mark.skipif(+ os.environ.get("SKIP_SDK_INTEGRATION_TESTS") == "true",+ reason="SDK integration tests skipped",+)+++class TestListFiles:+ """Verify GET /v1/files via the Python SDK."""++ @pytest.mark.asyncio+ async def test_list_files_returns_valid_response_shape(self, client, test_file: Path):+ """list_files() returns a ListFilesResponse with required fields."""+ # Ingest a file so there is at least one result+ await client.documents.ingest(file_path=str(test_file))+ try:+ result = await client.documents.list_files(page_size=10)++ assert result.total >= 0+ assert isinstance(result.is_approximate, bool)+ assert result.page == 1+ assert result.page_size == 10+ assert isinstance(result.files, list)+ finally:+ await client.documents.delete(test_file.name)++ @pytest.mark.asyncio+ async def test_list_files_record_has_all_knowledge_filter_fields(self, client, test_file: Path):+ """Each FileRecord contains the fields needed to build a knowledge filter."""+ await client.documents.ingest(file_path=str(test_file))+ try:+ result = await client.documents.list_files(search=test_file.stem)+ assert len(result.files) >= 1, "Expected the ingested file to appear in results"++ f = result.files[0]+ # Core identity fields+ assert isinstance(f.filename, str) and f.filename+ assert isinstance(f.document_id, str)+ # Fields needed to build queryData.filters+ assert isinstance(f.connector_type, str)+ assert isinstance(f.mimetype, str)+ assert isinstance(f.owner, str)+ # Pagination / metadata fields+ assert isinstance(f.chunk_count, int) and f.chunk_count >= 0+ assert isinstance(f.file_size, int) and f.file_size >= 0+ assert isinstance(f.indexed_time, str) and f.indexed_time+ # ACL fields (may be empty lists but must be present)+ assert isinstance(f.allowed_users, list)+ assert isinstance(f.allowed_groups, list)+ assert isinstance(f.allowed_principal_labels, list)+ finally:+ await client.documents.delete(test_file.name)++ @pytest.mark.asyncio+ async def test_list_files_pagination(self, client, tmp_path: Path):+ """page_size is respected and after_key cursor enables non-overlapping pages.++ Three files are ingested with a unique token prefix. Both page requests+ are scoped to that prefix so unrelated index content cannot interfere.+ With page_size=2 and 3 matching files, page 1 must return an after_key —+ the assertion is unconditional, not conditional, so the test fails clearly+ if the cursor is missing.+ """+ token = uuid.uuid4().hex[:8]+ files = []+ for i in range(3):+ p = tmp_path / f"pg_{token}_{i}.md"+ p.write_text(f"# Page test {i}\n\nContent {uuid.uuid4()}.\n")+ await client.documents.ingest(file_path=str(p))+ files.append(p)++ try:+ page1 = await client.documents.list_files(+ page_size=2,+ search=f"pg_{token}",+ )+ assert len(page1.files) == 2, f"Expected 2 files on page 1, got {len(page1.files)}"+ assert page1.after_key is not None, (+ "Expected an after_key cursor with 3 matching files at page_size=2"+ )++ page2 = await client.documents.list_files(+ page_size=2,+ search=f"pg_{token}",+ after_key=json.dumps(page1.after_key),+ )+ assert isinstance(page2.files, list)+ assert len(page2.files) >= 1, (+ f"Expected at least 1 file on page 2, got {len(page2.files)}"+ )+ # Pages must not overlap by filename+ p1_names = {f.filename for f in page1.files}+ p2_names = {f.filename for f in page2.files}+ assert p1_names.isdisjoint(p2_names), f"Pages overlap: {p1_names & p2_names}"+ finally:+ for p in files:+ await client.documents.delete(p.name)++ @pytest.mark.asyncio+ async def test_list_files_search_filters_by_filename(self, client, tmp_path: Path):+ """search= filters by filename and is case-insensitive.++ The needle file has an uppercase prefix (NEEDLE_); the search term is+ lowercase ('needle_'). This directly exercises the case_insensitive fix+ in _build_filter_query.+ """+ token = uuid.uuid4().hex[:8]+ # Uppercase filename — search with lowercase to verify case-insensitive matching+ needle = tmp_path / f"NEEDLE_{token}.md"+ haystack = tmp_path / f"haystack_{token}.md"+ needle.write_text("# Needle\n\nUnique needle content.\n")+ haystack.write_text("# Haystack\n\nUnrelated haystack content.\n")++ await client.documents.ingest(file_path=str(needle))+ await client.documents.ingest(file_path=str(haystack))++ try:+ # Search with lowercase — must match the uppercase filename+ result = await client.documents.list_files(search=f"needle_{token}")+ filenames = [f.filename for f in result.files]+ assert any(f"NEEDLE_{token}" in fn for fn in filenames), (+ f"Case-insensitive search for 'needle_{token}' should match "+ f"'NEEDLE_{token}.md', got: {filenames}"+ )+ assert not any(f"haystack_{token}" in fn for fn in filenames), (+ f"Haystack should not appear in needle search, got: {filenames}"+ )+ finally:+ await client.documents.delete(needle.name)+ await client.documents.delete(haystack.name)++ @pytest.mark.asyncio+ async def test_list_then_create_filter_workflow(self, client, test_file: Path):+ """Filenames from list_files can be used directly as knowledge filter data_sources."""+ await client.documents.ingest(file_path=str(test_file))+ filter_id = None++ try:+ page = await client.documents.list_files(search=test_file.stem)+ assert len(page.files) >= 1, "Ingested file must appear in list"++ filenames = [f.filename for f in page.files]+ result = await client.knowledge_filters.create(+ {+ "name": f"list-then-filter {uuid.uuid4().hex[:6]}",+ "description": "Created by SDK list_files integration test",+ "queryData": {+ "query": "",+ "filters": {+ "data_sources": filenames,+ "document_types": ["*"],+ "owners": ["*"],+ "connector_types": ["*"],+ },+ "limit": 10,+ "scoreThreshold": 0,+ },+ }+ )+ assert result.success is True+ assert result.id is not None+ filter_id = result.id+ finally:+ if filter_id:+ await client.knowledge_filters.delete(filter_id)+ await client.documents.delete(test_file.name)diff --git a/tests/unit/api/test_v1_files.py b/tests/unit/api/test_v1_files.pynew file mode 100644index 000000000..655912463--- /dev/null+++ b/tests/unit/api/test_v1_files.py@@ -0,0 +1,350 @@+"""+Unit tests for the GET /v1/files and GET /v1/files/search route handlers.++Tests cover:+- Route delegates to the v2 handler with all params forwarded correctly+- Auth dependency is require_api_key_permission("knowledge:read:own"),+ NOT get_current_user+- 401 returned on OpenSearch auth errors+- 400 returned on malformed after_key cursor+- 500 returned on unexpected errors+"""++import inspect+from unittest.mock import AsyncMock, MagicMock++import pytest+from fastapi import params as fastapi_params++from api.v1.files import list_files, search_files+from session_manager import User++# ---------------------------------------------------------------------------+# Auth-dependency introspection helpers+# ---------------------------------------------------------------------------+++def _get_user_dependency(fn) -> object:+ """Return the raw dependency object wired to the `user` parameter of `fn`."""+ sig = inspect.signature(fn)+ user_param = sig.parameters.get("user")+ assert user_param is not None, f"{fn.__name__} has no `user` parameter"+ default = user_param.default+ assert isinstance(default, fastapi_params.Depends), (+ f"`user` default in {fn.__name__} is not a FastAPI Depends()"+ )+ return default.dependency+++def _extract_permission(dep) -> str:+ """Extract the permission string from a require_api_key_permission closure."""+ # require_api_key_permission(perm) returns a closure _dep whose __closure__+ # holds exactly one cell: the `perm` string.+ assert dep.__closure__ is not None, "dependency has no closure — not a permission closure"+ perm_values = [cell.cell_contents for cell in dep.__closure__]+ assert len(perm_values) == 1, (+ f"Expected exactly one closure cell, got {len(perm_values)}: {perm_values}"+ )+ return perm_values[0]+++# ---------------------------------------------------------------------------+# Route-level dependency tests+# ---------------------------------------------------------------------------+++class TestAuthDependency:+ def test_list_files_uses_require_api_key_permission(self):+ """list_files must be gated by require_api_key_permission, not get_current_user."""+ dep = _get_user_dependency(list_files)+ perm = _extract_permission(dep)+ assert perm == "knowledge:read:own", f"Expected 'knowledge:read:own', got '{perm}'"++ def test_search_files_uses_require_api_key_permission(self):+ """search_files must be gated by require_api_key_permission, not get_current_user."""+ dep = _get_user_dependency(search_files)+ perm = _extract_permission(dep)+ assert perm == "knowledge:read:own", f"Expected 'knowledge:read:own', got '{perm}'"++ def test_list_files_and_search_files_use_same_permission(self):+ """Both handlers must require the same permission — no accidental divergence."""+ list_perm = _extract_permission(_get_user_dependency(list_files))+ search_perm = _extract_permission(_get_user_dependency(search_files))+ assert list_perm == search_perm+++def _make_user() -> User:+ user = MagicMock(spec=User)+ user.user_id = "test-user-id"+ user.jwt_token = "test-jwt"+ return user+++def _make_file_service(result: dict) -> MagicMock:+ svc = MagicMock()+ svc.list_files = AsyncMock(return_value=result)+ svc.search_files = AsyncMock(return_value=result)+ return svc+++_SAMPLE_RESPONSE = {+ "files": [+ {+ "filename": "report.pdf",+ "document_id": "doc-1",+ "mimetype": "application/pdf",+ "file_size": 12345,+ "source_url": "",+ "owner": "user-1",+ "owner_name": "Alice",+ "owner_email": "[email protected]",+ "connector_type": "local",+ "embedding_model": "text-embedding-3-small",+ "embedding_dimensions": 1536,+ "indexed_time": "2024-01-01T00:00:00Z",+ "chunk_count": 5,+ "allowed_users": [],+ "allowed_groups": [],+ "allowed_principal_labels": [],+ }+ ],+ "total": 1,+ "is_approximate": True,+ "page": 1,+ "page_size": 25,+ "after_key": None,+}+++# ---------------------------------------------------------------------------+# list_files+# ---------------------------------------------------------------------------+++class TestListFiles:+ @pytest.mark.asyncio+ async def test_returns_file_list_on_success(self):+ """Handler returns the service response as JSONResponse."""+ file_service = _make_file_service(_SAMPLE_RESPONSE)+ user = _make_user()++ response = await list_files(+ page=1,+ page_size=25,+ sort_by="filename",+ sort_order="asc",+ connector_type=None,+ mimetype=None,+ owner=None,+ search=None,+ after_key=None,+ file_service=file_service,+ user=user,+ )++ assert response.status_code == 200+ import json++ body = json.loads(response.body)+ assert body["total"] == 1+ assert body["files"][0]["filename"] == "report.pdf"+ # Verify all filter/knowledge fields are present+ f = body["files"][0]+ for field in (+ "document_id",+ "mimetype",+ "file_size",+ "connector_type",+ "chunk_count",+ "indexed_time",+ "allowed_users",+ ):+ assert field in f, f"Missing field: {field}"++ @pytest.mark.asyncio+ async def test_forwards_all_params_to_service(self):+ """All query params are forwarded to FileServiceV2.list_files."""+ file_service = _make_file_service(_SAMPLE_RESPONSE)+ user = _make_user()++ await list_files(+ page=2,+ page_size=50,+ sort_by="indexed_time",+ sort_order="desc",+ connector_type="sharepoint",+ mimetype="application/pdf",+ owner="user-42",+ search="report",+ after_key='{"filename": "a.pdf"}',+ file_service=file_service,+ user=user,+ )++ file_service.list_files.assert_awaited_once()+ call_kwargs = file_service.list_files.call_args.kwargs+ assert call_kwargs["page"] == 2+ assert call_kwargs["page_size"] == 50+ assert call_kwargs["sort_by"] == "indexed_time"+ assert call_kwargs["sort_order"] == "desc"+ assert call_kwargs["connector_type"] == "sharepoint"+ assert call_kwargs["mimetype"] == "application/pdf"+ assert call_kwargs["owner"] == "user-42"+ assert call_kwargs["search"] == "report"+ assert call_kwargs["after_key"] == {"filename": "a.pdf"}++ @pytest.mark.asyncio+ async def test_returns_401_on_opensearch_auth_error(self):+ """OpenSearch auth errors surface as 401, not 500."""+ from opensearchpy.exceptions import AuthenticationException++ file_service = MagicMock()+ file_service.list_files = AsyncMock(side_effect=AuthenticationException(401, "auth failed"))+ user = _make_user()++ response = await list_files(+ page=1,+ page_size=25,+ sort_by="filename",+ sort_order="asc",+ connector_type=None,+ mimetype=None,+ owner=None,+ search=None,+ after_key=None,+ file_service=file_service,+ user=user,+ )++ assert response.status_code == 401++ @pytest.mark.asyncio+ async def test_returns_500_on_unexpected_error(self):+ """Unexpected errors return 500."""+ file_service = MagicMock()+ file_service.list_files = AsyncMock(side_effect=RuntimeError("boom"))+ user = _make_user()++ response = await list_files(+ page=1,+ page_size=25,+ sort_by="filename",+ sort_order="asc",+ connector_type=None,+ mimetype=None,+ owner=None,+ search=None,+ after_key=None,+ file_service=file_service,+ user=user,+ )++ assert response.status_code == 500++ @pytest.mark.asyncio+ async def test_invalid_after_key_returns_400(self):+ """A non-JSON after_key value raises HTTPException 400 before the service is called."""+ from fastapi import HTTPException++ file_service = _make_file_service(_SAMPLE_RESPONSE)+ user = _make_user()++ with pytest.raises(HTTPException) as exc_info:+ await list_files(+ page=1,+ page_size=25,+ sort_by="filename",+ sort_order="asc",+ connector_type=None,+ mimetype=None,+ owner=None,+ search=None,+ after_key="not-valid-json",+ file_service=file_service,+ user=user,+ )++ assert exc_info.value.status_code == 400++ @pytest.mark.asyncio+ async def test_after_key_non_dict_returns_400(self):+ """A valid JSON non-dict after_key (e.g. a string) raises HTTPException 400."""+ import json++ from fastapi import HTTPException++ file_service = _make_file_service(_SAMPLE_RESPONSE)+ user = _make_user()++ with pytest.raises(HTTPException) as exc_info:+ await list_files(+ page=1,+ page_size=25,+ sort_by="filename",+ sort_order="asc",+ connector_type=None,+ mimetype=None,+ owner=None,+ search=None,+ after_key=json.dumps("just-a-string"),+ file_service=file_service,+ user=user,+ )++ assert exc_info.value.status_code == 400+++# ---------------------------------------------------------------------------+# search_files+# ---------------------------------------------------------------------------+++class TestSearchFiles:+ @pytest.mark.asyncio+ async def test_returns_search_results_on_success(self):+ """search_files delegates to v2.search_files and returns its result."""+ file_service = _make_file_service(_SAMPLE_RESPONSE)+ user = _make_user()++ response = await search_files(+ q="report",+ page=1,+ page_size=25,+ connector_type=None,+ mimetype=None,+ owner=None,+ after_key=None,+ file_service=file_service,+ user=user,+ )++ assert response.status_code == 200+ import json++ body = json.loads(response.body)+ assert "files" in body++ @pytest.mark.asyncio+ async def test_forwards_q_and_filters_to_service(self):+ """q and all filter params are forwarded to FileServiceV2.search_files."""+ file_service = _make_file_service(_SAMPLE_RESPONSE)+ user = _make_user()++ await search_files(+ q="annual report",+ page=2,+ page_size=10,+ connector_type="gdrive",+ mimetype="text/plain",+ owner="user-7",+ after_key=None,+ file_service=file_service,+ user=user,+ )++ file_service.search_files.assert_awaited_once()+ kwargs = file_service.search_files.call_args.kwargs+ assert kwargs["query"] == "annual report"+ assert kwargs["connector_type"] == "gdrive"+ assert kwargs["mimetype"] == "text/plain"+ assert kwargs["owner"] == "user-7"diff --git a/tests/unit/test_query_acl_filtering.py b/tests/unit/test_query_acl_filtering.pyindex 4917996ff..df7833287 100644--- a/tests/unit/test_query_acl_filtering.py+++ b/tests/unit/test_query_acl_filtering.py@@ -23,8 +23,22 @@ def test_file_service_query_omits_application_acl_filter():{"bool": {"should": [- {"wildcard": {"filename": {"value": "*roadmap*"}}},- {"prefix": {"filename": "roadmap"}},+ {+ "wildcard": {+ "filename": {+ "value": "*roadmap*",+ "case_insensitive": True,+ }+ }+ },+ {+ "prefix": {+ "filename": {+ "value": "roadmap",+ "case_insensitive": True,+ }+ }+ },],"minimum_should_match": 1,}