mixpeek 0.81.1

package/dist/models/stage-params-attribute-filter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Mixpeek API
+ * This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.
+ *
+ * The version of the OpenAPI document: 0.81.1
+ * Contact: info@mixpeek.com
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { StageDefsFilterOperator } from './stage-defs-filter-operator';
+import type { StageDefsLogicalOperator } from './stage-defs-logical-operator';
+/**
+ * Configuration for filtering documents by attribute conditions.  **Stage Category**: FILTER  **Transformation**: N documents → ≤N documents (subset, same schema)  **Purpose**: Produces a subset of input documents by removing those that don\'t match attribute conditions. Output documents have identical schema to input.  **When to Use**:     - **As First Stage**: To retrieve and filter documents by attributes without semantic search       (e.g., \"get all active products with priority >= 5\"). Fetches up to 1000 documents       per collection from Qdrant, then applies filter conditions.     - **As Subsequent Stage**: To narrow results from previous stages by specific attributes       (status, date range, category, tags). Operates purely on in-memory results.     - When you need to apply business logic filtering (active items, published content)     - Before expensive stages (SORT, APPLY) to reduce processing overhead     - For structured/fast filtering based on document properties  **When NOT to Use**:     - For reordering results (use SORT stages: sort_relevance, sort_attribute)     - For complex semantic filtering (use llm_filter instead)     - For enriching documents with additional data (use APPLY stages)     - For aggregating to single document (use REDUCE stages)  **Operational Behavior**:     - **As First Stage**: Fetches documents directly from Qdrant (up to 1000 per collection)       using scroll API. Supports pre_filters which leverage Qdrant\'s native filtering       (including full-text search with TEXT operator). Results are then filtered in-memory       using the stage\'s filter conditions. This allows attribute_filter to be used as an       initial retrieval stage without requiring a prior search/embedding stage.     - **As Subsequent Stage**: Operates purely on in-memory results from previous stages       (no database queries). This is the typical use case for post-filtering.     - Produces subset of documents (removes non-matching)     - Fast operation (simple condition evaluation)     - Processes documents in batches for memory efficiency     - Supports complex boolean logic (AND/OR/NOT)     - Output schema = Input schema (no schema changes)  **Common Pipeline Position**: FILTER (this stage) → SORT → APPLY  **Important Limitations**:     - When used as first stage, maximum 1000 documents per collection are fetched from Qdrant     - For large collections, consider using semantic_search or other retrieval stages first     - Vectors are not fetched from Qdrant (only payloads) to optimize performance  **Two modes of operation:**  1. **Simple mode** (single condition): Specify `field`, `operator`, and `value` 2. **Boolean mode** (multiple conditions): Specify `conditions` with AND/OR/NOT logic  Both modes support template variables that are evaluated for every document.  Examples:     Simple single condition:         ```json         {             \"field\": \"metadata.status\",             \"operator\": \"eq\",             \"value\": \"active\"         }         ```      Boolean AND:         ```json         {             \"conditions\": {                 \"AND\": [                     {\"field\": \"metadata.status\", \"operator\": \"eq\", \"value\": \"active\"},                     {\"field\": \"metadata.priority\", \"operator\": \"gte\", \"value\": 5}                 ]             }         }         ```      Boolean OR:         ```json         {             \"conditions\": {                 \"OR\": [                     {\"field\": \"metadata.urgent\", \"operator\": \"eq\", \"value\": true},                     {\"field\": \"metadata.priority\", \"operator\": \"gte\", \"value\": 8}                 ]             }         }         ```      Nested boolean logic:         ```json         {             \"conditions\": {                 \"AND\": [                     {\"field\": \"metadata.status\", \"operator\": \"eq\", \"value\": \"active\"},                     {                         \"OR\": [                             {\"field\": \"metadata.category\", \"operator\": \"eq\", \"value\": \"urgent\"},                             {\"field\": \"metadata.category\", \"operator\": \"eq\", \"value\": \"critical\"}                         ]                     }                 ]             }         }         ```
+ * @export
+ * @interface StageParamsAttributeFilter
+ */
+export interface StageParamsAttributeFilter {
+    /**
+     * Dot-delimited field path to evaluate on each document. Supports template variables (e.g. \'{{DOC.metadata.category}}\'). REQUIRED for simple mode. NOT USED when \'conditions\' is specified.
+     * @type {string}
+     * @memberof StageParamsAttributeFilter
+     */
+    'field'?: string;
+    /**
+     * Comparison operator to apply. Supported operators: eq, ne, gt, gte, lt, lte, in, nin, contains, starts_with, ends_with, regex, exists, is_null. REQUIRED for simple mode. NOT USED when \'conditions\' is specified.
+     * @type {StageDefsFilterOperator}
+     * @memberof StageParamsAttributeFilter
+     */
+    'operator'?: StageDefsFilterOperator;
+    /**
+     *
+     * @type {any}
+     * @memberof StageParamsAttributeFilter
+     */
+    'value'?: any;
+    /**
+     * Complex filter conditions using boolean logic (AND/OR/NOT). Use this for combining multiple filter conditions. REQUIRED for boolean mode. Cannot be used with \'field\'/\'operator\'/\'value\'.
+     * @type {StageDefsLogicalOperator}
+     * @memberof StageParamsAttributeFilter
+     */
+    'conditions'?: StageDefsLogicalOperator;
+    /**
+     * Number of documents to evaluate per batch. The executor streams documents through the filter in chunks to avoid large in-memory spikes.
+     * @type {number}
+     * @memberof StageParamsAttributeFilter
+     */
+    'batch_size'?: number;
+    /**
+     * When true, string comparisons are performed case-insensitively where the operator supports it. Applies to both simple and boolean modes.
+     * @type {boolean}
+     * @memberof StageParamsAttributeFilter
+     */
+    'case_insensitive'?: boolean;
+}
+//# sourceMappingURL=stage-params-attribute-filter.d.ts.map

package/dist/models/stage-params-attribute-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-params-attribute-filter.d.ts","sourceRoot":"","sources":["../../models/stage-params-attribute-filter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAG5E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,wBAAwB,CAAC;IACxC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAChC"}

package/dist/models/stage-params-cluster.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Mixpeek API
+ * This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.
+ *
+ * The version of the OpenAPI document: 0.81.1
+ * Contact: info@mixpeek.com
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * Configuration for clustering documents from previous stage results.  Stage Category: REDUCE  Transformation: N documents → K clusters (where K < N typically)  Purpose: Dynamically clusters documents from the pipeline by their embeddings. Unlike group_by which groups by a pre-existing field, cluster discovers natural groupings in the data based on vector similarity.  Performance: Calls clustering inference service. Fast for typical retriever result sets (10-500 documents). For larger datasets, consider using pre-computed clusters with group_by instead.  When to Use:     - Discover themes/topics in search results     - Group semantically similar documents without pre-existing labels     - Analyze patterns in retrieved content     - \"Find the 3 main themes in these results\"     - Auto-categorize search results  When NOT to Use:     - When documents already have cluster/category labels (use group_by)     - For very large result sets (>1000 docs) - use pre-computed clusters     - When you need exact groupings (clustering is approximate)  Output Modes:     - \"clusters\": Returns K cluster summary documents with member lists     - \"labeled\": Returns original N documents with cluster_label added     - \"representatives\": Returns K representative documents (one per cluster)  Common Pipeline Position: FILTER → cluster (this stage) → ENRICH (summarize clusters)  Examples:     - \"Find 3 themes in 60 ads\" → cluster with n_clusters=3     - \"Group similar products\" → cluster with algorithm=hdbscan (auto K)     - \"Discover topics in articles\" → cluster with representatives output
+ * @export
+ * @interface StageParamsCluster
+ */
+export interface StageParamsCluster {
+    /**
+     * Clustering algorithm to use:  - hdbscan: Auto-determines number of clusters, handles noise (DEFAULT, recommended) - kmeans: Fast, requires n_clusters, spherical clusters - dbscan: Density-based, handles noise, requires eps tuning - agglomerative: Hierarchical, good for nested structures - spectral: Graph-based, good for non-convex clusters - gaussian_mixture: Probabilistic, soft cluster assignments  Recommendation: Use \'hdbscan\' for exploratory analysis, \'kmeans\' when you know K.
+     * @type {string}
+     * @memberof StageParamsCluster
+     */
+    'algorithm'?: StageParamsClusterAlgorithmEnum;
+    /**
+     * Number of clusters to create. Required for kmeans, spectral, agglomerative, gaussian_mixture. Ignored for hdbscan and dbscan (auto-determined).  If not specified for algorithms that need it, auto-calculated as min(8, N/10).  Typical values: 3-5 for theme discovery, 5-10 for topic modeling, 10-20 for fine-grained categorization.
+     * @type {number}
+     * @memberof StageParamsCluster
+     */
+    'n_clusters'?: number;
+    /**
+     * Minimum number of documents to form a cluster (HDBSCAN/DBSCAN only).  Lower values = more clusters, may include noise. Higher values = fewer, denser clusters.  Auto-adjusted for small datasets: min(min_cluster_size, N/3). Typical values: 3-5 for small results, 10-20 for large results.
+     * @type {number}
+     * @memberof StageParamsCluster
+     */
+    'min_cluster_size'?: number;
+    /**
+     * Feature URI specifying which embedding to cluster on.  OPTIONAL - if not provided, auto-detects from the upstream feature_search stage. When a feature_search stage runs before cluster, its feature_uri is automatically tracked in the pipeline state and used for clustering.  Use the mixpeek:// URI format:   mixpeek://{extractor}@{version}/{output}  Examples: - \'mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding\' - \'mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\' - \'mixpeek://clip_extractor@v1/image_embedding\'  The feature_uri is resolved to the actual embedding field name on the documents (e.g., \'multimodal_extractor_v1_multimodal_embedding\').  Only specify explicitly if you want to cluster on a different embedding than the one used in the feature_search stage.
+     * @type {string}
+     * @memberof StageParamsCluster
+     */
+    'feature_uri'?: string;
+    /**
+     * How to format the output:  - \'clusters\': Returns K cluster documents, each containing:   - cluster_id: Cluster identifier   - member_count: Number of documents in cluster   - members: List of member documents   - centroid: Cluster center vector   Use for: Theme analysis, cluster summaries  - \'labeled\': Returns original N documents with added fields:   - cluster_id: Assigned cluster   - cluster_score: Distance to centroid (lower = closer)   Use for: Downstream processing with cluster context  - \'representatives\': Returns K documents (one per cluster):   - The document closest to each cluster centroid   Use for: Quick sampling, representative examples
+     * @type {string}
+     * @memberof StageParamsCluster
+     */
+    'output_mode'?: StageParamsClusterOutputModeEnum;
+    /**
+     * Whether to include centroid vectors in output. Useful for downstream similarity comparisons or visualization. Set to False to reduce response size.
+     * @type {boolean}
+     * @memberof StageParamsCluster
+     */
+    'include_centroids'?: boolean;
+    /**
+     * Maximum members to include per cluster in \'clusters\' output mode. Documents are sorted by distance to centroid (closest first). Use to limit response size for large result sets.
+     * @type {number}
+     * @memberof StageParamsCluster
+     */
+    'max_members_per_cluster'?: number;
+}
+export declare const StageParamsClusterAlgorithmEnum: {
+    readonly Kmeans: "kmeans";
+    readonly Hdbscan: "hdbscan";
+    readonly Dbscan: "dbscan";
+    readonly Agglomerative: "agglomerative";
+    readonly Spectral: "spectral";
+    readonly GaussianMixture: "gaussian_mixture";
+};
+export type StageParamsClusterAlgorithmEnum = typeof StageParamsClusterAlgorithmEnum[keyof typeof StageParamsClusterAlgorithmEnum];
+export declare const StageParamsClusterOutputModeEnum: {
+    readonly Clusters: "clusters";
+    readonly Labeled: "labeled";
+    readonly Representatives: "representatives";
+};
+export type StageParamsClusterOutputModeEnum = typeof StageParamsClusterOutputModeEnum[keyof typeof StageParamsClusterOutputModeEnum];
+//# sourceMappingURL=stage-params-cluster.d.ts.map

package/dist/models/stage-params-cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-params-cluster.d.ts","sourceRoot":"","sources":["../../models/stage-params-cluster.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAIH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,WAAW,CAAC,EAAE,+BAA+B,CAAC;IAC9C;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,gCAAgC,CAAC;IACjD;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,eAAO,MAAM,+BAA+B;;;;;;;CAOlC,CAAC;AAEX,MAAM,MAAM,+BAA+B,GAAG,OAAO,+BAA+B,CAAC,MAAM,OAAO,+BAA+B,CAAC,CAAC;AACnI,eAAO,MAAM,gCAAgC;;;;CAInC,CAAC;AAEX,MAAM,MAAM,gCAAgC,GAAG,OAAO,gCAAgC,CAAC,MAAM,OAAO,gCAAgC,CAAC,CAAC"}

package/dist/models/stage-params-code-execution.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Mixpeek API
+ * This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.
+ *
+ * The version of the OpenAPI document: 0.81.1
+ * Contact: info@mixpeek.com
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { StageDefsErrorHandling } from './stage-defs-error-handling';
+/**
+ * Configuration for executing custom code in secure isolated sandboxes.  **Stage Category**: ENRICH (1-1 Enrichment)  **Transformation**: N documents → N documents (same count, expanded schema)  **Purpose**: Executes user-provided code in isolated sandboxes to compute custom enrichments for each document. The code receives all documents as a JSON array and must return a list of results matching the input length.  **When to Use**:     - Custom transformations not covered by built-in stages     - Data extraction (regex, parsing)     - Unit conversions and normalization     - Cross-document computations (relative scores, rankings)     - Prototyping custom enrichment logic     - Complex string manipulations  **When NOT to Use**:     - Simple field transformations (use json_transform)     - LLM-based enrichment (use llm_enrich)     - External API calls (use api_call stage)     - When deterministic built-in stages suffice  **Operational Behavior**:     - Creates ONE sandbox per stage execution (~200ms startup)     - Passes ALL documents as JSON array to user code     - User code must set `result` to list matching input length     - Merges results back into documents at output_field     - Supports Python, TypeScript, and JavaScript  **Template Support**:     - {{INPUT.*}}: Pipeline input parameters (evaluated before execution)     - {{CONTEXT.*}}: Execution context (namespace_id, internal_id)     - {{SECRET.*}}: Organization vault secrets (e.g., {{SECRET.api_key}})     - Documents are passed as runtime `docs` variable (NOT a template)  **Using Secrets**:     Secrets stored in your organization vault can be referenced in code and env:     - In env vars: {\"API_KEY\": \"{{SECRET.stripe_api_key}}\"}     - In code: \"api_key = \'{{SECRET.my_key}}\'\"  (less common, prefer env vars)     Secrets are automatically loaded from the vault and redacted in error messages.  Requirements:     - code: REQUIRED, code to execute (receives `docs`, must set `result`)     - output_field: REQUIRED, where to store computed results     - language: OPTIONAL, execution language (default: python)     - timeout_ms: OPTIONAL, execution timeout (default: 5000ms)  Examples:     Word count enrichment:         ```json         {             \"code\": \"result = [{\'word_count\': len(d.get(\'content\', \'\').split())} for d in docs]\",             \"output_field\": \"text_stats\"         }         ```      Cross-document relative scores:         ```json         {             \"code\": \"avg = sum(d.get(\'score\', 0) for d in docs) / len(docs)\\nresult = [{\'relative\': d.get(\'score\', 0) / avg} for d in docs]\",             \"output_field\": \"score_analysis\"         }         ```
+ * @export
+ * @interface StageParamsCodeExecution
+ */
+export interface StageParamsCodeExecution {
+    /**
+     * Code to execute in the sandbox. Receives \'docs\' variable (list of document dicts). Must set \'result\' variable to a list matching input length. Supports {{INPUT.*}}, {{CONTEXT.*}}, and {{SECRET.*}} templates.
+     * @type {string}
+     * @memberof StageParamsCodeExecution
+     */
+    'code'?: string;
+    /**
+     * Execution language. Python recommended for most use cases.
+     * @type {string}
+     * @memberof StageParamsCodeExecution
+     */
+    'language'?: StageParamsCodeExecutionLanguageEnum;
+    /**
+     * Document field path where results are merged. Dot notation supported: \'metadata.computed\'
+     * @type {string}
+     * @memberof StageParamsCodeExecution
+     */
+    'output_field'?: string;
+    /**
+     * Variable name containing the output list in your code. Must be a JSON-serializable list with length == len(docs).
+     * @type {string}
+     * @memberof StageParamsCodeExecution
+     */
+    'result_variable'?: string;
+    /**
+     * Execution timeout in milliseconds (100ms-30s, default 5s)
+     * @type {number}
+     * @memberof StageParamsCodeExecution
+     */
+    'timeout_ms'?: number;
+    /**
+     * Max output size in bytes (default 100KB, max 1MB)
+     * @type {number}
+     * @memberof StageParamsCodeExecution
+     */
+    'max_output_size'?: number;
+    /**
+     * Environment variables available during execution. Supports INPUT and SECRET templates: {\'API_KEY\': \'{{SECRET.stripe_key}}\', \'USER_ID\': \'{{INPUT.user_id}}\'}
+     * @type {{ [key: string]: string; }}
+     * @memberof StageParamsCodeExecution
+     */
+    'env'?: {
+        [key: string]: string;
+    };
+    /**
+     * \'skip\': On error, return input documents unchanged. \'raise\': Fail entire pipeline on any error.
+     * @type {StageDefsErrorHandling}
+     * @memberof StageParamsCodeExecution
+     */
+    'on_error'?: StageDefsErrorHandling;
+}
+export declare const StageParamsCodeExecutionLanguageEnum: {
+    readonly Python: "python";
+    readonly Typescript: "typescript";
+    readonly Javascript: "javascript";
+};
+export type StageParamsCodeExecutionLanguageEnum = typeof StageParamsCodeExecutionLanguageEnum[keyof typeof StageParamsCodeExecutionLanguageEnum];
+//# sourceMappingURL=stage-params-code-execution.d.ts.map

package/dist/models/stage-params-code-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-params-code-execution.d.ts","sourceRoot":"","sources":["../../models/stage-params-code-execution.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACrC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,oCAAoC,CAAC;IAClD;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KAAE,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,sBAAsB,CAAC;CACvC;AAED,eAAO,MAAM,oCAAoC;;;;CAIvC,CAAC;AAEX,MAAM,MAAM,oCAAoC,GAAG,OAAO,oCAAoC,CAAC,MAAM,OAAO,oCAAoC,CAAC,CAAC"}

package/dist/models/stage-params-document-enrich.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Mixpeek API
+ * This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.
+ *
+ * The version of the OpenAPI document: 0.81.1
+ * Contact: info@mixpeek.com
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { StageDefsLogicalOperator } from './stage-defs-logical-operator';
+import type { StageDefsStageCacheBehavior } from './stage-defs-stage-cache-behavior';
+/**
+ * Configuration for enriching documents with data from another collection.  **Stage Category**: APPLY (1-1 Inner Join/Enrichment)  **Transformation**: N documents → N documents (same count, expanded schema)  **Purpose**: Applies each input document to a lookup operation in another collection, merging matching data back. This performs JOIN-like operations similar to SQL INNER JOIN. Each input document produces exactly one output document with added fields.  **When to Use**:     - After FILTER/SORT to add related reference data     - To combine data from multiple collections (e.g., products + catalog info)     - When documents need contextual information from other sources     - For denormalizing data at query time instead of storage time     - To attach user profiles, metadata, or related entities  **When NOT to Use**:     - For initial document retrieval (use FILTER stages: hybrid_search)     - For removing documents (use FILTER stages)     - For reordering results (use SORT stages)     - When the target collection is very large (performance impact)     - For 1-N joins that expand document count (use taxonomy with multi-match)  **Operational Behavior**:     - Applies each input document to a collection lookup (1-1 operation)     - Performs database lookups for each document (MongoDB queries)     - Maintains document count: N in → N out     - Expands schema: adds fields from target collection     - Moderate performance (depends on target collection size and indexes)     - Left join semantics: missing matches result in null/absent fields  **Common Pipeline Position**: FILTER → SORT → APPLY (this stage)  **Join Operation**: This is a LEFT JOIN - all source documents are kept, enrichment fields are added when matches are found. Missing matches result in null/absent fields rather than document removal.  Requirements:     - target_collection_id: REQUIRED, collection to join with     - source_field: REQUIRED, field in current documents to match     - target_field: REQUIRED, field in target collection to match against     - fields_to_merge: OPTIONAL, specific fields to merge (or entire document)     - output_field: OPTIONAL, where to place enrichment (root or nested path)  Use Cases:     - Enrich product search results with full catalog data     - Add user profile information to activity logs     - Join cluster assignments with detailed metadata     - Attach reference data (categories, taxonomies) to documents     - Combine fragmented data across collections  Examples:     Basic field-based join:         ```json         {             \"target_collection_id\": \"col_products\",             \"source_field\": \"metadata.product_id\",             \"target_field\": \"product_id\",             \"fields_to_merge\": [\"name\", \"price\", \"category\"]         }         ```      Nested field join with custom output:         ```json         {             \"target_collection_id\": \"col_users\",             \"source_field\": \"lineage.source_object_id\",             \"target_field\": \"user_id\",             \"output_field\": \"enrichments.user_profile\",             \"fields_to_merge\": [\"name\", \"email\", \"role\"]         }         ```      Conditional enrichment (only for specific categories):         ```json         {             \"target_collection_id\": \"col_catalog\",             \"source_field\": \"metadata.sku\",             \"target_field\": \"sku\",             \"fields_to_merge\": [\"description\", \"specs\"],             \"when\": {                 \"field\": \"metadata.category\",                 \"operator\": \"eq\",                 \"value\": \"electronics\"             }         }         ```
+ * @export
+ * @interface StageParamsDocumentEnrich
+ */
+export interface StageParamsDocumentEnrich {
+    /**
+     * Controls internal caching behavior for this stage. OPTIONAL - defaults to \'auto\' for transparent performance.   \'auto\' (default): Automatic caching for deterministic operations. Stage intelligently caches results based on inputs and parameters. Use for transformations, parsing, formatting, stable API calls. Cache invalidates automatically when parameters change. Recommended for 95% of use cases.   \'disabled\': Skip all internal caching. Every execution runs fresh without cache lookup. Use for templates with now(), random(), or external APIs that must be called every time (real-time data). No performance benefit but guarantees fresh execution.   \'aggressive\': Cache even non-deterministic operations. Use ONLY when you fully understand caching implications. May cache time-sensitive or random data. Generally not recommended - prefer \'auto\' or \'disabled\'.   Note: This controls internal stage caching. Retriever-level caching (cache_config.cache_stage_names) is separate and caches complete stage outputs.
+     * @type {StageDefsStageCacheBehavior}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'cache_behavior'?: StageDefsStageCacheBehavior;
+    /**
+     * Time-to-live for cache entries in seconds. OPTIONAL - defaults to None (LRU eviction only).   When None (default, recommended): Cache uses Redis LRU eviction policy. Most frequently used items stay cached automatically. No manual TTL management needed. Memory bounded by Redis maxmemory setting.   When specified: Cache entries expire after this duration regardless of usage. Useful for data that becomes stale after specific time periods. Lower values for frequently changing external data. Higher values for stable transformations.   Examples: - None: LRU-based eviction (recommended for most cases) - 300: 5 minutes (for semi-static external data) - 3600: 1 hour (for stable transformations) - 86400: 24 hours (for rarely changing operations)   Performance Note: TTL adds minimal overhead (<1ms) but forces eviction even for frequently accessed items. Use None unless you have specific staleness requirements.
+     * @type {number}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'cache_ttl_seconds'?: number;
+    /**
+     * ID of an existing retriever to use for finding enrichment data. When provided, uses the full retriever pipeline (semantic search, filters, etc.) instead of simple field matching. Mutually exclusive with retriever_config.
+     * @type {string}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'retriever_id'?: string;
+    /**
+     * Anonymous retriever definition for finding enrichment data. Allows defining a custom retriever inline without creating it separately. Mutually exclusive with retriever_id. Must have \'stages\' array with at least one stage.
+     * @type {{ [key: string]: any; }}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'retriever_config'?: {
+        [key: string]: any;
+    };
+    /**
+     * Template mapping from source document fields to retriever inputs. Supports template syntax: {{DOC.field_name}} to reference source document fields. Used when retriever_id or retriever_config is specified.
+     * @type {{ [key: string]: any; }}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'retriever_inputs'?: {
+        [key: string]: any;
+    };
+    /**
+     * Collection ID to fetch enrichment data from. REQUIRED for direct joins (when retriever_id/retriever_config not provided). Also used to scope retriever queries when retriever-based join is used. NOTE: You must replace the default placeholder with your actual collection ID.
+     * @type {string}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'target_collection_id'?: string;
+    /**
+     * Dot-path to field in current document to match on. REQUIRED for direct joins (when retriever_id/retriever_config not provided). For retriever-based joins, use retriever_inputs instead.
+     * @type {string}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'source_field'?: string;
+    /**
+     * Field in target collection to match against. REQUIRED for direct joins (when retriever_id/retriever_config not provided). Ignored for retriever-based joins.
+     * @type {string}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'target_field'?: string;
+    /**
+     * Specific fields from target document to merge. If None, merges entire document. Supports dot-notation for nested fields.
+     * @type {Array<string>}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'fields_to_merge'?: Array<string>;
+    /**
+     * Dot-path where enrichment data should be placed. If None, merges directly into document root. Use \'enrichments.{name}\' to namespace enrichments.
+     * @type {string}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'output_field'?: string;
+    /**
+     * How to handle the merge: \'enrich\' = add fields to existing document, \'replace\' = replace document with enriched version, \'append\' = add as array item
+     * @type {string}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'strategy'?: string;
+    /**
+     * Conditional filter to determine which documents should be enriched. Documents not matching the condition pass through unchanged.
+     * @type {StageDefsLogicalOperator}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'when'?: StageDefsLogicalOperator;
+    /**
+     * If True, documents without matching enrichment data pass through unchanged. If False, documents without matches are filtered out.
+     * @type {boolean}
+     * @memberof StageParamsDocumentEnrich
+     */
+    'allow_missing'?: boolean;
+}
+//# sourceMappingURL=stage-params-document-enrich.d.ts.map

package/dist/models/stage-params-document-enrich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-params-document-enrich.d.ts","sourceRoot":"","sources":["../../models/stage-params-document-enrich.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACtC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,2BAA2B,CAAC;IAC/C;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KAAE,CAAC;IAC7C;;;;OAIG;IACH,kBAAkB,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KAAE,CAAC;IAC7C;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAClC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B"}

package/dist/models/stage-params-external-web-search.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Mixpeek API
+ * This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.
+ *
+ * The version of the OpenAPI document: 0.81.1
+ * Contact: info@mixpeek.com
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * Configuration for web search enrichment using Exa AI-native search.  **Stage Category**: APPLY (Document Enrichment - enriches existing documents)  **Transformation**: N documents → N documents (each enriched with web search results)  **Purpose**: Enriches each document in the pipeline by adding AI-native web search results from Exa\'s neural ranking system to the document\'s metadata. The query can be templated per-document using {{DOC.*}}, {{INPUT.*}}, etc., enabling dynamic searches based on document content. Results are automatically cached by query to minimize redundant API calls.  **When to Use**:     - Enrich documents with real-time web context     - Add related articles/research to each document     - Augment internal data with external web sources     - Find competitive intelligence per product/company in documents     - Add news/updates related to document entities     - Research and discovery based on document content     - Context augmentation for RAG pipelines  **When NOT to Use**:     - Searching within your own collections (use feature_search instead)     - Need full web page content (use web_scrape stage for that)     - Want to create NEW documents from web search (this enriches existing ones)     - No existing documents to enrich (pipeline must have documents first)  **Operational Behavior**:     - ENRICHES existing documents (N → N operation, preserves all docs)     - Each document gets web search results added to metadata.web_search     - Query is templated per-document with {{DOC.*}} support     - Smart caching: identical queries share results (only 1 API call)     - Preserves all original document data (ID, collection, score, etc.)     - Makes external HTTP request to Exa API (cached per unique query)     - Fast operation: 100-500ms per unique query (not per document)  **Common Pipeline Position**:     - feature_search → web_search (enrich search results with web context)     - feature_search → web_search → llm_filter (search, enrich, then filter)     - feature_search → web_search → web_scrape (enrich with URLs, then scrape)  **Cost & Performance**:     - Moderate Cost: Exa API charges per unique query (caching reduces costs)     - Fast: 100-500ms per unique query, cached queries are instant     - Network dependent: requires external API call     - Static queries: 1 API call for all documents (highly efficient)     - Dynamic queries: 1 API call per unique rendered query  **Output Schema**: Adds to each DocumentResult:     - metadata.web_search.query: Rendered query used for this document     - metadata.web_search.results: Array of web search results     - metadata.web_search.results[].url: Web page URL     - metadata.web_search.results[].title: Page title     - metadata.web_search.results[].text: Text snippet (if include_text=True)     - metadata.web_search.results[].published_date: Publication date     - metadata.web_search.results[].author: Author name     - metadata.web_search.results[].score: Exa relevance score     - metadata.web_search.results[].position: Result position (0-indexed)     - metadata.web_search.num_results: Count of results     - metadata.web_search.autoprompt_used: Whether autoprompt was enabled  Requirements:     - query: REQUIRED, search query text (supports templates like {INPUT.query})     - num_results: OPTIONAL, number of results (default 10, max 100)     - use_autoprompt: OPTIONAL, use Exa\'s query enhancement (default True)     - start_published_date: OPTIONAL, filter by publication date     - category: OPTIONAL, filter by content type     - include_text: OPTIONAL, include text snippets (default True)  Use Cases:     - RAG enhancement: Enrich documents with current web context before LLM     - Product research: Add competitor info to each product document     - News enrichment: Add latest news to company/entity documents     - Academic research: Add related papers to each research document     - Documentation augmentation: Add official docs/guides to each result     - Competitive intelligence: Enrich results with competitor mentions     - Fact verification: Add source citations from web to each claim  Examples:     Static query enrichment (all documents get same web results):         ```json         {             \"query\": \"latest AI developments 2024\",             \"num_results\": 10,             \"include_text\": true         }         ```         Result: 1 API call total, all documents enriched with same 10 web results      Dynamic per-document enrichment (query varies by document):         ```json         {             \"query\": \"{{DOC.metadata.product_name}} reviews and comparisons\",             \"num_results\": 5,             \"include_text\": true         }         ```         Result: 1 API call per unique product name (automatically cached)      Hybrid query (combines input + document fields):         ```json         {             \"query\": \"{{INPUT.topic}} {{DOC.metadata.category}}\",             \"num_results\": 3,             \"start_published_date\": \"2024-01-01\"         }         ```         Result: Caching optimizes for documents with same topic+category combo      News enrichment with date filter:         ```json         {             \"query\": \"{{DOC.metadata.company_name}} latest news\",             \"num_results\": 5,             \"category\": \"news\",             \"start_published_date\": \"2024-11-01\"         }         ```         Result: Recent news added to each company document\'s metadata
+ * @export
+ * @interface StageParamsExternalWebSearch
+ */
+export interface StageParamsExternalWebSearch {
+    /**
+     * Search query text for Exa AI search. Supports template variables: {{INPUT.field}} for query inputs, {{DOC.field}} for document fields in enrichment context. Exa uses neural ranking for semantic search, so natural language queries work well. Examples: \'machine learning tutorials\', \'latest AI developments\', \'{{INPUT.user_query}}\', \'news about {{DOC.metadata.company_name}}\'
+     * @type {string}
+     * @memberof StageParamsExternalWebSearch
+     */
+    'query'?: string;
+    /**
+     * OPTIONAL. Number of search results to return. Must be between 1 and 100. Default is 10. More results = higher API costs. Consider using lower values for faster responses and cost control.
+     * @type {number}
+     * @memberof StageParamsExternalWebSearch
+     */
+    'num_results'?: number;
+    /**
+     * OPTIONAL. Enable Exa\'s autoprompt feature for query enhancement. When True, Exa optimizes the query for better search results. Default is True. Recommended for most use cases. Disable if you want exact query matching without enhancement.
+     * @type {boolean}
+     * @memberof StageParamsExternalWebSearch
+     */
+    'use_autoprompt'?: boolean;
+    /**
+     * OPTIONAL. Filter results to content published after this date. Format: YYYY-MM-DD (e.g., \'2024-01-01\'). When NOT specified, returns results from all dates. Useful for finding recent content, news, or time-sensitive information.
+     * @type {string}
+     * @memberof StageParamsExternalWebSearch
+     */
+    'start_published_date'?: string;
+    /**
+     * OPTIONAL. Filter results by content category. When NOT specified, searches across all categories. Common categories: \'research paper\', \'news\', \'github\', \'tweet\', \'company\', \'pdf\', \'personal site\', \'blog\'. Case-insensitive. Use for focused domain search.
+     * @type {string}
+     * @memberof StageParamsExternalWebSearch
+     */
+    'category'?: string;
+    /**
+     * OPTIONAL. Include text snippets in search results. When True, each result includes a text preview (~200 words). Default is True. Disable to reduce API costs and response size. Text snippets are stored in metadata.text field of DocumentResult.
+     * @type {boolean}
+     * @memberof StageParamsExternalWebSearch
+     */
+    'include_text'?: boolean;
+}
+//# sourceMappingURL=stage-params-external-web-search.d.ts.map

package/dist/models/stage-params-external-web-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-params-external-web-search.d.ts","sourceRoot":"","sources":["../../models/stage-params-external-web-search.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAIH;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IACzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B"}

package/dist/models/stage-params-feature-search.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Mixpeek API
+ * This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.
+ *
+ * The version of the OpenAPI document: 0.81.1
+ * Contact: info@mixpeek.com
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { StageDefsFacetFieldConfig } from './stage-defs-facet-field-config';
+import type { StageDefsFeatureSearchConfig } from './stage-defs-feature-search-config';
+import type { StageDefsFeatureSearchGroupBy } from './stage-defs-feature-search-group-by';
+import type { StageDefsFusionStrategy } from './stage-defs-fusion-strategy';
+import type { StageDefsLearnedFusionConfig } from './stage-defs-learned-fusion-config';
+import type { StageDefsQueryPreprocessing } from './stage-defs-query-preprocessing';
+import type { StageDefsStageCacheBehavior } from './stage-defs-stage-cache-behavior';
+/**
+ * User configuration for the feature_filter stage.  **Stage Category**: FILTER  **Transformation**: 0 documents → ≤final_top_k documents  **Purpose**: Unified stage for semantic and hybrid search across N feature URIs. Performs vector similarity search on one or more embedding features and fuses results using configurable strategies. Leverages Qdrant\'s native multi-vector search and fusion capabilities for optimal performance.  **When to Use**:     - As the initial stage to find candidate documents from collections     - Single feature URI (N=1): Pure semantic/KNN search     - Multiple feature URIs (N>1): Hybrid/multimodal search with fusion     - Multimodal search: Text + image + video embeddings combined     - Lexical + semantic: Sparse + dense vectors for best-of-both     - Any combination of dense vector features     - **Filter-only mode (N=0)**: Pure attribute/text filtering without embeddings       by providing only pre_filters (uses Qdrant\'s native full-text search)  **When NOT to Use**:     - For filtering in-memory results (use attribute_filter or llm_filter)     - For reordering results (use SORT stages)     - For enriching documents (use APPLY stages)  **Operational Behavior**:     - **With searches**: Queries vector databases (Qdrant) for each feature URI       in parallel, generates embeddings via inference service, performs multi-vector       search with Qdrant native fusion, returns fused and scored results     - **Filter-only mode**: Uses Qdrant\'s scroll API with native filtering (no embeddings,       no vector search). Supports full-text search via TEXT operator and all other       filter operators. Returns documents matching filters without relevance scores.     - Moderate performance (depends on number of features and top_k)     - Output schema = Collection document schema (no schema changes)  **Common Pipeline Position**: FILTER (this stage) → ENRICH → SORT → REDUCE  **Configuration vs Execution**:     Configuration time (defining the retriever):     - Specify searches: List of features to search with parameters     - Use TEMPLATES for query inputs: {{INPUT.field_name}}     - Configure fusion strategy, weights, final_top_k      Execution time (running the retriever):     - Only pass input values (e.g., {\"user_query\": \"search text\"})     - System resolves templates using your input values     - Generates embeddings and performs searches automatically  Requirements:     - searches: REQUIRED, at least one feature search configuration     - final_top_k: OPTIONAL, defaults to 25 results after fusion     - fusion: OPTIONAL, defaults to RRF for multi-feature searches     - cache_behavior: OPTIONAL, defaults to \'auto\' for caching (inherited)  Use Cases:     - Single-modal search: One feature URI (text OR image OR video)     - Multimodal search: Text + image + video features combined     - Hybrid search: Dense + sparse vectors for best-of-both     - Multi-index search: Search across multiple feature types simultaneously  Example Stage Configuration (Multimodal):     ```json     {         \"stage_name\": \"multimodal_search\",         \"stage_type\": \"filter\",         \"config\": {             \"stage_id\": \"feature_search\",             \"parameters\": {                 \"searches\": [                     {                         \"feature_uri\": \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",                         \"query\": {\"input_mode\": \"text\", \"value\": \"{{INPUT.user_query}}\"},                         \"top_k\": 100,                         \"weight\": 0.6                     },                     {                         \"feature_uri\": \"mixpeek://clip_extractor@v1/image_embedding\",                         \"query\": {\"input_mode\": \"text\", \"value\": \"{{INPUT.user_query}}\"},                         \"top_k\": 50,                         \"weight\": 0.4                     }                 ],                 \"final_top_k\": 25,                 \"fusion\": \"weighted\"             }         }     }     ```  Example Execution Request:     ```json     {         \"inputs\": {             \"user_query\": \"red sports car with spoiler\"         }     }     ```
+ * @export
+ * @interface StageParamsFeatureSearch
+ */
+export interface StageParamsFeatureSearch {
+    /**
+     * Controls internal caching behavior for this stage. OPTIONAL - defaults to \'auto\' for transparent performance.   \'auto\' (default): Automatic caching for deterministic operations. Stage intelligently caches results based on inputs and parameters. Use for transformations, parsing, formatting, stable API calls. Cache invalidates automatically when parameters change. Recommended for 95% of use cases.   \'disabled\': Skip all internal caching. Every execution runs fresh without cache lookup. Use for templates with now(), random(), or external APIs that must be called every time (real-time data). No performance benefit but guarantees fresh execution.   \'aggressive\': Cache even non-deterministic operations. Use ONLY when you fully understand caching implications. May cache time-sensitive or random data. Generally not recommended - prefer \'auto\' or \'disabled\'.   Note: This controls internal stage caching. Retriever-level caching (cache_config.cache_stage_names) is separate and caches complete stage outputs.
+     * @type {StageDefsStageCacheBehavior}
+     * @memberof StageParamsFeatureSearch
+     */
+    'cache_behavior'?: StageDefsStageCacheBehavior;
+    /**
+     * Time-to-live for cache entries in seconds. OPTIONAL - defaults to None (LRU eviction only).   When None (default, recommended): Cache uses Redis LRU eviction policy. Most frequently used items stay cached automatically. No manual TTL management needed. Memory bounded by Redis maxmemory setting.   When specified: Cache entries expire after this duration regardless of usage. Useful for data that becomes stale after specific time periods. Lower values for frequently changing external data. Higher values for stable transformations.   Examples: - None: LRU-based eviction (recommended for most cases) - 300: 5 minutes (for semi-static external data) - 3600: 1 hour (for stable transformations) - 86400: 24 hours (for rarely changing operations)   Performance Note: TTL adds minimal overhead (<1ms) but forces eviction even for frequently accessed items. Use None unless you have specific staleness requirements.
+     * @type {number}
+     * @memberof StageParamsFeatureSearch
+     */
+    'cache_ttl_seconds'?: number;
+    /**
+     * List of feature searches to perform and fuse. Can be empty for filter-only mode (requires pre_filters). For single-modal search: Provide 1 feature search (pure KNN/semantic). For hybrid/multimodal: Provide 2+ feature searches (fusion applied). Each feature search specifies: feature URI, query input, top_k, score threshold. Searches execute in parallel and results are fused using fusion strategy.   **Filter-only mode**: Leave empty and provide pre_filters to use Qdrant\'s native filtering (including full-text search) without vector embeddings. This enables pure attribute/text search without semantic similarity.
+     * @type {Array<StageDefsFeatureSearchConfig>}
+     * @memberof StageParamsFeatureSearch
+     */
+    'searches'?: Array<StageDefsFeatureSearchConfig>;
+    /**
+     * OPTIONAL. Maximum number of documents to return after fusion. Defaults to 25. This is applied AFTER all feature searches are fused together. Must be ≤ minimum top_k across all searches.Higher values: More comprehensive results but slower. Common values: 10 (fast), 25 (balanced), 50-100 (comprehensive).
+     * @type {number}
+     * @memberof StageParamsFeatureSearch
+     */
+    'final_top_k'?: number;
+    /**
+     * OPTIONAL. Score fusion strategy for combining multiple feature searches. Defaults to \'rrf\' (Reciprocal Rank Fusion). Only relevant when searches has 2+ entries. Ignored for single feature search (no fusion needed).   ┌──────────┬──────────────┬────────────────────────────────────────┐ │ Strategy │ Qdrant Native│ Description                            │ ├──────────┼──────────────┼────────────────────────────────────────┤ │ rrf      │ ✅ Yes       │ Rank-based, robust default             │ │ dbsf     │ ✅ Yes       │ Score-based with normalization         │ │ weighted │ ❌ No        │ Manual score-weighted fusion           │ │ max      │ ❌ No        │ Best match from any feature            │ │ learned  │ ❌ No        │ Bandit-learned, personalized weights   │ └──────────┴──────────────┴────────────────────────────────────────┘   \'rrf\' (default): Rank-based fusion, robust and simple. Single Qdrant call, no tuning needed.   \'dbsf\': Score-based fusion with statistical normalization. Single Qdrant call, handles different score scales.   \'weighted\': Manual weight fusion using FeatureSearchConfig.weight. N separate queries, merged client-side.   \'max\': Maximum score across features (OR semantics). N separate queries, merged client-side.   \'learned\': Bandit-learned weights from user feedback. Requires learning_config. Enables personalization. N separate queries for per-feature score tracking.
+     * @type {StageDefsFusionStrategy}
+     * @memberof StageParamsFeatureSearch
+     */
+    'fusion'?: StageDefsFusionStrategy;
+    /**
+     * OPTIONAL. Configuration for learned fusion. REQUIRED when fusion=\'learned\', ignored otherwise.   Enables personalized feature weighting by learning from user interactions. The system learns which features (text, image, audio) matter most for different users or contexts via Thompson Sampling bandit.   See LearnedFusionConfig for full documentation.
+     * @type {StageDefsLearnedFusionConfig}
+     * @memberof StageParamsFeatureSearch
+     */
+    'learning_config'?: StageDefsLearnedFusionConfig;
+    /**
+     * OPTIONAL. Default preprocessing config for all searches in this stage. When set, all searches without their own query_preprocessing will inherit this config. Per-search query_preprocessing overrides this stage default. Use for stage-wide preprocessing when all searches target large file inputs.
+     * @type {StageDefsQueryPreprocessing}
+     * @memberof StageParamsFeatureSearch
+     */
+    'query_preprocessing'?: StageDefsQueryPreprocessing;
+    /**
+     * OPTIONAL. Enable smart auto-detection of when to apply query preprocessing. Defaults to True. When enabled, content-mode queries (URLs/base64) are automatically preprocessed based on content type: - Video/Audio: Auto-preprocessed (decompose into segments) - PDF: Auto-preprocessed (decompose into pages) - Image: NOT preprocessed (single embedding is sufficient) - Text mode: NOT preprocessed (unless explicitly configured)  Set to False to disable auto-detection and require explicit query_preprocessing config on each search. Per-search query_preprocessing always takes priority over auto-detection.
+     * @type {boolean}
+     * @memberof StageParamsFeatureSearch
+     */
+    'auto_preprocess'?: boolean;
+    /**
+     * OPTIONAL. Collection identifiers to search within this stage. Can be collection IDs or names. If NOT provided, uses retriever\'s default collections. Use this to target specific collections independent of retriever defaults.   Note: These identifiers are validated at retriever creation time to ensure the stage\'s feature_uris can be resolved against these collections.   Use cases: - Multi-tier pipelines where different stages search different collections - Stage-specific collection targeting - Override retriever defaults for this stage only
+     * @type {Array<string>}
+     * @memberof StageParamsFeatureSearch
+     */
+    'collection_identifiers'?: Array<string>;
+    /**
+     * OPTIONAL. Fields to compute facet counts for during search. Facets run in PARALLEL with the search query using the same filters, providing value counts for the entire filtered result set (not just paginated results).   Use cases: - Build faceted search UIs (e.g., \'Filter by Category: Sports (45), Music (23)\') - Show available filter options with document counts - Enable drill-down navigation in search results   Requirements: - Each faceted field MUST have a keyword index in Qdrant - Common auto-indexed fields: metadata.*, status, collection_id - For custom fields, ensure indexing is configured   Performance: - Facets execute in parallel with search (minimal latency impact) - Use approximate counts (exact=False) for fast UI responses - Limit facet count per field to reduce response size
+     * @type {Array<StageDefsFacetFieldConfig>}
+     * @memberof StageParamsFeatureSearch
+     */
+    'facets'?: Array<StageDefsFacetFieldConfig>;
+    /**
+     * OPTIONAL. Database-level grouping configuration (uses Qdrant query_points_groups). When enabled, results are grouped by the specified field at the database level, which is more efficient than in-memory grouping for large result sets.   Use cases: - Decompose/recompose: Search chunks, return parent documents - Deduplication: One best result per product_id - Scene→Video grouping: Search frames, return parent videos   Output modes (mirrors group_by REDUCE stage for consistency): - \'first\': Top doc per group (deduplication) - \'all\': All docs with group structure preserved - \'flatten\': All docs as flat list   Performance: - Grouping happens in Qdrant (database-level) - Much faster than fetching all results and grouping in memory - Use for decompose/recompose patterns at scale
+     * @type {StageDefsFeatureSearchGroupBy}
+     * @memberof StageParamsFeatureSearch
+     */
+    'group_by'?: StageDefsFeatureSearchGroupBy;
+}
+//# sourceMappingURL=stage-params-feature-search.d.ts.map

package/dist/models/stage-params-feature-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-params-feature-search.d.ts","sourceRoot":"","sources":["../../models/stage-params-feature-search.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAGjF,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oCAAoC,CAAC;AAGvF,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,sCAAsC,CAAC;AAG1F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAG5E,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oCAAoC,CAAC;AAGvF,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAGpF,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACrC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,2BAA2B,CAAC;IAC/C;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,4BAA4B,CAAC;IACjD;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,2BAA2B,CAAC;IACpD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC5C;;;;OAIG;IACH,UAAU,CAAC,EAAE,6BAA6B,CAAC;CAC9C"}

package/dist/models/stage-params-group-by.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mixpeek API
+ * This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.
+ *
+ * The version of the OpenAPI document: 0.81.1
+ * Contact: info@mixpeek.com
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * Configuration for grouping documents by field value.  Stage Category: REDUCE  Transformation: N documents → M groups (where M ≤ N)  Purpose: Groups documents by a common field value, aggregating chunks back to parent objects. Essential for decompose/recompose workflows where chunks are searched individually then grouped to show context.  Performance: Runs in API layer (fast stage, ~10-50ms for 100-500 docs). Integrates with optimizer for filter push-down before grouping. Future optimization will push grouping into Qdrant for 10-100x speedup.  When to Use:     - After chunk-level search to group back to objects     - To deduplicate results by a field     - To aggregate related documents     - For decompose→search→recompose workflows     - Show top N results per category/author/parent  When NOT to Use:     - For initial document retrieval (use FILTER stages: hybrid_search)     - For ordering documents (use SORT stages: sort_relevance)     - For enriching documents (use APPLY stages: document_enrich)     - For expanding documents (use APPLY 1-N stages: taxonomy_enrich)  Operational Behavior:     - Fast stage: runs in API layer (no Engine delegation)     - In-memory grouping: Python dict-based grouping     - Groups documents with same field value     - Sorts within groups by score (highest first)     - Limits documents per group (configurable)     - Reports metrics to ClickHouse for learned optimizations  Common Pipeline Position: FILTER → SORT → REDUCE (this stage)  Requirements:     - group_by_field: REQUIRED     - max_per_group: OPTIONAL, defaults to 10     - output_mode: OPTIONAL, defaults to \"all\"  Use Cases:     - Decompose/recompose: Search 50 scenes, group to 10 videos     - Deduplication: Group by unique_id, keep top match     - Analytics: Group by category, show top docs per category     - Multi-tier results: Show top 3 products per brand  Examples:     - Group video scenes back to parent videos     - Deduplicate search results by product_id     - Show top 3 articles per author     - Display best match per category
+ * @export
+ * @interface StageParamsGroupBy
+ */
+export interface StageParamsGroupBy {
+    /**
+     * Field path to group documents by using dot notation. Documents with the same field value are grouped together. Common fields: \'source_object_id\' (parent object from decomposition), \'root_object_id\' (top-level ancestor in hierarchy), \'metadata.category\' (nested categorical field), \'video_id\' (media grouping), \'product_id\' (e-commerce). Use dot notation for nested fields: \'metadata.user_id\', \'lineage.source_id\'. Performance: Indexed fields are faster for future Qdrant native grouping optimization. Template support: Use {{inputs.group_field}} for dynamic grouping.
+     * @type {string}
+     * @memberof StageParamsGroupBy
+     */
+    'group_by_field'?: string;
+    /**
+     * OPTIONAL. Maximum number of documents to keep per group. Documents are sorted by score (highest first) before limiting. Default: 10. Use 1 for deduplication (keeps only highest scoring doc per group). Use 3-5 for preview results (show top chunks per parent). Use 50+ for comprehensive results (show many chunks per parent). Performance: Lower values reduce response size and improve latency. Typical values: 1 (dedup), 5 (preview), 10 (default), 20 (detailed), 50 (comprehensive).
+     * @type {number}
+     * @memberof StageParamsGroupBy
+     */
+    'max_per_group'?: number;
+    /**
+     * OPTIONAL. Controls what documents are returned per group. \'first\': Return only the top document per group (deduplication, fastest).          Use for: unique results per group (e.g., one video per brand). \'all\': Return all documents grouped by field (default, shows full context).        Use for: showing chunks within each parent object. \'flatten\': Return all documents as flat list (loses group structure).            Use for: need all docs but don\'t care about grouping metadata. Default: \'all\'. Performance: \'first\' is fastest (smallest response), \'all\' preserves grouping, \'flatten\' is lightest (no group metadata).
+     * @type {string}
+     * @memberof StageParamsGroupBy
+     */
+    'output_mode'?: StageParamsGroupByOutputModeEnum;
+}
+export declare const StageParamsGroupByOutputModeEnum: {
+    readonly First: "first";
+    readonly All: "all";
+    readonly Flatten: "flatten";
+};
+export type StageParamsGroupByOutputModeEnum = typeof StageParamsGroupByOutputModeEnum[keyof typeof StageParamsGroupByOutputModeEnum];
+//# sourceMappingURL=stage-params-group-by.d.ts.map

package/dist/models/stage-params-group-by.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-params-group-by.d.ts","sourceRoot":"","sources":["../../models/stage-params-group-by.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAIH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,gCAAgC,CAAC;CACpD;AAED,eAAO,MAAM,gCAAgC;;;;CAInC,CAAC;AAEX,MAAM,MAAM,gCAAgC,GAAG,OAAO,gCAAgC,CAAC,MAAM,OAAO,gCAAgC,CAAC,CAAC"}