@numa-tech/numa 1.25.0 → 1.26.0

package/scripts/export-kb-contract.py

@@ -31,15 +31,12 @@ AGENT_OPERATIONS = {
     ("post", "/upload-sessions/{session_id}/complete"): "complete_direct_upload",
     ("delete", "/upload-sessions/{session_id}"): "cancel_direct_upload",
     ("get", "/documents/{document_id}/download-ticket"): "get_document_download",
-    ("post", "/archives"): "start_async_archive",
     ("get", "/archives/{archive_id}"): "get_archive_status",
     ("post", "/archives/{archive_id}/retry"): "retry_archive",
 }
 PREFIX = "/api/v1/external/agent"
 OPERATIONS = {(method, PREFIX + suffix): name
               for (method, suffix), name in AGENT_OPERATIONS.items()} | {
-    ("post", "/api/v1/external/documents/batch-upload"):
-        "upload_external_documents_api_v1_external_documents_batch_upload_post",
     ("get", "/api/v1/external/batches/{batch_id}"):
         "get_external_batch_api_v1_external_batches__batch_id__get",
     ("post", "/api/v1/external/batches/{batch_id}/retry"):
@@ -49,6 +46,24 @@ OPERATIONS = {(method, PREFIX + suffix): name
 }
 
 
+NATIVE_OPERATIONS = {
+    '/collections/{collection_id}':['get','put','delete'],
+    '/collections/{collection_id}/transfer':['post'],
+    '/collections/{collection_id}/members':['get','put'],
+    '/collections/{collection_id}/members/{global_uid}':['delete'],
+    '/users/search':['get'], '/documents':['get'],
+    '/documents/{document_id}':['get','put','delete'],
+    '/documents/{document_id}/chunks':['get'], '/documents/{document_id}/assets':['get'],
+    '/documents/{document_id}/versions':['get'], '/documents/{document_id}/change-history':['get'],
+    '/documents/{document_id}/switch-version':['post'], '/documents/{document_id}/reindex':['post'],
+    '/batches':['get'], '/batch/{batch_id}/cancel':['post'], '/ingest-jobs':['get'],
+    '/conflict-reviews':['get'], '/conflict-reviews/{conflict_id}/resolve':['post'],
+    '/chat/stream':['post'], '/chat/sessions':['get','post'], '/chat/sessions/{session_id}':['get','delete'],
+    '/upload-sessions/preflight':['post'],
+}
+OPERATIONS.update({(method, '/api/v1/kb'+path):None for path,methods in NATIVE_OPERATIONS.items() for method in methods})
+
+
 def forbid_network(event: str, _args: tuple) -> None:
     if event in {"socket.connect", "socket.connect_ex", "socket.getaddrinfo", "socket.bind"}:
         raise RuntimeError("KB contract export must remain offline")
@@ -78,6 +93,8 @@ def export_contract(kb_root: Path) -> dict:
     from fastapi import FastAPI
     from backend.external.agent_routes import router
     from backend.external.routes import router as external_router
+    from backend.routes.knowledge_base import router as kb_router
+    from backend.routes.direct_uploads import router as upload_router
     from backend.knowledge_base.constants import (
         MAX_EXTERNAL_FILES_PER_BATCH,
         MAX_FILES_PER_BATCH,
@@ -89,11 +106,13 @@ def export_contract(kb_root: Path) -> dict:
     app = FastAPI(title="Knowledge Base Agent API")
     app.include_router(router, prefix="/api/v1")
     app.include_router(external_router, prefix="/api/v1")
+    app.include_router(kb_router,prefix="/api/v1")
+    app.include_router(upload_router,prefix="/api/v1")
     original = app.openapi()
     paths = {}
     for (method, path), operation_id in OPERATIONS.items():
         operation = original.get("paths", {}).get(path, {}).get(method)
-        if operation is None or operation.get("operationId") != operation_id:
+        if operation is None or (operation_id is not None and operation.get("operationId") != operation_id):
             raise ValueError(f"KB route contract changed: {method.upper()} {path}")
         paths.setdefault(path, {})[method] = operation
 
@@ -112,10 +131,10 @@ def export_contract(kb_root: Path) -> dict:
         "paths": paths,
         "components": {"schemas": selected},
         "x-numa-contract": {
-            "sources": ["backend/external/agent_routes.py", "backend/external/routes.py"],
+            "sources": ["backend/external/agent_routes.py", "backend/external/routes.py", "backend/routes/knowledge_base.py", "backend/routes/direct_uploads.py"],
             "generator": "scripts/export-kb-contract.py",
             "response_validation": "Responses are free-form upstream; validate consumed fields at runtime.",
-            "authentication": "X-Api-Key; deployments may additionally require Bearer application authorization.",
+            "authentication": "Keycloak Bearer JWT for native KB routes; legacy Agent API deployments may also support X-Api-Key.",
             "parse_supported_extensions": sorted(SUPPORTED_EXTS),
             "default_upload_limits": {
                 "max_files_per_batch": MAX_FILES_PER_BATCH,