@arke-institute/sdk 3.6.4 → 3.6.9

package/dist/generated/index.d.cts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-02-11T22:34:10.645Z
+ * Generated: 2026-02-16T21:35:43.532Z
  */
 type paths = {
     "/ops-reference": {
@@ -931,6 +931,25 @@ type paths = {
          * Create a new collection
          * @description Creates a collection with the authenticated user as owner.
          *
+         *     **Default Roles:**
+         *
+         *     By default (`use_roles_default: true`), collections include these standard roles:
+         *     - `owner`: Full control including collection management
+         *     - `editor`: Can modify entities but not collection settings
+         *     - `viewer`: Read-only access
+         *     - `public`: Public read access (`*:view`)
+         *
+         *     **Customizing Roles:**
+         *
+         *     Pass custom `roles` to override specific defaults while keeping others. For example, to make entities publicly invokable (for agents):
+         *     ```json
+         *     { "roles": { "public": ["*:view", "*:invoke"] } }
+         *     ```
+         *
+         *     Set `use_roles_default: false` to define all roles from scratch.
+         *
+         *     **Platform Requirement:** The `public` role with `*:view` is always automatically ensured, guaranteeing all collections are publicly readable.
+         *
          *     ---
          *     **Permission:** `collection:create`
          *     **Auth:** required
@@ -1981,13 +2000,13 @@ type paths = {
         };
         /**
          * List entities in a collection
-         * @description Returns entities belonging to this collection from the graph database.
+         * @description Returns entities belonging to this collection.
          *
          *     Supports pagination and optional type filtering. Results are ordered by creation date (newest first).
          *
          *     **Expansion Modes:**
          *
-         *     By default, returns lightweight summaries from GraphDB (pi, type, label, timestamps).
+         *     By default, returns lightweight summaries (pi, type, label, timestamps).
          *
          *     Use the `expand` parameter to hydrate entity data from storage:
          *
@@ -2005,6 +2024,7 @@ type paths = {
             parameters: {
                 query?: {
                     type?: string;
+                    filter?: string;
                     limit?: number;
                     offset?: number | null;
                     expand?: "preview" | "full";
@@ -2055,7 +2075,7 @@ type paths = {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description GraphDB service unavailable */
+                /** @description Collection index service unavailable */
                 503: {
                     headers: {
                         [name: string]: unknown;
@@ -7059,8 +7079,8 @@ type paths = {
             requestBody?: {
                 content: {
                     "application/json": {
-                        /** @description Collection PI to find similar collections for */
-                        pi: string;
+                        /** @description Collection ID to find similar collections for */
+                        id: string;
                         /**
                          * @description Maximum results to return
                          * @default 10
@@ -7089,7 +7109,7 @@ type paths = {
                     content: {
                         "application/json": {
                             results: {
-                                pi: string;
+                                id: string;
                                 label: string;
                                 score: number;
                                 created_at?: string;
@@ -7098,7 +7118,7 @@ type paths = {
                                 entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
-                                source_pi: string;
+                                source_id: string;
                                 result_count: number;
                                 cached?: boolean;
                                 cached_at?: string;
@@ -7213,10 +7233,10 @@ type paths = {
             requestBody?: {
                 content: {
                     "application/json": {
-                        /** @description Entity PI to find similar items for */
-                        pi: string;
-                        /** @description Entity's collection PI */
-                        collection_pi: string;
+                        /** @description Entity ID to find similar items for */
+                        id: string;
+                        /** @description Entity's collection ID */
+                        collection_id: string;
                         /**
                          * @description Maximum results to return
                          * @default 20
@@ -7260,10 +7280,10 @@ type paths = {
                     content: {
                         "application/json": {
                             results: {
-                                pi: string;
+                                id: string;
                                 type: string;
                                 label: string;
-                                collection_pi: string | null;
+                                collection_id: string | null;
                                 score: number;
                                 created_at?: string;
                                 updated_at?: string;
@@ -7271,7 +7291,7 @@ type paths = {
                                 entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
-                                source_pi: string;
+                                source_id: string;
                                 collections_searched: number;
                                 result_count: number;
                                 cached?: boolean;
@@ -7393,6 +7413,56 @@ type paths = {
                         limit?: number;
                         /** @description Filter by collection types */
                         types?: string[];
+                        /**
+                         * @description Filter by indexed metadata properties.
+                         *
+                         *     **Filterable Properties:**
+                         *     Only underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.
+                         *
+                         *     **Operators:**
+                         *     | Operator | Description | Example |
+                         *     |----------|-------------|---------|
+                         *     | `$eq` | Equals | `{ "_year": { "$eq": 1905 } }` |
+                         *     | `$ne` | Not equals | `{ "_class": { "$ne": "draft" } }` |
+                         *     | `$gt` | Greater than | `{ "_year": { "$gt": 1900 } }` |
+                         *     | `$gte` | Greater than or equal | `{ "_year": { "$gte": 1900 } }` |
+                         *     | `$lt` | Less than | `{ "_year": { "$lt": 2000 } }` |
+                         *     | `$lte` | Less than or equal | `{ "_year": { "$lte": 2000 } }` |
+                         *     | `$in` | In array | `{ "_class": { "$in": ["letter", "memo"] } }` |
+                         *     | `$nin` | Not in array | `{ "_class": { "$nin": ["draft"] } }` |
+                         *     | `$exists` | Property exists | `{ "_ocr_text": { "$exists": true } }` |
+                         *
+                         *     **Logical Operators:**
+                         *     | Operator | Description | Example |
+                         *     |----------|-------------|---------|
+                         *     | `$and` | All conditions must match | `{ "$and": [{ "_year": { "$gt": 1900 } }, { "_year": { "$lt": 2000 } }] }` |
+                         *     | `$or` | Any condition must match | `{ "$or": [{ "_class": "letter" }, { "_class": "memo" }] }` |
+                         *
+                         *     **Built-in Fields (always available):**
+                         *     - `type` - Entity type
+                         *     - `created_at` - ISO timestamp string
+                         *     - `updated_at` - ISO timestamp string
+                         *
+                         *     **Example - Find letters from 1800-1900:**
+                         *     ```json
+                         *     {
+                         *       "$and": [
+                         *         { "type": { "$eq": "letter" } },
+                         *         { "_year": { "$gte": 1800 } },
+                         *         { "_year": { "$lte": 1900 } }
+                         *       ]
+                         *     }
+                         *     ```
+                         * @example {
+                         *       "_year": {
+                         *         "$gt": 1800
+                         *       },
+                         *       "type": "letter"
+                         *     }
+                         */
+                        filter?: {
+                            [key: string]: unknown;
+                        };
                         /**
                          * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
                          * @example preview
@@ -7411,7 +7481,7 @@ type paths = {
                     content: {
                         "application/json": {
                             results: {
-                                pi: string;
+                                id: string;
                                 label: string;
                                 type: string;
                                 score: number;
@@ -7525,6 +7595,56 @@ type paths = {
                          * @default 10
                          */
                         limit?: number;
+                        /**
+                         * @description Filter by indexed metadata properties.
+                         *
+                         *     **Filterable Properties:**
+                         *     Only underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.
+                         *
+                         *     **Operators:**
+                         *     | Operator | Description | Example |
+                         *     |----------|-------------|---------|
+                         *     | `$eq` | Equals | `{ "_year": { "$eq": 1905 } }` |
+                         *     | `$ne` | Not equals | `{ "_class": { "$ne": "draft" } }` |
+                         *     | `$gt` | Greater than | `{ "_year": { "$gt": 1900 } }` |
+                         *     | `$gte` | Greater than or equal | `{ "_year": { "$gte": 1900 } }` |
+                         *     | `$lt` | Less than | `{ "_year": { "$lt": 2000 } }` |
+                         *     | `$lte` | Less than or equal | `{ "_year": { "$lte": 2000 } }` |
+                         *     | `$in` | In array | `{ "_class": { "$in": ["letter", "memo"] } }` |
+                         *     | `$nin` | Not in array | `{ "_class": { "$nin": ["draft"] } }` |
+                         *     | `$exists` | Property exists | `{ "_ocr_text": { "$exists": true } }` |
+                         *
+                         *     **Logical Operators:**
+                         *     | Operator | Description | Example |
+                         *     |----------|-------------|---------|
+                         *     | `$and` | All conditions must match | `{ "$and": [{ "_year": { "$gt": 1900 } }, { "_year": { "$lt": 2000 } }] }` |
+                         *     | `$or` | Any condition must match | `{ "$or": [{ "_class": "letter" }, { "_class": "memo" }] }` |
+                         *
+                         *     **Built-in Fields (always available):**
+                         *     - `type` - Entity type
+                         *     - `created_at` - ISO timestamp string
+                         *     - `updated_at` - ISO timestamp string
+                         *
+                         *     **Example - Find letters from 1800-1900:**
+                         *     ```json
+                         *     {
+                         *       "$and": [
+                         *         { "type": { "$eq": "letter" } },
+                         *         { "_year": { "$gte": 1800 } },
+                         *         { "_year": { "$lte": 1900 } }
+                         *       ]
+                         *     }
+                         *     ```
+                         * @example {
+                         *       "_year": {
+                         *         "$gt": 1800
+                         *       },
+                         *       "type": "letter"
+                         *     }
+                         */
+                        filter?: {
+                            [key: string]: unknown;
+                        };
                         /**
                          * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
                          * @example preview
@@ -7549,10 +7669,10 @@ type paths = {
                     content: {
                         "application/json": {
                             results: {
-                                pi: string;
+                                id: string;
                                 label: string;
                                 score: number;
-                                collection_pi: string | null;
+                                collection_id: string | null;
                                 status?: string;
                                 created_at?: string;
                                 updated_at?: string;
@@ -7629,7 +7749,7 @@ type paths = {
          * Search entities within collection(s)
          * @description Search for entities within one or more collections using semantic text search.
          *
-         *     Provide either `collection_pi` for a single collection or `collection_pis` for multiple collections (searched in parallel).
+         *     Provide either `collection_pi` for a single collection or `collection_ids` for multiple collections (searched in parallel).
          *
          *     Use `per_collection_limit` to ensure result diversity when searching multiple collections.
          *
@@ -7658,10 +7778,10 @@ type paths = {
             requestBody?: {
                 content: {
                     "application/json": {
-                        /** @description Single collection PI to search within */
-                        collection_pi?: string;
-                        /** @description Multiple collection PIs to search (max 20) */
-                        collection_pis?: string[];
+                        /** @description Single collection ID to search within */
+                        collection_id?: string;
+                        /** @description Multiple collection IDs to search (max 20) */
+                        collection_ids?: string[];
                         /** @description Search query text */
                         query: string;
                         /**
@@ -7671,6 +7791,56 @@ type paths = {
                         limit?: number;
                         /** @description Filter by entity types */
                         types?: string[];
+                        /**
+                         * @description Filter by indexed metadata properties.
+                         *
+                         *     **Filterable Properties:**
+                         *     Only underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.
+                         *
+                         *     **Operators:**
+                         *     | Operator | Description | Example |
+                         *     |----------|-------------|---------|
+                         *     | `$eq` | Equals | `{ "_year": { "$eq": 1905 } }` |
+                         *     | `$ne` | Not equals | `{ "_class": { "$ne": "draft" } }` |
+                         *     | `$gt` | Greater than | `{ "_year": { "$gt": 1900 } }` |
+                         *     | `$gte` | Greater than or equal | `{ "_year": { "$gte": 1900 } }` |
+                         *     | `$lt` | Less than | `{ "_year": { "$lt": 2000 } }` |
+                         *     | `$lte` | Less than or equal | `{ "_year": { "$lte": 2000 } }` |
+                         *     | `$in` | In array | `{ "_class": { "$in": ["letter", "memo"] } }` |
+                         *     | `$nin` | Not in array | `{ "_class": { "$nin": ["draft"] } }` |
+                         *     | `$exists` | Property exists | `{ "_ocr_text": { "$exists": true } }` |
+                         *
+                         *     **Logical Operators:**
+                         *     | Operator | Description | Example |
+                         *     |----------|-------------|---------|
+                         *     | `$and` | All conditions must match | `{ "$and": [{ "_year": { "$gt": 1900 } }, { "_year": { "$lt": 2000 } }] }` |
+                         *     | `$or` | Any condition must match | `{ "$or": [{ "_class": "letter" }, { "_class": "memo" }] }` |
+                         *
+                         *     **Built-in Fields (always available):**
+                         *     - `type` - Entity type
+                         *     - `created_at` - ISO timestamp string
+                         *     - `updated_at` - ISO timestamp string
+                         *
+                         *     **Example - Find letters from 1800-1900:**
+                         *     ```json
+                         *     {
+                         *       "$and": [
+                         *         { "type": { "$eq": "letter" } },
+                         *         { "_year": { "$gte": 1800 } },
+                         *         { "_year": { "$lte": 1900 } }
+                         *       ]
+                         *     }
+                         *     ```
+                         * @example {
+                         *       "_year": {
+                         *         "$gt": 1800
+                         *       },
+                         *       "type": "letter"
+                         *     }
+                         */
+                        filter?: {
+                            [key: string]: unknown;
+                        };
                         /** @description Max results per collection for diversity */
                         per_collection_limit?: number;
                         /**
@@ -7691,18 +7861,18 @@ type paths = {
                     content: {
                         "application/json": {
                             results: {
-                                pi: string;
+                                id: string;
                                 label: string;
                                 type: string;
                                 score: number;
-                                collection_pi: string;
+                                collection_id: string;
                                 created_at?: string;
                                 updated_at?: string;
                                 entity_preview?: components["schemas"]["EntityPreview"] & unknown;
                                 entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
-                                collection_pis: string[];
+                                collection_ids: string[];
                                 query: string;
                                 collections_searched: number;
                                 result_count: number;
@@ -7814,6 +7984,56 @@ type paths = {
                         limit?: number;
                         /** @description Filter by entity types */
                         types?: string[];
+                        /**
+                         * @description Filter by indexed metadata properties.
+                         *
+                         *     **Filterable Properties:**
+                         *     Only underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.
+                         *
+                         *     **Operators:**
+                         *     | Operator | Description | Example |
+                         *     |----------|-------------|---------|
+                         *     | `$eq` | Equals | `{ "_year": { "$eq": 1905 } }` |
+                         *     | `$ne` | Not equals | `{ "_class": { "$ne": "draft" } }` |
+                         *     | `$gt` | Greater than | `{ "_year": { "$gt": 1900 } }` |
+                         *     | `$gte` | Greater than or equal | `{ "_year": { "$gte": 1900 } }` |
+                         *     | `$lt` | Less than | `{ "_year": { "$lt": 2000 } }` |
+                         *     | `$lte` | Less than or equal | `{ "_year": { "$lte": 2000 } }` |
+                         *     | `$in` | In array | `{ "_class": { "$in": ["letter", "memo"] } }` |
+                         *     | `$nin` | Not in array | `{ "_class": { "$nin": ["draft"] } }` |
+                         *     | `$exists` | Property exists | `{ "_ocr_text": { "$exists": true } }` |
+                         *
+                         *     **Logical Operators:**
+                         *     | Operator | Description | Example |
+                         *     |----------|-------------|---------|
+                         *     | `$and` | All conditions must match | `{ "$and": [{ "_year": { "$gt": 1900 } }, { "_year": { "$lt": 2000 } }] }` |
+                         *     | `$or` | Any condition must match | `{ "$or": [{ "_class": "letter" }, { "_class": "memo" }] }` |
+                         *
+                         *     **Built-in Fields (always available):**
+                         *     - `type` - Entity type
+                         *     - `created_at` - ISO timestamp string
+                         *     - `updated_at` - ISO timestamp string
+                         *
+                         *     **Example - Find letters from 1800-1900:**
+                         *     ```json
+                         *     {
+                         *       "$and": [
+                         *         { "type": { "$eq": "letter" } },
+                         *         { "_year": { "$gte": 1800 } },
+                         *         { "_year": { "$lte": 1900 } }
+                         *       ]
+                         *     }
+                         *     ```
+                         * @example {
+                         *       "_year": {
+                         *         "$gt": 1800
+                         *       },
+                         *       "type": "letter"
+                         *     }
+                         */
+                        filter?: {
+                            [key: string]: unknown;
+                        };
                         /**
                          * @description Number of collections to search
                          * @default 10
@@ -7842,11 +8062,11 @@ type paths = {
                     content: {
                         "application/json": {
                             results: {
-                                pi: string;
+                                id: string;
                                 label: string;
                                 type: string;
                                 score: number;
-                                collection_pi: string;
+                                collection_id: string;
                                 created_at?: string;
                                 updated_at?: string;
                                 entity_preview?: components["schemas"]["EntityPreview"] & unknown;
@@ -8579,10 +8799,10 @@ type components = {
              */
             type: "user";
             /**
-             * @description User entity PI (persistent identifier)
+             * @description User entity ID
              * @example 01J1SHMAE10000000000000000
              */
-            pi: string;
+            id: string;
             /**
              * @description How this identity was authenticated
              * @example jwt
@@ -8623,10 +8843,10 @@ type components = {
              */
             type: "agent";
             /**
-             * @description Agent entity PI (persistent identifier)
+             * @description Agent entity ID
              * @example 01J1AGENTID000000000000000
              */
-            pi: string;
+            id: string;
             /**
              * @description How this identity was authenticated
              * @example api_key
@@ -8634,10 +8854,10 @@ type components = {
              */
             auth_method: "api_key";
             /**
-             * @description Entity PI of the agent owner
+             * @description Entity ID of the agent owner
              * @example 01J1OWNERID0000000000000000
              */
-            owner_pi: string;
+            owner_id: string;
             /**
              * @description API key prefix
              * @example ak_xyz9
@@ -8841,10 +9061,10 @@ type components = {
         };
         UserCollectionItem: {
             /**
-             * @description Collection persistent identifier
+             * @description Collection ID
              * @example 01JCOLLECTION123456789AB
              */
-            pi: string;
+            id: string;
             /**
              * @description Collection label/name
              * @example My Research Collection
@@ -8887,7 +9107,7 @@ type components = {
          *       "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
          *       "type": "file",
          *       "label": "Research Paper.pdf",
-         *       "collection_pi": "01JCOLLECTION123456789AB",
+         *       "collection_id": "01JCOLLECTION123456789AB",
          *       "description_preview": "A comprehensive study on distributed systems architecture...",
          *       "created_at": "2026-01-12T00:00:00.000Z",
          *       "updated_at": "2026-01-12T10:30:00.000Z"
@@ -8913,7 +9133,7 @@ type components = {
              * @description Collection ID this entity belongs to
              * @example 01JCOLLECTION123456789ABCD
              */
-            collection_pi?: string;
+            collection_id?: string;
             /**
              * @description Truncated description (max 200 chars + "...")
              * @example This document contains research findings from the 2025 study on entity management systems. It covers key architectural decisions and performance benchmarks...
@@ -8937,10 +9157,10 @@ type components = {
         };
         SearchResultItem: {
             /**
-             * @description Entity persistent identifier
+             * @description Entity ID
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            pi: string;
+            id: string;
             /**
              * @description Entity type
              * @example file
@@ -8955,7 +9175,7 @@ type components = {
              * @description Collection this entity belongs to (null for public-domain)
              * @example 01JCOLLECTION123456789AB
              */
-            collection_pi: string | null;
+            collection_id: string | null;
             /**
              * @description Relevance score (0-1, higher is better)
              * @example 0.87
@@ -9068,26 +9288,17 @@ type components = {
              */
             display_image_url?: string;
             /**
-             * @description Custom role definitions (defaults to owner/editor/viewer/public)
+             * @description Whether to merge with default roles (true) or use only provided roles (false). Public role with *:view is always ensured.
+             * @default true
+             * @example true
+             */
+            use_roles_default: boolean;
+            /**
+             * @description Role definitions. When use_roles_default is true (default), these merge with defaults. When false, these replace defaults entirely.
              * @example {
-             *       "captain": [
-             *         "*:view",
-             *         "*:update",
-             *         "*:create",
-             *         "collection:manage"
-             *       ],
-             *       "harpooner": [
-             *         "*:view",
-             *         "*:update",
-             *         "*:create"
-             *       ],
-             *       "crew": [
-             *         "*:view",
-             *         "entity:create"
-             *       ],
              *       "public": [
-             *         "entity:view",
-             *         "collection:view"
+             *         "*:view",
+             *         "*:invoke"
              *       ]
              *     }
              */
@@ -9414,8 +9625,8 @@ type components = {
             entity_id: string;
         };
         CollectionEntitySummary: {
-            /** @description Entity persistent identifier */
-            pi: string;
+            /** @description Entity ID */
+            id: string;
             /**
              * @description Entity type
              * @example document
@@ -9616,6 +9827,11 @@ type components = {
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
             collection?: string;
+            /**
+             * @description Wait for collection index update before returning. Use when checking for duplicates immediately after creation. Adds ~1-5ms latency per collection.
+             * @default false
+             */
+            sync_index: boolean;
         };
         BatchCreateSuccess: {
             /** @enum {boolean} */
@@ -9793,6 +10009,11 @@ type components = {
                  */
                 peer?: string;
             }[];
+            /**
+             * @description Wait for collection index update before returning. Use when checking index immediately after update.
+             * @default false
+             */
+            sync_index: boolean;
         };
         EntityDeletedResponse: {
             /**
@@ -9837,6 +10058,11 @@ type components = {
              * @example Duplicate entry
              */
             reason?: string;
+            /**
+             * @description Wait for collection index removal before returning. Use when checking index immediately after deletion.
+             * @default false
+             */
+            sync_index: boolean;
         };
         CascadeDeletedEntity: {
             /**
@@ -9981,7 +10207,7 @@ type components = {
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            pi: string;
+            id: string;
             /** @description Entity label */
             label: string;
             /** @description Entity type */
@@ -11320,7 +11546,7 @@ type components = {
              * @example {
              *       "extract": {
              *         "klados": {
-             *           "pi": "01KKLADOSA12345678901234",
+             *           "id": "01KKLADOSA12345678901234",
              *           "type": "klados"
              *         },
              *         "then": {
@@ -11329,7 +11555,7 @@ type components = {
              *       },
              *       "summarize": {
              *         "klados": {
-             *           "pi": "01KKLADOSB12345678901234",
+             *           "id": "01KKLADOSB12345678901234",
              *           "type": "klados"
              *         },
              *         "then": {
@@ -11344,12 +11570,17 @@ type components = {
                      * KladosRef
                      * @description Reference to the klados entity to invoke for this step
                      * @example {
-                     *       "pi": "01KEXAMPLE123456789012345",
+                     *       "id": "01KEXAMPLE123456789012345",
                      *       "type": "klados",
                      *       "label": "OCR Processor"
                      *     }
                      */
                     klados: {
+                        id: string;
+                        type?: string;
+                        label?: string;
+                        description?: string;
+                    } | {
                         pi: string;
                         type?: string;
                         label?: string;
@@ -11503,7 +11734,7 @@ type components = {
              * @example {
              *       "extract": {
              *         "klados": {
-             *           "pi": "01KKLADOSA12345678901234",
+             *           "id": "01KKLADOSA12345678901234",
              *           "type": "klados"
              *         },
              *         "then": {
@@ -11512,7 +11743,7 @@ type components = {
              *       },
              *       "summarize": {
              *         "klados": {
-             *           "pi": "01KKLADOSB12345678901234",
+             *           "id": "01KKLADOSB12345678901234",
              *           "type": "klados"
              *         },
              *         "then": {
@@ -11527,12 +11758,17 @@ type components = {
                      * KladosRef
                      * @description Reference to the klados entity to invoke for this step
                      * @example {
-                     *       "pi": "01KEXAMPLE123456789012345",
+                     *       "id": "01KEXAMPLE123456789012345",
                      *       "type": "klados",
                      *       "label": "OCR Processor"
                      *     }
                      */
                     klados: {
+                        id: string;
+                        type?: string;
+                        label?: string;
+                        description?: string;
+                    } | {
                         pi: string;
                         type?: string;
                         label?: string;
@@ -11740,7 +11976,7 @@ type components = {
              * @description Entity ID that changed
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            pi: string;
+            entity_id: string;
             /**
              * @description New manifest CID
              * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
@@ -11768,27 +12004,27 @@ type components = {
         };
         /**
          * @example {
-         *       "subject_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *       "subject_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
          *       "subject_label": "Project Folder",
          *       "subject_type": "folder",
          *       "subject_preview": {
          *         "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
          *         "type": "folder",
          *         "label": "Project Folder",
-         *         "collection_pi": "01JCOLLECTION123456789ABCD",
+         *         "collection_id": "01JCOLLECTION123456789ABCD",
          *         "description_preview": "Main project folder containing research documents...",
          *         "created_at": "2025-01-10T08:00:00.000Z",
          *         "updated_at": "2025-01-18T16:45:00.000Z"
          *       },
          *       "predicate": "contains",
-         *       "object_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *       "object_id": "01KE506KZGD8M2P1XK3VNQT4YR",
          *       "object_label": "Research Paper.pdf",
          *       "object_type": "file",
          *       "object_preview": {
          *         "id": "01KE506KZGD8M2P1XK3VNQT4YR",
          *         "type": "file",
          *         "label": "Research Paper.pdf",
-         *         "collection_pi": "01JCOLLECTION123456789ABCD",
+         *         "collection_id": "01JCOLLECTION123456789ABCD",
          *         "description_preview": "Analysis of entity management patterns and best practices...",
          *         "created_at": "2025-01-15T10:00:00.000Z",
          *         "updated_at": "2025-01-20T14:30:00.000Z"
@@ -11800,7 +12036,7 @@ type components = {
              * @description Source entity PI
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            subject_pi: string;
+            subject_id: string;
             /** @description Source entity label */
             subject_label: string;
             /** @description Source entity type */
@@ -11813,7 +12049,7 @@ type components = {
              * @description Target entity PI
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            object_pi: string;
+            object_id: string;
             /** @description Target entity label */
             object_label: string;
             /** @description Target entity type */
@@ -11826,12 +12062,12 @@ type components = {
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            source_pi: string;
+            source_id: string;
             /**
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            target_pi: string;
+            target_id: string;
             /** @description Path length (number of hops) */
             length: number;
             edges: components["schemas"]["PathEdge"][];
@@ -11848,14 +12084,14 @@ type components = {
              *       "01KE4ZY69F9R40E88PK9S0TQRQ"
              *     ]
              */
-            source_pis: string[];
+            source_ids: string[];
             /**
              * @description Target entity PIs
              * @example [
              *       "01KE506KZGD8M2P1XK3VNQT4YR"
              *     ]
              */
-            target_pis: string[];
+            target_ids: string[];
             /**
              * @description Maximum path depth (1-4)
              * @default 4
@@ -11878,8 +12114,8 @@ type components = {
         };
         /**
          * @example {
-         *       "source_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
-         *       "target_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *       "source_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *       "target_id": "01KE506KZGD8M2P1XK3VNQT4YR",
          *       "target_label": "Research Paper.pdf",
          *       "target_type": "file",
          *       "length": 1,
@@ -11888,7 +12124,7 @@ type components = {
          *         "id": "01KE506KZGD8M2P1XK3VNQT4YR",
          *         "type": "file",
          *         "label": "Research Paper.pdf",
-         *         "collection_pi": "01JCOLLECTION123456789ABCD",
+         *         "collection_id": "01JCOLLECTION123456789ABCD",
          *         "description_preview": "Analysis of entity management patterns and best practices...",
          *         "created_at": "2025-01-15T10:00:00.000Z",
          *         "updated_at": "2025-01-20T14:30:00.000Z"
@@ -11900,12 +12136,12 @@ type components = {
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            source_pi: string;
+            source_id: string;
             /**
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            target_pi: string;
+            target_id: string;
             target_label: string;
             target_type: string;
             /** @description Path length (number of hops) */
@@ -11926,7 +12162,7 @@ type components = {
              *       "01KE4ZY69F9R40E88PK9S0TQRQ"
              *     ]
              */
-            source_pis: string[];
+            source_ids: string[];
             /**
              * @description Target entity type to find
              * @example file
@@ -11956,7 +12192,7 @@ type components = {
          * @example {
          *       "direction": "outgoing",
          *       "predicate": "contains",
-         *       "peer_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *       "peer_id": "01KE506KZGD8M2P1XK3VNQT4YR",
          *       "peer_type": "file",
          *       "peer_label": "Research Paper.pdf",
          *       "properties": {},
@@ -11964,7 +12200,7 @@ type components = {
          *         "id": "01KE506KZGD8M2P1XK3VNQT4YR",
          *         "type": "file",
          *         "label": "Research Paper.pdf",
-         *         "collection_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *         "collection_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
          *         "description_preview": "Analysis of entity management patterns and best practices...",
          *         "created_at": "2025-01-15T10:00:00.000Z",
          *         "updated_at": "2025-01-20T14:30:00.000Z"
@@ -11979,7 +12215,7 @@ type components = {
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            peer_pi: string;
+            peer_id: string;
             peer_type: string;
             peer_label: string;
             properties: {
@@ -11990,17 +12226,17 @@ type components = {
         };
         /**
          * @example {
-         *       "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *       "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
          *       "type": "folder",
          *       "label": "Project Folder",
-         *       "collection_pi": "01JCOLLECTION123456789ABCD",
+         *       "collection_id": "01JCOLLECTION123456789ABCD",
          *       "created_at": "2025-01-10T08:00:00.000Z",
          *       "updated_at": "2025-01-18T16:45:00.000Z",
          *       "relationships": [
          *         {
          *           "direction": "outgoing",
          *           "predicate": "contains",
-         *           "peer_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *           "peer_id": "01KE506KZGD8M2P1XK3VNQT4YR",
          *           "peer_type": "file",
          *           "peer_label": "Research Paper.pdf",
          *           "properties": {},
@@ -12008,7 +12244,7 @@ type components = {
          *             "id": "01KE506KZGD8M2P1XK3VNQT4YR",
          *             "type": "file",
          *             "label": "Research Paper.pdf",
-         *             "collection_pi": "01JCOLLECTION123456789ABCD",
+         *             "collection_id": "01JCOLLECTION123456789ABCD",
          *             "description_preview": "Analysis of entity management patterns and best practices...",
          *             "created_at": "2025-01-15T10:00:00.000Z",
          *             "updated_at": "2025-01-20T14:30:00.000Z"
@@ -12022,10 +12258,10 @@ type components = {
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            pi: string;
+            id: string;
             type: string;
             label: string;
-            collection_pi: string | null;
+            collection_id: string | null;
             /** Format: date-time */
             created_at: string;
             /** Format: date-time */
@@ -12074,15 +12310,15 @@ type components = {
                 /**
                  * @description Query result entity with optional expansion data
                  * @example {
-                 *       "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+                 *       "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
                  *       "type": "person",
                  *       "label": "Albert Einstein",
-                 *       "collection_pi": "01JCOLL_RESEARCH",
+                 *       "collection_id": "01JCOLL_RESEARCH",
                  *       "preview_data": {
                  *         "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
                  *         "type": "person",
                  *         "label": "Albert Einstein",
-                 *         "collection_pi": "01JCOLL_RESEARCH",
+                 *         "collection_id": "01JCOLL_RESEARCH",
                  *         "description_preview": "German-born theoretical physicist who developed the theory of relativity...",
                  *         "created_at": "2025-01-15T10:00:00.000Z",
                  *         "updated_at": "2025-01-20T14:30:00.000Z"
@@ -12094,13 +12330,13 @@ type components = {
                      * @description Entity ID (ULID format)
                      * @example 01KDETYWYWM0MJVKM8DK3AEXPY
                      */
-                    pi: string;
+                    id: string;
                     /** @example person */
                     type: string;
                     /** @example Albert Einstein */
                     label: string;
                     /** @example 01JCOLL_RESEARCH */
-                    collection_pi: string | null;
+                    collection_id: string | null;
                     preview_data?: components["schemas"]["EntityPreview"] & unknown;
                     full_entity?: components["schemas"]["EntityResponse"] & unknown;
                 };
@@ -12145,6 +12381,26 @@ type components = {
              * @enum {string}
              */
             expand?: "none" | "preview" | "full";
+            /**
+             * @description Filter by indexed metadata properties during semantic search.
+             *
+             *     Only underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.
+             *
+             *     **Operators:** `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$and`, `$or`
+             *
+             *     **Example - Find letters from the 1800s:**
+             *     ```json
+             *     { "_year": { "$gte": 1800, "$lte": 1899 } }
+             *     ```
+             * @example {
+             *       "_year": {
+             *         "$gt": 1800
+             *       }
+             *     }
+             */
+            filter?: {
+                [key: string]: unknown;
+            };
         };
         MessageTooLargeDetails: {
             /** @enum {string} */
@@ -12308,7 +12564,7 @@ type components = {
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            pi: string;
+            id: string;
             /**
              * @description Entity version number
              * @example 1
@@ -12341,7 +12597,7 @@ type components = {
              * @description Entity ID (ULID format)
              * @example 01KDETYWYWM0MJVKM8DK3AEXPY
              */
-            pi: string;
+            id: string;
             /**
              * @description Entity version number
              * @example 1
@@ -12388,7 +12644,7 @@ type components = {
                  * @description Entity ID (ULID format)
                  * @example 01KDETYWYWM0MJVKM8DK3AEXPY
                  */
-                pi: string;
+                id: string;
                 /**
                  * @description Entity version number
                  * @example 1