--- title: "Partially Update Cluster" method: PATCH path: "/v1/clusters/{cluster_identifier}" tags: ["Clusters"] --- # Partially Update Cluster `PATCH /v1/clusters/{cluster_identifier}` This endpoint partially updates a cluster (PATCH operation). Only provided fields will be updated. At minimum, metadata can always be updated. Immutable fields like cluster_id, status, and computed fields cannot be modified. ## Path parameters - `cluster_identifier` string, required — Cluster ID or name ## Request body - PatchClusterRequest — Request model for partially updating a cluster (PATCH operation). - `cluster_name` string, nullable — Updated name for the cluster - `description` string, nullable — Updated description for the cluster - `metadata` object, nullable — Updated metadata for the cluster - `llm_labeling` LLMLabelingInput — Configuration for LLM-based cluster labeling. Supports multiple LLM providers with comprehensive model selection: - OpenAI: GPT-4o, GPT-4o-mini, GPT-4.1, O3-mini (best for quality) - Google: Gemini 2.5 Flash, Gemini 1.5 Flash (best for speed and cost) - Anthropic: Claude 3.5 Sonnet, Claude 3.5 Haiku (best for reasoning) All models are defined as enums and validated at API level. - `enabled` boolean — Whether to generate labels for clusters using LLM. When enabled, clusters will have semantic labels like 'High-Performance Laptops' instead of generic labels like 'Cluster 0'. - `labeling_inputs` LLMLabelingInputInput — Input configuration for LLM-based cluster labeling. Supports flexible input mappings similar to retrievers and buckets, allowing multimodal inputs (text, images, videos, audio) for providers like Gemini that support native multimodal understanding. Examples: # Text-only labeling: LLMLabelingInput(input_mappings=[ InputMapping(input_key="headline", source_type="payload", path="headline"), InputMapping(input_key="description", source_type="payload", path="description") ]) # Multimodal labeling with images: LLMLabelingInput(input_mappings=[ InputMapping(input_key="text", source_type="payload", path="headline"), InputMapping(input_key="image_url", source_type="payload", path="thumbnail_url") ]) # Multimodal with video (for Gemini): LLMLabelingInput(input_mappings=[ InputMapping(input_key="text", source_type="payload", path="description"), InputMapping(input_key="video_url", source_type="payload", path="video_url") ]) - `input_mappings` InputMapping[], required — Flexible input mappings for constructing LLM context. Supports multimodal inputs (text, image_url, video_url, audio_url). Each mapping specifies how to extract data from document payloads. At least one input mapping is required. - `input_key` string, required — Key used in the constructed inputs payload. - `source_type` 'payload' | 'literal' | 'vector' | 'blob' — Where the value for an input should be retrieved from. - `path` string, nullable — Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback. - `override` unknown - `provider` 'openai' | 'google' | 'anthropic' — Supported LLM providers for content generation. Each provider has different strengths, pricing, and multimodal capabilities. Choose based on your use case, performance requirements, and budget. Values: OPENAI: OpenAI GPT models (GPT-4o, GPT-4.1, O3-mini) - Best for: General purpose, vision tasks, structured outputs - Multimodal: Text, images - Performance: Fast (100-500ms), reliable - Cost: Moderate to high ($0.15-$10 per 1M tokens) - Use when: Need high-quality generation with vision support GOOGLE: Google Gemini models (Gemini 3.1 Flash Lite, Gemini 2.5 Pro) - Best for: Fast generation, video understanding, cost-efficiency - Multimodal: Text, images, video, audio, PDFs - Performance: Very fast (50-200ms) - Cost: Low to moderate ($0.075-$0.40 per 1M tokens) - Use when: Need video/audio/PDF support or cost-efficiency ANTHROPIC: Anthropic Claude models (Claude 3.5 Sonnet, Claude 3.5 Haiku) - Best for: Long context, complex reasoning, safety - Multimodal: Text, images - Performance: Moderate (200-800ms) - Cost: Moderate to high ($0.25-$15 per 1M tokens) - Use when: Need long context or complex reasoning Examples: - Use OPENAI for production with structured JSON outputs - Use GOOGLE for video summarization and cost-sensitive workloads - Use ANTHROPIC for complex reasoning with long documents - `model_name` union — REQUIRED when enabled=True. Specific LLM model to use for cluster labeling. All models are defined as enums for type safety. OpenAI Models (provider='openai'): - gpt-4o-2024-08-06: Highest quality, best for production ($2.50/$10 per 1M tokens) - gpt-4o-mini-2024-07-18: Cost-effective, recommended for most use cases ($0.15/$0.60 per 1M tokens) - gpt-4.1-2025-04-14: Latest model, future-proofed - gpt-4.1-mini-2025-04-14: Latest cost-optimized model - o3-mini-2025-01-31: Advanced reasoning, best for complex clustering Google Models (provider='google'): - gemini-2.5-flash-lite: Fastest, latest multimodal model, recommended ($0.15/$0.60 per 1M tokens) Anthropic Models (provider='anthropic'): - claude-3-5-sonnet-20241022: Best reasoning, 200K context ($3/$15 per 1M tokens) - claude-3-5-haiku-20241022: Fast, cost-effective ($0.25/$1.25 per 1M tokens) Recommendation: - Use gemini-2.5-flash-lite (DEFAULT) - multimodal support - Use gpt-4o-mini-2024-07-18 for OpenAI compatibility - Use gpt-4o-2024-08-06 for highest quality when cost is not a concern - 'gpt-4o-2024-08-06' | 'gpt-4o-mini-2024-07-18' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'o3-mini-2025-01-31' — OpenAI model identifiers for LLM generation. Models listed in order of capability and cost (highest to lowest). All models support vision (images) except O3-mini. Values: GPT_4O: Latest GPT-4 Omni model (2024-08-06) - Use for: Production, highest quality generation - Context: 128K tokens - Vision: Yes - Cost: $2.50/1M input, $10/1M output - Performance: 200-500ms per request - When to use: Need best quality, willing to pay premium GPT_41: GPT-4.1 (2025-04-14) - Use for: Future-proofed pipelines - Context: 128K tokens - Vision: Yes - Cost: TBD (expected similar to GPT-4o) - When to use: Want latest model features GPT_4O_MINI: Smaller, faster GPT-4 Omni (2024-07-18) - Use for: High-volume, cost-sensitive workloads - Context: 128K tokens - Vision: Yes - Cost: $0.15/1M input, $0.60/1M output - Performance: 100-200ms per request - When to use: Good balance of quality and cost GPT_41_MINI: Smaller GPT-4.1 (2025-04-14) - Use for: Future cost-optimized pipelines - Context: 128K tokens - Vision: Yes - Cost: TBD (expected similar to GPT-4o-mini) - When to use: Want latest features at lower cost O3_MINI: Reasoning-optimized model (2025-01-31) - Use for: Complex reasoning, math, code - Context: 200K tokens - Vision: No - Cost: TBD - When to use: Need advanced reasoning capabilities Examples: - Use GPT_4O for caption generation with images (best quality) - Use GPT_4O_MINI for high-volume video scene summarization (cost-effective) - Use O3_MINI for complex entity extraction requiring reasoning - 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'gemini-3.1-flash-lite' — Google Gemini model identifiers for LLM generation. Gemini models excel at multimodal understanding with best-in-class video support. All models support text, images, video, audio, and PDFs. Values: GEMINI_2_5_FLASH_LITE: Gemini 2.5 Flash Lite model (recommended, stable GA) - Use for: Fastest generation, cost-effective multimodal - Context: 1M tokens - Multimodal: Text, images, video, audio, PDFs - When to use: Default choice for all Gemini use cases GEMINI_2_5_PRO: Gemini 2.5 Pro model - Use for: Higher quality reasoning, complex tasks - Context: 1M tokens GEMINI_2_5_FLASH: Gemini 2.5 Flash model - Kept for backward compatibility. GEMINI_3_1_FLASH_LITE: Alias for gemini-2.5-flash-lite (backwards compat) - Note: gemini-3.1-flash-lite does NOT exist in Google's API. This value is mapped to gemini-2.5-flash-lite at runtime. - 'claude-sonnet-4-5-20250929' | 'claude-haiku-4-5-20251001' | 'claude-3-5-sonnet-20241022' | 'claude-3-5-haiku-20241022' — Anthropic Claude model identifiers for LLM generation. Claude models excel at long context, complex reasoning, and safety. All models support text and images. Values: CLAUDE_3_5_SONNET: Most capable Claude model - Use for: Complex reasoning, long documents, safety-critical - Context: 200K tokens - Vision: Yes - Cost: $3/1M input, $15/1M output - Performance: 300-800ms per request - When to use: Need best reasoning, safety, or long context CLAUDE_3_5_HAIKU: Fast, cost-effective Claude model - Use for: High-volume, quick summaries - Context: 200K tokens - Vision: Yes - Cost: $0.25/1M input, $1.25/1M output - Performance: 100-300ms per request - When to use: Good balance of quality and cost Examples: - Use CLAUDE_3_5_SONNET for complex entity extraction from contracts (best reasoning) - Use CLAUDE_3_5_HAIKU for high-volume content moderation (cost-effective) - `include_summary` boolean — Whether to generate cluster summaries - `include_keywords` boolean — Whether to extract keywords for clusters - `max_samples_per_cluster` integer, nullable — Maximum representative documents to send to LLM per cluster for semantic analysis. When null (default), automatically scales based on cluster size and spread — smaller/tighter clusters get fewer samples, larger/sparser clusters get more (range 3-20). Set explicitly to override with a fixed value. - `sample_text_max_length` integer — Maximum characters per document sample text - `sample_selection_strategy` 'nearest' | 'representative' — How representative documents are chosen for the labeling LLM. 'nearest' (default): the N members closest to the cluster centroid — maximally prototypical, but adjacent clusters can yield near-identical sample sets and therefore near-identical labels. 'representative': a mixed panel of ~40% nearest-to-centroid, ~40% diversity picks (farthest-point coverage of the cluster's extent), and ~20% high-density examples — differentiates similar clusters at the same sample count and LLM cost. - `use_embedding_dedup` boolean — Enable embedding-based label deduplication to prevent near-duplicate labels (requires sentence-transformers) - `embedding_similarity_threshold` number — Cosine similarity threshold for duplicate label detection (labels above this are considered duplicates) - `cache_ttl_seconds` integer — Time-to-live for cached labels in seconds. Labels for clusters with identical representative documents will be reused within this TTL window, reducing LLM API costs. Default: 604800 (7 days). Set to 0 to disable caching. - `labeling_context` string, nullable — OPTIONAL. Freeform domain context about the data being clustered, injected into the labeling prompt as a clearly-delimited 'Domain context provided by the user' block (LS-4). Unlike custom_prompt, this does NOT replace the default prompt — it grounds the default labeler so labels use the right domain vocabulary. Example: 'These are scenes from pharmaceutical TV ads' turns generic labels like 'People Talking Outdoors' into 'Patient Testimonial Scenes'. Max 2000 characters. - `custom_prompt` string, nullable — OPTIONAL. Custom prompt template for LLM labeling. NOT REQUIRED - uses default discriminative prompt if not provided. When provided, completely replaces the default prompt. Your custom prompt receives cluster information but you must format it yourself. Use when: - Need domain-specific labeling (e.g., medical, legal, technical) - Want different label format (e.g., emoji labels, code names) - Require specific output structure - Have custom business logic for categorization Default prompt includes: cluster document samples, forbidden labels for uniqueness, and JSON response format. See engine/clusters/labeling/prompts.py for reference. Example: 'Analyze these product clusters and generate SHORT category names (2-3 words max) focusing on product type and price range. Return JSON: [{"cluster_id": "cl_0", "label": "..."}]' - `response_shape` union — OPTIONAL. Define custom structured output for LLM labeling. NOT REQUIRED - uses default structure (label, summary, keywords) if not provided. When provided, LLM output will match this structure and be stored in cluster documents. Two modes supported: 1. Natural language prompt (string): Describe desired output in plain English - Service automatically infers JSON schema from your description - Example: 'Extract cluster category, confidence score (0-1), and top 3 representative terms' - Auto-generates schema with appropriate types (string, number, array, etc.) 2. Explicit JSON schema (dict): Provide complete JSON schema for output structure - Full control over output structure, types, and constraints - Example: {'type': 'object', 'properties': {'category': {'type': 'string'}, ...}} Use when: - Need custom metadata fields (confidence scores, sentiment, complexity) - Want domain-specific structure (taxonomy hierarchies, entity extractions) - Require specific data types (arrays, nested objects, enums) - Have downstream schema requirements Output fields are automatically added to cluster collection schema and stored in metadata. Default behavior (if not provided): label (string), summary (string), keywords (array of strings) - string - object - `parameters` object — Provider-specific parameters forwarded to the LLM service. For OpenAI: temperature, max_tokens, top_p, json_output, etc. For Google: temperature, top_k, max_output_tokens, json_output, etc. - `filters` object, nullable — Updated pre-filter for clustering input documents. Overrides the cluster's stored filter on subsequent execute calls. - `face_cluster_merge` FaceClusterMergeConfig — Configuration for the post-HDBSCAN face-identity merge pass. Enables an agglomerative merge after HDBSCAN labels are assigned but before centroid calculation. Two clusters merge when the centroid cosine meets the cosine threshold AND at least one of the spatial signals (bbox IoU on overlapping frames, scene Jaccard) also clears its threshold. Defaults target ArcFace 512d face embeddings at the brand-corpus scale (~10^4 faces, ~10^2 true identities). - `enabled` boolean — Run the merge pass. Set False to disable without removing the config. - `centroid_cosine_threshold` number — Minimum centroid cosine similarity for a candidate merge. - `bbox_iou_threshold` number — Minimum bbox IoU on overlapping frames to satisfy the spatial half. - `scene_jaccard_threshold` number — Minimum Jaccard similarity of scene-id sets to satisfy the spatial half. - `bbox_field` string — Document-payload field holding the face bbox (list/tuple of 4 floats). - `frame_field` string — Document-payload field holding the frame identifier used to pair bboxes. - `scene_field` string — Document-payload field holding the scene identifier used for Jaccard. - `sample_size` integer, nullable — Updated per-execution document cap. Takes effect on the next `POST /v1/clusters/{id}/execute`. Omit to leave the stored value untouched; set to an integer to change it. KMeans supports up to 1M; O(N²) algorithms are capped at 100K by the engine. - `algorithm_params` object, nullable — Updated algorithm parameters (e.g. min_cluster_size, min_samples for HDBSCAN). Takes effect on the next `POST /v1/clusters/{id}/execute`. - `layout_stability` 'none' | 'transform' | 'align', nullable — Updated layout-stability mode (LS-5): 'align' keeps the map stable across runs (default behavior), 'transform' reuses the previous run's saved projection when compatible, 'none' re-layouts every run. Takes effect on the next `POST /v1/clusters/{id}/execute`. Omit to leave the stored value untouched. ## Response `200` Successful Response - ClusterModel — Cluster metadata stored in MongoDB. - `collection_ids` string[], nullable — Collections to cluster together - `cluster_name` string, nullable — Optional human-friendly name for the clustering job - `cluster_type` 'vector' | 'attribute' — Type of clustering to perform. Determines the clustering approach: - vector: Cluster documents by embedding similarity (semantic clustering) - attribute: Cluster documents by metadata attributes (business logic clustering) Use Cases: vector: - Group semantically similar content - Find content with similar meaning - Organize by topic/theme - Requires vector embeddings attribute: - Group by business attributes (category, brand, status, etc.) - Organize by explicit metadata - Create hierarchical groupings - No embeddings required - `vector_config` VectorBasedConfigOutput — Configuration for vector-based clustering. Use canonical feature URIs to specify which vector embeddings to cluster. Feature URIs follow the format: mixpeek://{extractor}@{version}/{output} Supports both single and multi-feature clustering: - Single feature: Provide one feature_uri for standard clustering - Multi-feature: Provide multiple feature_uris for hybrid clustering Examples: Single feature: { "feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding", "clustering_method": "hdbscan", "sample_size": 1000 } Multi-feature: { "feature_uris": [ "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "mixpeek://image_extractor@v1/embedding" ], "clustering_method": "hdbscan", "multi_feature_strategy": "concatenate" } - `feature_uri` string, nullable — DEPRECATED: Use feature_uris instead. Canonical feature URI for the vector embedding to cluster. Format: 'mixpeek://{extractor}@{version}/{output}'. For multi-feature clustering, use feature_uris (plural) instead. - `feature_uris` string[], nullable — RECOMMENDED. List of feature URIs to cluster. Format: 'mixpeek://{extractor}@{version}/{output}'. For single-feature clustering, provide a list with one element. For multi-feature clustering, provide multiple feature URIs. Each feature must exist in all input collections. - `clustering_method` 'kmeans' | 'dbscan' | 'hdbscan' | 'agglomerative' | 'spectral' | 'gaussian_mixture' | 'mean_shift' | 'optics' | 'leiden' | 'evoc' | 'attribute_based' | 'auto', required — Supported clustering algorithms. Two types of clustering are available: 1. Vector-based: Clusters documents by embedding similarity 2. Attribute-based: Clusters documents by metadata attributes Vector-based algorithms (require feature_vector): - kmeans: Partitions data into K clusters by minimizing within-cluster variance - dbscan: Density-based clustering, finds clusters of arbitrary shape - hdbscan: Hierarchical DBSCAN, auto-determines number of clusters - agglomerative: Hierarchical clustering using linkage criteria - spectral: Uses graph theory to find clusters - gaussian_mixture: Probabilistic model assuming Gaussian distributions - mean_shift: Finds clusters by locating density maxima - optics: Ordering points to identify clustering structure - leiden: Community detection on a kNN graph (fast at scale, auto cluster count via resolution; skips the UMAP step that dominates KMeans) - evoc: Embedding Vector Oriented Clustering (Tutte Institute) — built for embeddings, discovers the cluster count automatically, less parameter-sensitive than HDBSCAN and scales roughly linearly Attribute-based algorithm (requires attribute_config): - attribute_based: Groups documents by metadata attributes (e.g., category, brand) - `sample_size` integer, nullable — Number of samples to use for clustering. If not set, defaults are applied per algorithm to prevent out-of-memory: HDBSCAN/DBSCAN/OPTICS: 50,000 (O(N²) memory), Spectral/Agglomerative: 50,000, KMeans/GaussianMixture/MeanShift: 100,000. KMeans/GMM hard max: 1,000,000; O(N²) algorithms: 100,000. - `kmeans_parameters` union — Parameters for K-means clustering (deprecated, use algorithm_params) - KMeansParams — Parameters for K-Means clustering algorithm. - `n_clusters` integer — Number of clusters to form - `max_iter` integer — Maximum number of iterations - `random_state` integer, nullable — Random seed for reproducibility - `n_init` integer — Number of times k-means will run with different centroid seeds - `tol` number — Tolerance for convergence - `init` string — Method for initialization ('k-means++' or 'random') - `verbose` integer — Verbosity mode - `copy_x` boolean — If True, the original data is not modified - `algorithm` string — K-means algorithm to use ('lloyd', 'elkan', or 'auto') - object - `dbscan_parameters` union — Parameters for DBSCAN clustering (deprecated, use algorithm_params) - DBSCANParams — Parameters for DBSCAN clustering algorithm. - `eps` number — Maximum distance between two samples for one to be considered in the neighborhood of the other - `min_samples` integer — Number of samples in a neighborhood for a point to be considered a core point - `metric` string — Metric to use for distance computation - `metric_params` object — Additional keyword arguments for the metric function - `algorithm` string — Algorithm to compute pointwise distances and find nearest neighbors ('auto', 'ball_tree', 'kd_tree', 'brute') - `leaf_size` integer — Leaf size passed to BallTree or KDTree - `p` number — The power of the Minkowski metric to be used to calculate distance between points - `n_jobs` integer — The number of parallel jobs to run (-1 means using all processors) - object - `hdbscan_parameters` union — Parameters for HDBSCAN clustering (deprecated, use algorithm_params) - HDBSCANParams — Parameters for HDBSCAN clustering algorithm. - `min_cluster_size` integer — Minimum number of samples in a cluster - `min_samples` integer, nullable — Number of samples in a neighborhood for a point to be considered a core point. Defaults to min_cluster_size if None - `cluster_selection_epsilon` number — A distance threshold for cluster selection. Clusters below this value will be merged - `max_cluster_size` integer, nullable — Maximum number of samples in a cluster. Clusters above this size will be split - `metric` string — Metric to use for distance computation - `alpha` number — A distance scaling parameter - `cluster_selection_method` string — Method to select clusters from the condensed tree ('eom' or 'leaf') - `allow_single_cluster` boolean — Allow HDBSCAN to find only a single cluster - `prediction_data` boolean — Whether to generate extra data for predicting cluster membership - `match_reference_implementation` boolean — Whether to match the reference implementation exactly - object - `algorithm_params` union — Algorithm-specific parameters - KMeansParams — Parameters for K-Means clustering algorithm. - `n_clusters` integer — Number of clusters to form - `max_iter` integer — Maximum number of iterations - `random_state` integer, nullable — Random seed for reproducibility - `n_init` integer — Number of times k-means will run with different centroid seeds - `tol` number — Tolerance for convergence - `init` string — Method for initialization ('k-means++' or 'random') - `verbose` integer — Verbosity mode - `copy_x` boolean — If True, the original data is not modified - `algorithm` string — K-means algorithm to use ('lloyd', 'elkan', or 'auto') - DBSCANParams — Parameters for DBSCAN clustering algorithm. - `eps` number — Maximum distance between two samples for one to be considered in the neighborhood of the other - `min_samples` integer — Number of samples in a neighborhood for a point to be considered a core point - `metric` string — Metric to use for distance computation - `metric_params` object — Additional keyword arguments for the metric function - `algorithm` string — Algorithm to compute pointwise distances and find nearest neighbors ('auto', 'ball_tree', 'kd_tree', 'brute') - `leaf_size` integer — Leaf size passed to BallTree or KDTree - `p` number — The power of the Minkowski metric to be used to calculate distance between points - `n_jobs` integer — The number of parallel jobs to run (-1 means using all processors) - HDBSCANParams — Parameters for HDBSCAN clustering algorithm. - `min_cluster_size` integer — Minimum number of samples in a cluster - `min_samples` integer, nullable — Number of samples in a neighborhood for a point to be considered a core point. Defaults to min_cluster_size if None - `cluster_selection_epsilon` number — A distance threshold for cluster selection. Clusters below this value will be merged - `max_cluster_size` integer, nullable — Maximum number of samples in a cluster. Clusters above this size will be split - `metric` string — Metric to use for distance computation - `alpha` number — A distance scaling parameter - `cluster_selection_method` string — Method to select clusters from the condensed tree ('eom' or 'leaf') - `allow_single_cluster` boolean — Allow HDBSCAN to find only a single cluster - `prediction_data` boolean — Whether to generate extra data for predicting cluster membership - `match_reference_implementation` boolean — Whether to match the reference implementation exactly - AgglomerativeParams — Parameters for Agglomerative clustering algorithm. - `n_clusters` integer, nullable — Number of clusters to find. Can be None if distance_threshold is not None - `affinity` string — Metric used to compute linkage. Can be 'euclidean', 'l1', 'l2', 'manhattan', 'cosine', or 'precomputed' - `memory` string, nullable — Path to the caching directory - `connectivity` unknown - `compute_full_tree` string — Whether to compute the full tree ('auto', True, or False) - `linkage` string — Linkage criterion ('ward', 'complete', 'average', 'single') - `distance_threshold` number, nullable — The linkage distance threshold above which clusters will not be merged - `compute_distances` boolean — Whether to compute distances between clusters - SpectralParams — Parameters for Spectral clustering algorithm. - `n_clusters` integer — Number of clusters to form - `eigen_solver` string, nullable — The eigenvalue decomposition strategy ('arpack', 'lobpcg', 'amg', or None) - `n_components` integer, nullable — Number of eigenvectors to use for spectral embedding - `random_state` integer, nullable — Random seed for reproducibility - `n_init` integer — Number of times k-means will run with different centroid seeds - `gamma` number — Kernel coefficient for rbf, poly, sigmoid, laplacian and chi2 kernels - `affinity` string — How to construct the affinity matrix ('nearest_neighbors', 'rbf', 'precomputed', 'precomputed_nearest_neighbors') - `n_neighbors` integer — Number of neighbors to use when constructing the affinity matrix using nearest neighbors - `eigen_tol` number — Stopping criterion for eigendecomposition - `assign_labels` string — Strategy to assign labels in the embedding space ('kmeans' or 'discretize') - `degree` number — Degree of the polynomial kernel. Ignored by other kernels - `coef0` number — Zero coefficient for polynomial and sigmoid kernels - `kernel_params` object, nullable — Parameters for the kernel function - `n_jobs` integer — Number of parallel jobs to run (-1 means using all processors) - `verbose` boolean — Verbosity mode - GaussianMixtureParams — Parameters for Gaussian Mixture Model clustering. - `n_components` integer — Number of mixture components - `covariance_type` string — Type of covariance parameters ('full', 'tied', 'diag', 'spherical') - `tol` number — Convergence threshold - `reg_covar` number — Regularization added to the diagonal of covariance - `max_iter` integer — Maximum number of EM iterations - `n_init` integer — Number of initializations to perform - `init_params` string — Method used to initialize weights, means and covariances ('kmeans' or 'random') - `weights_init` unknown[], nullable — Initial weights - unknown - `means_init` unknown[], nullable — Initial means - unknown - `precisions_init` unknown[], nullable — Initial precisions - unknown - `random_state` integer, nullable — Random seed for reproducibility - `warm_start` boolean — If True, use the solution of the last fit as initialization - `verbose` integer — Enable verbose output - `verbose_interval` integer — Number of iterations between each verbose message - MeanShiftParams — Parameters for Mean Shift clustering algorithm. - `bandwidth` number, nullable — Bandwidth used in the RBF kernel. If None, estimated using sklearn.cluster.estimate_bandwidth - `bandwidth_quantile` number — Quantile of pairwise distances used to estimate bandwidth when bandwidth is None. sklearn's own default of 0.3 merges every cluster into one on embedding data: with k equally sized clusters only 1/k of pairs are within-cluster, so a quantile above 1/k measures the distance BETWEEN clusters. 0.1 suits up to roughly ten clusters; lower it if you expect more. - `seeds` array[], nullable — Seeds used to initialize kernels. If None, all points are used as seeds - number[] - `bin_seeding` boolean — If true, initial kernel locations are discretized into a grid to speed up algorithm - `min_bin_freq` integer — Minimum number of seeds within a bin for the bin to be considered - `cluster_all` boolean — If true, all points are clustered, even orphans. If false, orphans are given label -1 - `n_jobs` integer — Number of parallel jobs to run (-1 means using all processors) - `max_iter` integer — Maximum number of iterations per seed point before the algorithm stops - OPTICSParams — Parameters for OPTICS clustering algorithm. - `min_samples` integer — Number of samples in a neighborhood for a point to be considered a core point - `max_eps` number, nullable — Maximum distance between two samples. Default (None) means no maximum distance - `metric` string — Metric to use for distance computation - `p` number — Parameter for the Minkowski metric - `metric_params` object, nullable — Additional keyword arguments for the metric function - `cluster_method` string — Method to extract clusters ('xi' or 'dbscan') - `eps` number, nullable — Maximum distance for DBSCAN cluster extraction method - `xi` number — Minimum steepness on the reachability plot for cluster boundary (xi method) - `predecessor_correction` boolean — Correct clusters based on predecessors (xi method) - `min_cluster_size` number, nullable — Minimum number of samples in a cluster. Can be a fraction if < 1.0 - `algorithm` string — Algorithm to compute pointwise distances ('auto', 'ball_tree', 'kd_tree', 'brute') - `leaf_size` integer — Leaf size passed to BallTree or KDTree - `n_jobs` integer — Number of parallel jobs to run (-1 means using all processors) - LeidenParams — Parameters for Leiden graph community-detection clustering. - `resolution` number — Resolution for the Leiden objective. Higher values yield more, smaller communities; lower values yield fewer, larger ones. Leiden discovers the cluster count from the graph — there is no fixed n_clusters. - `n_neighbors` integer — Number of nearest neighbours per node when building the kNN graph. Larger values give a denser graph (smoother communities) at higher build cost. - `metric` string — Distance metric for kNN graph construction (cosine or euclidean). - `min_cluster_size` integer — Communities smaller than this are relabelled as noise (cluster_id -1). 0 keeps every community. - `objective_function` 'RBConfiguration' | 'modularity' | 'CPM' — Leiden quality function. RBConfiguration and CPM honour the resolution parameter; modularity ignores it. - `n_iterations` integer — Leiden optimisation passes. -1 runs until no further improvement; a small positive value (e.g. 2) is faster and usually sufficient. - `random_state` integer, nullable — Random seed for reproducible partitions. - EVoCParams — Parameters for EVoC (Embedding Vector Oriented Clustering). - `noise_level` number — How aggressively points are set aside as noise (cluster_id -1). Lower values keep more points in clusters; higher values demand denser, more confident clusters. 0.5 is a balanced default. - `base_min_cluster_size` integer — Minimum number of points for a cluster at the base layer of the cluster hierarchy. Larger values create fewer, bigger clusters. - `approx_n_clusters` integer, nullable — Optional hint for roughly how many clusters to aim for. EVoC picks the hierarchy layer closest to this count. Leave unset to let EVoC choose the granularity from the data. - `n_neighbors` integer — Number of nearest neighbours per point when building the kNN graph. Larger values give a denser graph at higher build cost. - `min_samples` integer — Number of neighbouring samples for a point to be considered a core point (density estimation, as in HDBSCAN). - `random_state` integer, nullable — Random seed for reproducible clusterings. - object - `multi_feature_strategy` 'concatenate' | 'independent' | 'weighted' — Strategy for handling multiple feature vectors: - concatenate: Combine embeddings into one vector, single clustering - independent: Run separate clustering per feature - weighted: Learn optimal feature weights - `normalize_features` boolean — Apply L2 normalization to each feature block before concatenation. Prevents feature dominance when combining different modalities. Only applies when multi_feature_strategy='concatenate'. - `feature_weights` object, nullable — Optional per-feature weights (0.0-1.0) for concatenation strategy. Keys are feature URIs, values are weights. Example: {'mixpeek://text@v1/emb': 0.7, 'mixpeek://image@v1/emb': 0.3}. Defaults to equal weights (1.0) if not specified. Only applies when multi_feature_strategy='concatenate'. If multi_feature_strategy='weighted' and this is None, weights are learned automatically using weight_learning_config. - `weight_learning_config` WeightLearningConfig — Configuration for automatic feature weight learning in multi-feature clustering. When multi_feature_strategy='weighted' and feature_weights is not provided, this configuration controls how optimal weights are automatically learned. The system tries different weight combinations and picks the one that produces the best clustering quality (measured by silhouette score, etc.). Examples: Bayesian optimization (recommended): { "method": "bayesian", "max_iterations": 20, "metric": "silhouette", "sample_size": 5000 } Grid search (exhaustive, limited to 2-3 features): { "method": "grid_search", "max_iterations": 5, "metric": "silhouette" } - `method` 'grid_search' | 'bayesian' — Weight learning method: - bayesian: Gaussian process optimization (recommended, scales to 5+ features) - grid_search: Exhaustive search (limited to 2-3 features, simpler but slower) - `max_iterations` integer — Maximum optimization iterations: - grid_search: Number of values to try per feature (total: max_iterations^n_features) - bayesian: Number of weight combinations to evaluate Recommended: 20 for bayesian, 5 for grid_search - `metric` 'silhouette' | 'davies_bouldin' | 'calinski_harabasz' — Clustering quality metric to optimize: - silhouette: Measures how similar points are to their cluster vs other clusters (range: [-1, 1], higher is better) - davies_bouldin: Ratio of within-cluster to between-cluster distances (range: [0, ∞], lower is better) - calinski_harabasz: Ratio of between-cluster to within-cluster variance (range: [0, ∞], higher is better) Recommended: silhouette (most general-purpose) - `sample_size` integer, nullable — Optional: Learn weights on a random sample (speeds up large datasets). If provided and dataset has more documents, weights are learned on sample_size random documents, then applied to full dataset. Recommended: 5000 for datasets >10k documents - `random_state` integer — Random seed for reproducibility of weight learning - `output_strategy` 'single' | 'per_feature' — Output collection creation strategy: - single: Create one collection with all feature vectors - per_feature: Create separate collections for each feature (for hierarchical taxonomies) - `effective_feature_method` 'mean' | 'median' | 'medoid' — Method for calculating cluster centroids: - mean: Average of all vectors in cluster - median: Median vector (robust to outliers) - medoid: Actual cluster member closest to centroid - `enrich_source` boolean — Whether to enrich source documents with cluster_id - `face_cluster_merge` FaceClusterMergeConfig — Configuration for the post-HDBSCAN face-identity merge pass. Enables an agglomerative merge after HDBSCAN labels are assigned but before centroid calculation. Two clusters merge when the centroid cosine meets the cosine threshold AND at least one of the spatial signals (bbox IoU on overlapping frames, scene Jaccard) also clears its threshold. Defaults target ArcFace 512d face embeddings at the brand-corpus scale (~10^4 faces, ~10^2 true identities). - `enabled` boolean — Run the merge pass. Set False to disable without removing the config. - `centroid_cosine_threshold` number — Minimum centroid cosine similarity for a candidate merge. - `bbox_iou_threshold` number — Minimum bbox IoU on overlapping frames to satisfy the spatial half. - `scene_jaccard_threshold` number — Minimum Jaccard similarity of scene-id sets to satisfy the spatial half. - `bbox_field` string — Document-payload field holding the face bbox (list/tuple of 4 floats). - `frame_field` string — Document-payload field holding the frame identifier used to pair bboxes. - `scene_field` string — Document-payload field holding the scene identifier used for Jaccard. - `preprocessing_steps` union[], nullable — Ordered list of preprocessing steps applied before clustering. Steps execute in order. Common patterns: - [whitening, umap]: Decorrelate then reduce — best for high-dimensional embeddings - [umap]: UMAP pre-reduction only (defaults: 50D, cosine, n_neighbors=30) - [whitening]: Whitening only — improves density-based clustering without dimension reduction If set, overrides any default dimensionality reduction. - union - TSNEParams - `method` 'tsne' - `n_components` integer - `random_state` integer - `perplexity` number - `learning_rate` number - UMAPParams - `method` 'umap' - `n_components` integer - `random_state` integer - `n_neighbors` integer - `min_dist` number - `metric` string — Distance metric for UMAP. 'cosine' is best for normalized embeddings. - WhiteningParams - `method` 'whitening' - `regularization` number — Eigenvalue floor to prevent division by near-zero values. - NoReduction - `method` 'none' - `hierarchical` boolean — Enable recursive sub-clustering. After initial clustering, each cluster with enough members is sub-divided using UMAP+HDBSCAN recursively. Produces hierarchical cluster IDs (e.g., cl_0_sub_1_sub_0). - `max_hierarchy_depth` integer — Maximum recursion depth for hierarchical sub-clustering. - `vis_n_components` 2 | 3 — Number of dimensions for visualization coordinates (2 or 3). When 3, the z coordinate is populated for depth/size-based rendering. Stored on the cluster and used as the default for all executions. - `layout_stability` 'none' | 'transform' | 'align', nullable — How the visualization layout behaves across re-executions (LS-5). 'align' (the default when unset): re-fit the projection as usual, then register the new layout onto the previous run's coordinates with a least-squares similarity transform computed over shared documents — the map keeps its shape and orientation, so users don't lose their bearings. 'transform': additionally reuse the previous run's saved projection reducer when compatible (same features/dimensionality), so existing documents stay pixel-stable and new documents land in the established frame; falls back to 'align', then to a raw layout. 'none': independent re-layout every run (pre-LS-5 behavior). Pure post-processing of coordinates — cluster assignments are never affected. The execution record reports what was actually applied in layout_stability_applied. - `attribute_config` AttributeBasedConfig — Configuration for attribute-based clustering. Attribute-based clustering groups documents by metadata attributes (e.g., category, brand, status) instead of vector similarity. This is useful for organizing content by business logic rather than semantic similarity. Examples: - Group products by category and brand - Organize orders by status and priority - Cluster content by author and topic - `attributes` string[], required — List of attribute field names to use for clustering. Documents will be grouped by unique combinations of these attribute values. Supports dot-notation for nested fields (e.g., 'metadata.category'). Order matters for hierarchical grouping: first attribute is top-level, subsequent are nested. - `hierarchical_grouping` boolean — Whether to create hierarchical clusters based on attribute order. When True: Creates parent clusters for each unique value of the first attribute, then child clusters for subsequent attributes within each parent. When False: Creates flat clusters for each unique combination of all attributes. Example with ['category', 'brand']: hierarchical=True → 'Electronics' (parent) → 'Apple', 'Samsung' (children). hierarchical=False → 'Electronics_Apple', 'Electronics_Samsung' (flat). - `aggregation_method` string, nullable — Method for aggregating attribute values when creating cluster centroids. Options: 'most_frequent' (default), 'first', 'last'. Most use cases should use the default. - `filters` LogicalOperatorOutput — Represents a logical operation (AND, OR, NOT) on filter conditions. Allows nesting with a defined depth limit. Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}). - `AND` union[], nullable — Logical AND operation - all conditions must be true - union - LogicalOperatorOutput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `OR` union[], nullable — Logical OR operation - at least one condition must be true - union - LogicalOperatorOutput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `NOT` union[], nullable — Logical NOT operation - all conditions must be false - union - LogicalOperatorOutput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `case_sensitive` boolean, nullable — Whether to perform case-sensitive matching - `llm_labeling` LLMLabelingOutput — Configuration for LLM-based cluster labeling. Supports multiple LLM providers with comprehensive model selection: - OpenAI: GPT-4o, GPT-4o-mini, GPT-4.1, O3-mini (best for quality) - Google: Gemini 2.5 Flash, Gemini 1.5 Flash (best for speed and cost) - Anthropic: Claude 3.5 Sonnet, Claude 3.5 Haiku (best for reasoning) All models are defined as enums and validated at API level. - `enabled` boolean — Whether to generate labels for clusters using LLM. When enabled, clusters will have semantic labels like 'High-Performance Laptops' instead of generic labels like 'Cluster 0'. - `labeling_inputs` LLMLabelingInputOutput — Input configuration for LLM-based cluster labeling. Supports flexible input mappings similar to retrievers and buckets, allowing multimodal inputs (text, images, videos, audio) for providers like Gemini that support native multimodal understanding. Examples: # Text-only labeling: LLMLabelingInput(input_mappings=[ InputMapping(input_key="headline", source_type="payload", path="headline"), InputMapping(input_key="description", source_type="payload", path="description") ]) # Multimodal labeling with images: LLMLabelingInput(input_mappings=[ InputMapping(input_key="text", source_type="payload", path="headline"), InputMapping(input_key="image_url", source_type="payload", path="thumbnail_url") ]) # Multimodal with video (for Gemini): LLMLabelingInput(input_mappings=[ InputMapping(input_key="text", source_type="payload", path="description"), InputMapping(input_key="video_url", source_type="payload", path="video_url") ]) - `input_mappings` InputMapping[], required — Flexible input mappings for constructing LLM context. Supports multimodal inputs (text, image_url, video_url, audio_url). Each mapping specifies how to extract data from document payloads. At least one input mapping is required. - `input_key` string, required — Key used in the constructed inputs payload. - `source_type` 'payload' | 'literal' | 'vector' | 'blob' — Where the value for an input should be retrieved from. - `path` string, nullable — Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback. - `override` unknown - `provider` 'openai' | 'google' | 'anthropic' — Supported LLM providers for content generation. Each provider has different strengths, pricing, and multimodal capabilities. Choose based on your use case, performance requirements, and budget. Values: OPENAI: OpenAI GPT models (GPT-4o, GPT-4.1, O3-mini) - Best for: General purpose, vision tasks, structured outputs - Multimodal: Text, images - Performance: Fast (100-500ms), reliable - Cost: Moderate to high ($0.15-$10 per 1M tokens) - Use when: Need high-quality generation with vision support GOOGLE: Google Gemini models (Gemini 3.1 Flash Lite, Gemini 2.5 Pro) - Best for: Fast generation, video understanding, cost-efficiency - Multimodal: Text, images, video, audio, PDFs - Performance: Very fast (50-200ms) - Cost: Low to moderate ($0.075-$0.40 per 1M tokens) - Use when: Need video/audio/PDF support or cost-efficiency ANTHROPIC: Anthropic Claude models (Claude 3.5 Sonnet, Claude 3.5 Haiku) - Best for: Long context, complex reasoning, safety - Multimodal: Text, images - Performance: Moderate (200-800ms) - Cost: Moderate to high ($0.25-$15 per 1M tokens) - Use when: Need long context or complex reasoning Examples: - Use OPENAI for production with structured JSON outputs - Use GOOGLE for video summarization and cost-sensitive workloads - Use ANTHROPIC for complex reasoning with long documents - `model_name` union — REQUIRED when enabled=True. Specific LLM model to use for cluster labeling. All models are defined as enums for type safety. OpenAI Models (provider='openai'): - gpt-4o-2024-08-06: Highest quality, best for production ($2.50/$10 per 1M tokens) - gpt-4o-mini-2024-07-18: Cost-effective, recommended for most use cases ($0.15/$0.60 per 1M tokens) - gpt-4.1-2025-04-14: Latest model, future-proofed - gpt-4.1-mini-2025-04-14: Latest cost-optimized model - o3-mini-2025-01-31: Advanced reasoning, best for complex clustering Google Models (provider='google'): - gemini-2.5-flash-lite: Fastest, latest multimodal model, recommended ($0.15/$0.60 per 1M tokens) Anthropic Models (provider='anthropic'): - claude-3-5-sonnet-20241022: Best reasoning, 200K context ($3/$15 per 1M tokens) - claude-3-5-haiku-20241022: Fast, cost-effective ($0.25/$1.25 per 1M tokens) Recommendation: - Use gemini-2.5-flash-lite (DEFAULT) - multimodal support - Use gpt-4o-mini-2024-07-18 for OpenAI compatibility - Use gpt-4o-2024-08-06 for highest quality when cost is not a concern - 'gpt-4o-2024-08-06' | 'gpt-4o-mini-2024-07-18' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'o3-mini-2025-01-31' — OpenAI model identifiers for LLM generation. Models listed in order of capability and cost (highest to lowest). All models support vision (images) except O3-mini. Values: GPT_4O: Latest GPT-4 Omni model (2024-08-06) - Use for: Production, highest quality generation - Context: 128K tokens - Vision: Yes - Cost: $2.50/1M input, $10/1M output - Performance: 200-500ms per request - When to use: Need best quality, willing to pay premium GPT_41: GPT-4.1 (2025-04-14) - Use for: Future-proofed pipelines - Context: 128K tokens - Vision: Yes - Cost: TBD (expected similar to GPT-4o) - When to use: Want latest model features GPT_4O_MINI: Smaller, faster GPT-4 Omni (2024-07-18) - Use for: High-volume, cost-sensitive workloads - Context: 128K tokens - Vision: Yes - Cost: $0.15/1M input, $0.60/1M output - Performance: 100-200ms per request - When to use: Good balance of quality and cost GPT_41_MINI: Smaller GPT-4.1 (2025-04-14) - Use for: Future cost-optimized pipelines - Context: 128K tokens - Vision: Yes - Cost: TBD (expected similar to GPT-4o-mini) - When to use: Want latest features at lower cost O3_MINI: Reasoning-optimized model (2025-01-31) - Use for: Complex reasoning, math, code - Context: 200K tokens - Vision: No - Cost: TBD - When to use: Need advanced reasoning capabilities Examples: - Use GPT_4O for caption generation with images (best quality) - Use GPT_4O_MINI for high-volume video scene summarization (cost-effective) - Use O3_MINI for complex entity extraction requiring reasoning - 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'gemini-3.1-flash-lite' — Google Gemini model identifiers for LLM generation. Gemini models excel at multimodal understanding with best-in-class video support. All models support text, images, video, audio, and PDFs. Values: GEMINI_2_5_FLASH_LITE: Gemini 2.5 Flash Lite model (recommended, stable GA) - Use for: Fastest generation, cost-effective multimodal - Context: 1M tokens - Multimodal: Text, images, video, audio, PDFs - When to use: Default choice for all Gemini use cases GEMINI_2_5_PRO: Gemini 2.5 Pro model - Use for: Higher quality reasoning, complex tasks - Context: 1M tokens GEMINI_2_5_FLASH: Gemini 2.5 Flash model - Kept for backward compatibility. GEMINI_3_1_FLASH_LITE: Alias for gemini-2.5-flash-lite (backwards compat) - Note: gemini-3.1-flash-lite does NOT exist in Google's API. This value is mapped to gemini-2.5-flash-lite at runtime. - 'claude-sonnet-4-5-20250929' | 'claude-haiku-4-5-20251001' | 'claude-3-5-sonnet-20241022' | 'claude-3-5-haiku-20241022' — Anthropic Claude model identifiers for LLM generation. Claude models excel at long context, complex reasoning, and safety. All models support text and images. Values: CLAUDE_3_5_SONNET: Most capable Claude model - Use for: Complex reasoning, long documents, safety-critical - Context: 200K tokens - Vision: Yes - Cost: $3/1M input, $15/1M output - Performance: 300-800ms per request - When to use: Need best reasoning, safety, or long context CLAUDE_3_5_HAIKU: Fast, cost-effective Claude model - Use for: High-volume, quick summaries - Context: 200K tokens - Vision: Yes - Cost: $0.25/1M input, $1.25/1M output - Performance: 100-300ms per request - When to use: Good balance of quality and cost Examples: - Use CLAUDE_3_5_SONNET for complex entity extraction from contracts (best reasoning) - Use CLAUDE_3_5_HAIKU for high-volume content moderation (cost-effective) - `include_summary` boolean — Whether to generate cluster summaries - `include_keywords` boolean — Whether to extract keywords for clusters - `max_samples_per_cluster` integer, nullable — Maximum representative documents to send to LLM per cluster for semantic analysis. When null (default), automatically scales based on cluster size and spread — smaller/tighter clusters get fewer samples, larger/sparser clusters get more (range 3-20). Set explicitly to override with a fixed value. - `sample_text_max_length` integer — Maximum characters per document sample text - `sample_selection_strategy` 'nearest' | 'representative' — How representative documents are chosen for the labeling LLM. 'nearest' (default): the N members closest to the cluster centroid — maximally prototypical, but adjacent clusters can yield near-identical sample sets and therefore near-identical labels. 'representative': a mixed panel of ~40% nearest-to-centroid, ~40% diversity picks (farthest-point coverage of the cluster's extent), and ~20% high-density examples — differentiates similar clusters at the same sample count and LLM cost. - `use_embedding_dedup` boolean — Enable embedding-based label deduplication to prevent near-duplicate labels (requires sentence-transformers) - `embedding_similarity_threshold` number — Cosine similarity threshold for duplicate label detection (labels above this are considered duplicates) - `cache_ttl_seconds` integer — Time-to-live for cached labels in seconds. Labels for clusters with identical representative documents will be reused within this TTL window, reducing LLM API costs. Default: 604800 (7 days). Set to 0 to disable caching. - `labeling_context` string, nullable — OPTIONAL. Freeform domain context about the data being clustered, injected into the labeling prompt as a clearly-delimited 'Domain context provided by the user' block (LS-4). Unlike custom_prompt, this does NOT replace the default prompt — it grounds the default labeler so labels use the right domain vocabulary. Example: 'These are scenes from pharmaceutical TV ads' turns generic labels like 'People Talking Outdoors' into 'Patient Testimonial Scenes'. Max 2000 characters. - `custom_prompt` string, nullable — OPTIONAL. Custom prompt template for LLM labeling. NOT REQUIRED - uses default discriminative prompt if not provided. When provided, completely replaces the default prompt. Your custom prompt receives cluster information but you must format it yourself. Use when: - Need domain-specific labeling (e.g., medical, legal, technical) - Want different label format (e.g., emoji labels, code names) - Require specific output structure - Have custom business logic for categorization Default prompt includes: cluster document samples, forbidden labels for uniqueness, and JSON response format. See engine/clusters/labeling/prompts.py for reference. Example: 'Analyze these product clusters and generate SHORT category names (2-3 words max) focusing on product type and price range. Return JSON: [{"cluster_id": "cl_0", "label": "..."}]' - `response_shape` union — OPTIONAL. Define custom structured output for LLM labeling. NOT REQUIRED - uses default structure (label, summary, keywords) if not provided. When provided, LLM output will match this structure and be stored in cluster documents. Two modes supported: 1. Natural language prompt (string): Describe desired output in plain English - Service automatically infers JSON schema from your description - Example: 'Extract cluster category, confidence score (0-1), and top 3 representative terms' - Auto-generates schema with appropriate types (string, number, array, etc.) 2. Explicit JSON schema (dict): Provide complete JSON schema for output structure - Full control over output structure, types, and constraints - Example: {'type': 'object', 'properties': {'category': {'type': 'string'}, ...}} Use when: - Need custom metadata fields (confidence scores, sentiment, complexity) - Want domain-specific structure (taxonomy hierarchies, entity extractions) - Require specific data types (arrays, nested objects, enums) - Have downstream schema requirements Output fields are automatically added to cluster collection schema and stored in metadata. Default behavior (if not provided): label (string), summary (string), keywords (array of strings) - string - object - `parameters` object — Provider-specific parameters forwarded to the LLM service. For OpenAI: temperature, max_tokens, top_p, json_output, etc. For Google: temperature, top_k, max_output_tokens, json_output, etc. - `enrich_source_collection` boolean — If True, cluster results are written back to source collection(s) in-place instead of creating new output collections. Documents will be enriched with cluster_id, cluster_label, distance_to_centroid, and optionally other metadata. Similar to taxonomy enrichment pattern. - `source_enrichment_config` SourceEnrichmentConfig — Configuration for enriching source collection documents with cluster assignments. When enrich_source_collection=True, cluster assignments are written back to the original source documents, similar to taxonomy enrichment. Uses flexible field mapping pattern to support any cluster result fields. - `field_mappings` EnrichmentFieldMapping[] — List of field mappings from cluster results to document fields. Default includes cluster_id and cluster_label. Can include: distance_to_centroid, member_count, keywords, visualization coords (x, y, z), etc. - `source_field` string, required — Field from cluster results to include. Available fields: cluster_id, cluster_label, distance_to_centroid, member_count, keywords, x, y, z (visualization coords), metadata.* - `target_field` string, required — Target field name in enriched document. Example: 'category_id' for cluster_id, 'product_category' for cluster_label - `auto_execute_on_batch` boolean — Automatically execute this cluster whenever a batch completes on any of its input collections. When True, a ClusterApplicationConfig entry is added to each input collection's cluster_applications field at creation time. The cluster will then auto-trigger after each batch completion (subject to cooldown and document threshold). When False (default), the cluster must be executed manually via the API. - `auto_execute_min_documents` integer, nullable — Minimum number of documents required before auto-executing cluster. Only used when auto_execute_on_batch=True. If the collection has fewer documents than this threshold, clustering is skipped. - `auto_execute_cooldown_seconds` integer — Minimum time (in seconds) between automatic cluster executions. Only used when auto_execute_on_batch=True. Default: 3600 (1 hour). - `cluster_id` string — Unique cluster identifier - `parquet_path` string, nullable — S3 path to parquet files with cluster data - `members_key` string, nullable — S3 key to members.parquet (if saved) - `num_clusters` integer, nullable — Number of clusters found - `cluster_stats` ClusterStats — Basic clustering quality metrics. - `num_clusters` integer, required - `noise_points` integer, nullable — Number of noise points (for DBSCAN, etc.) - `silhouette_score` number, nullable — Silhouette score (-1 to 1, higher is better) - `extra` object - `status` 'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED' | 'DEACTIVATED' — Enumeration of task statuses for tracking asynchronous operations. Task statuses indicate the current state of asynchronous operations like batch processing, object ingestion, clustering, and taxonomy execution. Status Categories: Operation Statuses: Track progress of async operations Lifecycle Statuses: Track entity state (buckets, collections, namespaces) Values: PENDING: Task is queued but has not started processing yet IN_PROGRESS: Task is currently being executed PROCESSING: Task is actively processing data (similar to IN_PROGRESS) COMPLETED: Task finished successfully with no errors COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) FAILED: Task encountered an error and could not complete CANCELED: Task was manually canceled by a user or system UNKNOWN: Task status could not be determined SKIPPED: Task was intentionally skipped DRAFT: Task is in draft state and not yet submitted ACTIVE: Entity is active and operational (for buckets, collections, etc.) ARCHIVED: Entity has been archived SUSPENDED: Entity has been temporarily suspended Terminal Statuses: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state. Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately. Polling Guidance: - Poll tasks in PENDING, QUEUED, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling - `task_id` string, nullable — Associated task ID for clustering job - `last_run_id` string, nullable — Run ID of the most recent successful clustering execution. Used to retrieve execution results. - `created_at` string, date-time — When the cluster was created - `updated_at` string, date-time — When the cluster was last updated - `metadata` object — Additional user-defined metadata for the cluster ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error --- [API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)