@arbidocs/client 0.3.29 → 0.3.31

package/dist/index.d.cts

@@ -726,7 +726,11 @@ interface paths {
         };
         /**
          * List Documents
-         * @description List all documents in the current workspace.
+         * @description List documents in the current workspace.
+         *
+         *     By default returns all documents (no pagination) since the frontend needs
+         *     the full set for client-side sort/search/filter. Pass ``limit``/``offset``
+         *     to opt into pagination — useful for the CLI when streaming a workspace.
          */
         get: operations['list_documents'];
         put?: never;
@@ -794,8 +798,17 @@ interface paths {
          * @description Update one or more documents.
          *
          *     Special status handling:
-         *     - status="processing": Smart reprocess - reindexes if final.pklenc exists, else full re-parse.
-         *       Skips if doc was updated < 10 min ago (prevents duplicate submissions).
+         *     - status="processing": Smart reprocess — reindexes if final.pklenc exists in MinIO
+         *       (regardless of current doc.status), else full re-parse from the original file.
+         *       Skips if a fresh Redis task already exists for the doc (< 10 min old).
+         *
+         *     Batch behavior: the request handler validates + commits ORM field updates
+         *     synchronously, then hands the reprocess work off to a FastAPI background task
+         *     (dispatch_batch_reprocess). The response returns as soon as the background task
+         *     is scheduled, so a single user asking to reprocess 1000+ docs does not block
+         *     the event loop or tie up an HTTP worker. The background dispatcher fans out
+         *     requeue_document_processing calls bounded by the existing deployment-wide
+         *     _indexing_semaphore to keep other users responsive.
          */
         patch: operations['update_documents'];
         trace?: never;
@@ -1027,7 +1040,26 @@ interface paths {
         };
         /**
          * Get Threads With Histories
-         * @description Retrieve all conversation threads (leaf messages and their histories) for a given conversation external ID.
+         * @description Retrieve all conversation threads (leaf messages and their histories).
+         *
+         *     Performance notes
+         *     -----------------
+         *     This endpoint used to issue 3+ DB round-trips per message in every
+         *     history (user_ext_id, config_ext_id, parent_ext_id) and serially decrypt
+         *     each message's tools blob on the event loop. For a conversation with N
+         *     forks of M messages each that's O(N*M) round-trips. The rewrite is
+         *     O(forks) DB calls plus three constant-count batch queries:
+         *
+         *       1. ``get_threads`` to find leaf message ids
+         *       2. one ``get_conversation_history`` recursive CTE per leaf
+         *       3. one batched user-ext-id query (across every message in every fork)
+         *       4. one batched configuration-ext-id query
+         *       5. one ``asyncio.gather`` over ``decrypt_tools_async`` so blobs decrypt
+         *          in parallel on worker threads instead of one-at-a-time on the loop
+         *
+         *     Parent message ext_ids are read off the already-fetched message set —
+         *     parents are by definition ancestors of leaves, so they're always in the
+         *     history we just loaded. No extra query.
          */
         get: operations['get_conversation_threads'];
         put?: never;
@@ -1272,6 +1304,35 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/v1/health/metrics': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get Metrics
+         * @description Live operational metrics for this instance (developer-only).
+         *
+         *     Returns a structured snapshot of DB pool utilisation, in-process
+         *     semaphores (embedder, reranker, indexing, qdrant, doctag_llm, etc.),
+         *     Redis queue backpressure for this deployment, and the current
+         *     asyncio task count. Same data the periodic concurrency_monitor
+         *     logger emits, but as JSON for dashboards / probes / tests.
+         *
+         *     Gated to developer accounts because the payload exposes internal
+         *     pool sizes and saturation — useful for recon if leaked to end users.
+         */
+        get: operations['get_metrics'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/v1/tag/list': {
         parameters: {
             query?: never;
@@ -1373,10 +1434,10 @@ interface paths {
         };
         /**
          * Get Notifications
-         * @description Retrieve all notifications for the current user.
+         * @description Retrieve notifications for the current user, newest first.
          *
-         *     Returns notifications ordered by most recent first.
-         *     Bilateral model: user sees notifications they sent OR received.
+         *     Bilateral model: user sees notifications they sent OR received. Capped at
+         *     ``limit`` (default 100) so the response stays small for chatty users.
          *     Use POST /notifications/read to mark specific notifications as read.
          */
         get: operations['get_notifications'];
@@ -2253,7 +2314,7 @@ interface components {
              * @default {
              *       "MIN_SCORE": 0.01,
              *       "MAX_NUMB_OF_CHUNKS": 30,
-             *       "MAX_CONCURRENT_REQUESTS": 64,
+             *       "MAX_CONCURRENT_REQUESTS": 256,
              *       "MODEL_NAME": "Qwen/Qwen3-Reranker-0.6B",
              *       "API_TYPE": "remote",
              *       "RETRIEVAL_INSTRUCTION": "Judge whether the passage contains the specific facts, figures, names, or references mentioned in the query. Only answer yes if the passage directly contains these details"
@@ -2279,7 +2340,7 @@ interface components {
              *       "MODEL_NAME": "Qwen/Qwen3-Embedding-0.6B",
              *       "API_TYPE": "remote",
              *       "BATCH_SIZE": 128,
-             *       "MAX_CONCURRENT_REQUESTS": 64,
+             *       "MAX_CONCURRENT_REQUESTS": 256,
              *       "DOCUMENT_PREFIX": "",
              *       "QUERY_PREFIX": "Instruct: Represent the user search query for retrieving relevant documents.\nQuery:"
              *     }
@@ -3194,6 +3255,8 @@ interface components {
             file_name?: string | null;
             /** Status */
             status?: string | null;
+            /** Error Message */
+            error_message?: string | null;
             /** N Pages */
             n_pages?: number | null;
             /** N Chunks */
@@ -3309,7 +3372,7 @@ interface components {
             content?: string | null;
             /**
              * Folder
-             * @description Logical folder path (URL safe)
+             * @description Logical folder path — preserved as-is for e-discovery (Unicode, spaces allowed)
              */
             folder?: string | null;
             /**
@@ -3439,8 +3502,8 @@ interface components {
             BATCH_SIZE: number;
             /**
              * Max Concurrent Requests
-             * @description Adjust concurrency level as needed.
-             * @default 64
+             * @description Deployment-wide in-flight embedder requests — sized for ~5 replicas * ~50 concurrent each.
+             * @default 256
              */
             MAX_CONCURRENT_REQUESTS: number;
             /**
@@ -4762,6 +4825,8 @@ interface components {
             storage_gb: components['schemas']['QuotaUsage'];
             ai_credits: components['schemas']['QuotaUsage'];
             collaborators: components['schemas']['QuotaUsage'];
+            /** Budget Reset At */
+            budget_reset_at?: number | null;
         };
         /**
          * ProjectResponse
@@ -5066,8 +5131,8 @@ interface components {
             MAX_NUMB_OF_CHUNKS: number;
             /**
              * Max Concurrent Requests
-             * @description Maximum number of concurrent reranking requests.
-             * @default 64
+             * @description Deployment-wide in-flight reranker requests — sized for ~5 replicas * ~50 concurrent each.
+             * @default 256
              */
             MAX_CONCURRENT_REQUESTS: number;
             /**
@@ -8381,7 +8446,12 @@ interface operations {
     };
     list_documents: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Optional page size. Omit to return every document in the workspace (the default — the web UI's sort/search/filter is client-side and needs the full list). Set when paging through huge workspaces from a CLI. */
+                limit?: number | null;
+                /** @description Optional offset for pagination. Requires a stable id-ordered scan. */
+                offset?: number | null;
+            };
             header?: never;
             path?: never;
             cookie?: never;
@@ -8397,6 +8467,15 @@ interface operations {
                     'application/json': components['schemas']['DocResponse'][];
                 };
             };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HTTPValidationError'];
+                };
+            };
         };
     };
     get_similar_documents: {
@@ -8638,7 +8717,7 @@ interface operations {
                 wp_type?: string | null;
                 /** @description Tag to link the document to */
                 tag_ext_id?: string | null;
-                /** @description Optional logical folder path (URL safe) */
+                /** @description Optional logical folder path (preserved as-is for e-discovery) */
                 folder?: string | null;
             };
             header?: never;
@@ -9249,6 +9328,28 @@ interface operations {
             };
         };
     };
+    get_metrics: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+    };
     list_tags: {
         parameters: {
             query?: never;
@@ -9390,7 +9491,12 @@ interface operations {
     };
     get_notifications: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Maximum number of notifications to return, newest first. Defaults to 100 — almost everyone only cares about the latest. Increase or page via offset to walk further back in history. */
+                limit?: number;
+                /** @description Number of notifications to skip from the newest, for paging. */
+                offset?: number;
+            };
             header?: never;
             path?: never;
             cookie?: never;
@@ -9406,6 +9512,15 @@ interface operations {
                     'application/json': components['schemas']['NotificationResponse'][];
                 };
             };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HTTPValidationError'];
+                };
+            };
         };
     };
     send_messages: {

package/dist/index.d.ts

@@ -726,7 +726,11 @@ interface paths {
         };
         /**
          * List Documents
-         * @description List all documents in the current workspace.
+         * @description List documents in the current workspace.
+         *
+         *     By default returns all documents (no pagination) since the frontend needs
+         *     the full set for client-side sort/search/filter. Pass ``limit``/``offset``
+         *     to opt into pagination — useful for the CLI when streaming a workspace.
          */
         get: operations['list_documents'];
         put?: never;
@@ -794,8 +798,17 @@ interface paths {
          * @description Update one or more documents.
          *
          *     Special status handling:
-         *     - status="processing": Smart reprocess - reindexes if final.pklenc exists, else full re-parse.
-         *       Skips if doc was updated < 10 min ago (prevents duplicate submissions).
+         *     - status="processing": Smart reprocess — reindexes if final.pklenc exists in MinIO
+         *       (regardless of current doc.status), else full re-parse from the original file.
+         *       Skips if a fresh Redis task already exists for the doc (< 10 min old).
+         *
+         *     Batch behavior: the request handler validates + commits ORM field updates
+         *     synchronously, then hands the reprocess work off to a FastAPI background task
+         *     (dispatch_batch_reprocess). The response returns as soon as the background task
+         *     is scheduled, so a single user asking to reprocess 1000+ docs does not block
+         *     the event loop or tie up an HTTP worker. The background dispatcher fans out
+         *     requeue_document_processing calls bounded by the existing deployment-wide
+         *     _indexing_semaphore to keep other users responsive.
          */
         patch: operations['update_documents'];
         trace?: never;
@@ -1027,7 +1040,26 @@ interface paths {
         };
         /**
          * Get Threads With Histories
-         * @description Retrieve all conversation threads (leaf messages and their histories) for a given conversation external ID.
+         * @description Retrieve all conversation threads (leaf messages and their histories).
+         *
+         *     Performance notes
+         *     -----------------
+         *     This endpoint used to issue 3+ DB round-trips per message in every
+         *     history (user_ext_id, config_ext_id, parent_ext_id) and serially decrypt
+         *     each message's tools blob on the event loop. For a conversation with N
+         *     forks of M messages each that's O(N*M) round-trips. The rewrite is
+         *     O(forks) DB calls plus three constant-count batch queries:
+         *
+         *       1. ``get_threads`` to find leaf message ids
+         *       2. one ``get_conversation_history`` recursive CTE per leaf
+         *       3. one batched user-ext-id query (across every message in every fork)
+         *       4. one batched configuration-ext-id query
+         *       5. one ``asyncio.gather`` over ``decrypt_tools_async`` so blobs decrypt
+         *          in parallel on worker threads instead of one-at-a-time on the loop
+         *
+         *     Parent message ext_ids are read off the already-fetched message set —
+         *     parents are by definition ancestors of leaves, so they're always in the
+         *     history we just loaded. No extra query.
          */
         get: operations['get_conversation_threads'];
         put?: never;
@@ -1272,6 +1304,35 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/v1/health/metrics': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get Metrics
+         * @description Live operational metrics for this instance (developer-only).
+         *
+         *     Returns a structured snapshot of DB pool utilisation, in-process
+         *     semaphores (embedder, reranker, indexing, qdrant, doctag_llm, etc.),
+         *     Redis queue backpressure for this deployment, and the current
+         *     asyncio task count. Same data the periodic concurrency_monitor
+         *     logger emits, but as JSON for dashboards / probes / tests.
+         *
+         *     Gated to developer accounts because the payload exposes internal
+         *     pool sizes and saturation — useful for recon if leaked to end users.
+         */
+        get: operations['get_metrics'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/v1/tag/list': {
         parameters: {
             query?: never;
@@ -1373,10 +1434,10 @@ interface paths {
         };
         /**
          * Get Notifications
-         * @description Retrieve all notifications for the current user.
+         * @description Retrieve notifications for the current user, newest first.
          *
-         *     Returns notifications ordered by most recent first.
-         *     Bilateral model: user sees notifications they sent OR received.
+         *     Bilateral model: user sees notifications they sent OR received. Capped at
+         *     ``limit`` (default 100) so the response stays small for chatty users.
          *     Use POST /notifications/read to mark specific notifications as read.
          */
         get: operations['get_notifications'];
@@ -2253,7 +2314,7 @@ interface components {
              * @default {
              *       "MIN_SCORE": 0.01,
              *       "MAX_NUMB_OF_CHUNKS": 30,
-             *       "MAX_CONCURRENT_REQUESTS": 64,
+             *       "MAX_CONCURRENT_REQUESTS": 256,
              *       "MODEL_NAME": "Qwen/Qwen3-Reranker-0.6B",
              *       "API_TYPE": "remote",
              *       "RETRIEVAL_INSTRUCTION": "Judge whether the passage contains the specific facts, figures, names, or references mentioned in the query. Only answer yes if the passage directly contains these details"
@@ -2279,7 +2340,7 @@ interface components {
              *       "MODEL_NAME": "Qwen/Qwen3-Embedding-0.6B",
              *       "API_TYPE": "remote",
              *       "BATCH_SIZE": 128,
-             *       "MAX_CONCURRENT_REQUESTS": 64,
+             *       "MAX_CONCURRENT_REQUESTS": 256,
              *       "DOCUMENT_PREFIX": "",
              *       "QUERY_PREFIX": "Instruct: Represent the user search query for retrieving relevant documents.\nQuery:"
              *     }
@@ -3194,6 +3255,8 @@ interface components {
             file_name?: string | null;
             /** Status */
             status?: string | null;
+            /** Error Message */
+            error_message?: string | null;
             /** N Pages */
             n_pages?: number | null;
             /** N Chunks */
@@ -3309,7 +3372,7 @@ interface components {
             content?: string | null;
             /**
              * Folder
-             * @description Logical folder path (URL safe)
+             * @description Logical folder path — preserved as-is for e-discovery (Unicode, spaces allowed)
              */
             folder?: string | null;
             /**
@@ -3439,8 +3502,8 @@ interface components {
             BATCH_SIZE: number;
             /**
              * Max Concurrent Requests
-             * @description Adjust concurrency level as needed.
-             * @default 64
+             * @description Deployment-wide in-flight embedder requests — sized for ~5 replicas * ~50 concurrent each.
+             * @default 256
              */
             MAX_CONCURRENT_REQUESTS: number;
             /**
@@ -4762,6 +4825,8 @@ interface components {
             storage_gb: components['schemas']['QuotaUsage'];
             ai_credits: components['schemas']['QuotaUsage'];
             collaborators: components['schemas']['QuotaUsage'];
+            /** Budget Reset At */
+            budget_reset_at?: number | null;
         };
         /**
          * ProjectResponse
@@ -5066,8 +5131,8 @@ interface components {
             MAX_NUMB_OF_CHUNKS: number;
             /**
              * Max Concurrent Requests
-             * @description Maximum number of concurrent reranking requests.
-             * @default 64
+             * @description Deployment-wide in-flight reranker requests — sized for ~5 replicas * ~50 concurrent each.
+             * @default 256
              */
             MAX_CONCURRENT_REQUESTS: number;
             /**
@@ -8381,7 +8446,12 @@ interface operations {
     };
     list_documents: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Optional page size. Omit to return every document in the workspace (the default — the web UI's sort/search/filter is client-side and needs the full list). Set when paging through huge workspaces from a CLI. */
+                limit?: number | null;
+                /** @description Optional offset for pagination. Requires a stable id-ordered scan. */
+                offset?: number | null;
+            };
             header?: never;
             path?: never;
             cookie?: never;
@@ -8397,6 +8467,15 @@ interface operations {
                     'application/json': components['schemas']['DocResponse'][];
                 };
             };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HTTPValidationError'];
+                };
+            };
         };
     };
     get_similar_documents: {
@@ -8638,7 +8717,7 @@ interface operations {
                 wp_type?: string | null;
                 /** @description Tag to link the document to */
                 tag_ext_id?: string | null;
-                /** @description Optional logical folder path (URL safe) */
+                /** @description Optional logical folder path (preserved as-is for e-discovery) */
                 folder?: string | null;
             };
             header?: never;
@@ -9249,6 +9328,28 @@ interface operations {
             };
         };
     };
+    get_metrics: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+    };
     list_tags: {
         parameters: {
             query?: never;
@@ -9390,7 +9491,12 @@ interface operations {
     };
     get_notifications: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Maximum number of notifications to return, newest first. Defaults to 100 — almost everyone only cares about the latest. Increase or page via offset to walk further back in history. */
+                limit?: number;
+                /** @description Number of notifications to skip from the newest, for paging. */
+                offset?: number;
+            };
             header?: never;
             path?: never;
             cookie?: never;
@@ -9406,6 +9512,15 @@ interface operations {
                     'application/json': components['schemas']['NotificationResponse'][];
                 };
             };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HTTPValidationError'];
+                };
+            };
         };
     };
     send_messages: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbidocs/client",
-  "version": "0.3.29",
+  "version": "0.3.31",
   "description": "TypeScript SDK for the ARBI API — zero-knowledge auth, E2E encryption, and type-safe REST client",
   "type": "module",
   "main": "dist/index.cjs",