--- title: "Clone Taxonomy" method: POST path: "/v1/taxonomies/{taxonomy_identifier}/clone" tags: ["Taxonomies"] --- # Clone Taxonomy `POST /v1/taxonomies/{taxonomy_identifier}/clone` Clone a taxonomy with optional modifications. **Purpose:** Creates a NEW taxonomy (with new ID) based on an existing one. This is the recommended way to iterate on taxonomy designs when you need to modify core logic that PATCH doesn't allow (config, retriever_id, input_mappings). **Clone vs PATCH vs Template:** - **PATCH**: Update metadata only (name, description, metadata) - **Clone**: Copy and modify core logic (config, retriever, collections) - **Template**: Start from a pre-configured pattern (for new projects) **Common Use Cases:** - Fix configuration errors without losing join history - Change retriever or input mappings - Modify enrichment fields or collection configuration - Test modifications before replacing production taxonomy - Create variants for different datasets **How it works:** 1. Source taxonomy is copied 2. You provide a new name (REQUIRED) 3. Optionally override any other fields (description, config) 4. A new taxonomy is created with a new ID 5. Original taxonomy remains unchanged ## Path parameters - `taxonomy_identifier` string, required — Source taxonomy ID or name to clone. ## Request body - CloneTaxonomyRequest — Request to clone a taxonomy with optional modifications. **Purpose:** Cloning creates a NEW taxonomy (with new ID) based on an existing one, allowing you to make changes that aren't allowed via PATCH (config, retriever_id, collections). This is the recommended way to iterate on taxonomy designs. **Clone vs Template vs Version:** - **Clone**: Copy THIS taxonomy and modify it (for iteration/fixes) - **Template**: Create taxonomy from a reusable pattern (for new projects) - **Version**: (Not implemented) - Use clone instead **Use Cases:** - Fix configuration errors without losing join history - Change retriever or input mappings - Change target collections - Test modifications before replacing production taxonomy - Create variants for different datasets **All fields are OPTIONAL:** - Omit a field to keep the original value - Provide a field to override the original value - taxonomy_name is REQUIRED (clones must have unique names) - `taxonomy_name` string, required — REQUIRED. Name for the cloned taxonomy. Must be unique and different from the source taxonomy. - `description` string, nullable — OPTIONAL. Description override. If omitted, copies from source taxonomy. - `config` union — OPTIONAL. Override taxonomy configuration. If omitted, copies from source taxonomy. This allows you to change retriever_id, input_mappings, enrichment_fields, or collection hierarchy. - FlatTaxonomyConfigInput — Configuration for a *flat* taxonomy - single source collection with one retriever. - `taxonomy_type` 'flat' — Discriminator identifying this as a flat taxonomy. - `retriever_id` string, required — The retriever to use for matching against the source collection. - `input_mappings` InputMapping[], required — Input mappings defining how to construct retriever inputs. - `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 - `source_collection` SourceCollectionInput, required — A source collection for a flat taxonomy. - `collection_id` string, required — The ID of the source collection for the taxonomy. - `enrichment_fields` EnrichmentField[], nullable — Fields to copy from matched taxonomy node when enriching (append/replace semantics). If omitted, the full payload is copied. - `field_path` string, required — Dot-notation path of the field to copy from the taxonomy node. - `target_field` string, nullable — Optional target field name in the enriched document. If specified, the source field will be renamed to this name. If not specified, the field_path is used as the target name. Use this to rename fields during enrichment (e.g., label → visual_style). - `merge_mode` 'replace' | 'append' — How a field from the taxonomy node should be merged into the target doc. - `step_analytics` StepAnalyticsConfigInput — Configuration for step-by-step transition analytics on taxonomy assignments. Enables analysis of how documents progress through taxonomy labels as a temporal sequence, answering questions like: - How long from "inquiry" to "closed_won"? - What % of "inquiry" emails reach "proposal"? - Which sender domains correlate with faster progression? Use Cases: 1. Email Thread Analysis: - Track progression: inquiry → followup → proposal → closed_won - Identify which subject lines correlate with faster closure 2. Content Workflow Tracking: - Monitor: draft → review → approved → published - Find bottlenecks and optimization opportunities 3. Safety Compliance Monitoring: - Trace: violation_detected → investigated → resolved - Track resolution times and success rates Attributes: timestamp_field: Document field containing event timestamp sequence_id_field: Field that groups related documents into sequences step_key_source: How to extract the step identifier (label/node_id/custom field) step_key_field_path: Required if step_key_source='field_path' covariates: List of predictor variables to analyze for conversion lift max_sequence_duration_days: Filter out sequences longer than this (data quality) Example: ```python # Email thread analysis configuration StepAnalyticsConfig( timestamp_field="Date", # Email timestamp sequence_id_field="Thread-Index", # Groups emails in same thread step_key_source="assignment_label", # Use taxonomy label as step covariates=[ CovariateConfig( field_path="sender_domain", covariate_type="categorical", name="Sender Domain" ), CovariateConfig( field_path="word_count", covariate_type="numeric", name="Email Length" ) ], max_sequence_duration_days=90 # Ignore threads >90 days ) ``` - `timestamp_field` string, required — Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp') - `sequence_id_field` string, required — Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id') - `step_key_source` 'assignment_label' | 'assignment_node_id' | 'field_path' — Defines how to extract the step key from documents for sequence analysis. The step key identifies which stage/state a document is in for transition analytics. Examples: ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., "inquiry", "proposal") ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., "node_sales_inquiry") FIELD_PATH: Use a custom document field (e.g., "metadata.workflow_stage") - `step_key_field_path` string, nullable — Required if step_key_source='field_path'. Dot-notation path to step value in document. - `covariates` CovariateConfig[] — Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster) - `field_path` string, required — Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority') - `covariate_type` 'categorical' | 'numeric' | 'embedding' | 'cluster_id', required — Type of covariate/predictor variable for conversion analysis. Different types enable different analysis strategies: - CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority) - NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price) - EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings) - CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster) Examples: ```python # Categorical: Which email domains convert better? CovariateConfig(field_path="sender_domain", covariate_type="categorical") # Numeric: Do longer emails convert faster? CovariateConfig(field_path="word_count", covariate_type="numeric") # Embedding: Do visually similar images follow similar paths? CovariateConfig(field_path="features.clip", covariate_type="embedding") # Cluster: Which topic clusters have highest conversion? CovariateConfig(field_path="metadata.topic_id", covariate_type="cluster_id") ``` - `name` string, required — Human-readable name for this covariate in analytics results - `binning_strategy` 'quartiles' | 'deciles' | 'custom', nullable — How to bin numeric values for lift analysis (only used for NUMERIC type) - `clustering_method` 'kmeans' | 'hdbscan', nullable — Clustering algorithm for embedding analysis (only used for EMBEDDING type) - `n_clusters` integer, nullable — Number of clusters for embedding-based predictors (only used for EMBEDDING type) - `max_sequence_duration_days` integer, nullable — Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues. - HierarchicalTaxonomyConfigInput — Hybrid hierarchical taxonomy configuration supporting inference with manual additions. All hierarchical taxonomies are hybrid: - Base hierarchy can be inferred via schema, clustering, or LLM - Additional collections can be explicitly added with specific retrievers - Supports mixing inference strategies with manual additions/overrides Examples: 1. Pure inference: Set inference_strategy + inference_collections 2. Pure manual: Set hierarchical_nodes only 3. Hybrid: Set inference_strategy + inference_collections + hierarchical_nodes (infers base from collections, adds/overrides with explicit nodes) - `taxonomy_type` 'hierarchical' — Discriminator identifying this as a hierarchical taxonomy. - `retriever_id` string, nullable — Default retriever to use for all nodes unless overridden per-node. - `input_mappings` InputMapping[], nullable — Default input mappings for all nodes unless overridden per-node. - `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 - `inference_strategy` 'schema' | 'cluster' | 'llm' — Strategy for inferring the base hierarchy structure. Can be combined with manual overrides via hierarchical_nodes for hybrid configuration: - SCHEMA: Infer based on overlapping collection schemas - CLUSTER: Infer based on clustering algorithms and overlap detection - LLM: Infer using AI/language models - `inference_collections` string[], nullable — Collection IDs to use for hierarchy inference. The inference_strategy will analyze these collections to discover relationships. Can be combined with hierarchical_nodes for hybrid configuration. - `llm_provider` 'openai_chat_v1', nullable — LLM provider to use for hierarchy inference (default openai_chat_v1) - `llm_model` string, nullable — LLM model name (e.g., gpt-4o-mini) - `llm_prompt_template` string, nullable — Optional prompt template. Variables available: {collection_id}, {collection_name}. - `llm_sample_size` integer — Optional number of sample docs to include in prompts (0 = disabled). - `cluster_ids` string[], nullable — Cluster IDs to use for CLUSTER inference strategy - `cluster_overlap_threshold` number — Minimum overlap ratio to establish parent-child relationship between clusters - `hierarchical_nodes` HierarchicalNodeInput[], nullable — Explicit node definitions that either: 1) Define the entire hierarchy (when inference_strategy is None), 2) Add additional nodes to an inferred hierarchy, or 3) Override specific relationships in an inferred hierarchy. Supports true hybrid: infer from some collections, manually add others. - `collection_id` string, required — REQUIRED. Collection ID representing this node in the hierarchy. Must reference an existing collection containing documents for this hierarchy level. Format: 'col_' prefix followed by alphanumeric/underscore characters. Used to: Match documents against this level, identify node in path, store enrichment data. Example: 'col_executives' for executive level, 'col_products_phones' for phones category. - `parent_collection_id` string, nullable — OPTIONAL. Collection ID of the parent node in the hierarchy. When None: This is a root node (top of hierarchy). When set: References parent node's collection_id, creating parent-child relationship. Format: Same as collection_id ('col_' prefix). Used to: Build hierarchy tree, determine inheritance order, construct path arrays. Example: 'col_managers' is parent of 'col_executives', 'col_products' is parent of 'col_electronics'. Validation: Must reference a valid collection_id from another node in same taxonomy. - `label` string, nullable — OPTIONAL. Human-readable display name for this hierarchy node. Used in UI, visualizations, and taxonomy assignment results. NOT REQUIRED - When None: collection name or auto-generated label may be used. Format: Free text, typically title case, 2-50 characters. Examples: 'Executive Leadership', 'Mobile Phones', 'Engineering Team'. Can be LLM-generated or manually specified during taxonomy creation. - `summary` string, nullable — OPTIONAL. Brief description of this hierarchy level and its contents. Used for: Documentation, UI tooltips, understanding hierarchy structure. NOT REQUIRED - When None: no summary available for this node. Format: Free text, typically 1-3 sentences, up to 500 characters. Can be LLM-generated or manually provided. - `keywords` string[], nullable — OPTIONAL. Keywords or tags describing this hierarchy level. Used for: Search, filtering, categorization, LLM understanding. NOT REQUIRED - When None: no keywords defined for this node. Format: List of strings, typically 3-10 keywords per node. Can be LLM-generated from collection contents or manually specified. - `retriever_id` string, nullable — OPTIONAL. Retriever to use for matching documents at this hierarchy level. When None: Uses taxonomy-level retriever_id (inheritance from parent config). When set: Overrides taxonomy-level retriever for this specific node. Format: 'ret_' prefix followed by alphanumeric characters. Use for: Specialized matching at certain levels (e.g., face recognition for employees, semantic search for products). Must reference an existing RetrieverModel. - `enrichment_fields` EnrichmentField[], nullable — OPTIONAL. Fields to enrich into documents when they match this hierarchy level. Specifies which properties from node collection to copy to matched documents. When None: No field-level enrichment (only taxonomy assignment recorded). Format: List of EnrichmentField objects with field_path and merge_mode. Inheritance: Child nodes inherit all parent enrichment_fields plus their own. Example: executives node adds 'executive_level' on top of inherited 'employee_id', 'department'. - `field_path` string, required — Dot-notation path of the field to copy from the taxonomy node. - `target_field` string, nullable — Optional target field name in the enriched document. If specified, the source field will be renamed to this name. If not specified, the field_path is used as the target name. Use this to rename fields during enrichment (e.g., label → visual_style). - `merge_mode` 'replace' | 'append' — How a field from the taxonomy node should be merged into the target doc. - `input_mappings` InputMapping[], nullable — OPTIONAL. Custom input mappings for the retriever at this hierarchy level. Specifies how to construct retriever inputs from document features. When None: Uses taxonomy-level input_mappings (inheritance). When set: Overrides taxonomy-level mappings for this specific node. Format: List of InputMapping objects specifying input_key, source_type, path. Use for: Different matching strategies at different levels (e.g., face at employee level, text at department level). - `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 - `step_analytics` StepAnalyticsConfigInput — Configuration for step-by-step transition analytics on taxonomy assignments. Enables analysis of how documents progress through taxonomy labels as a temporal sequence, answering questions like: - How long from "inquiry" to "closed_won"? - What % of "inquiry" emails reach "proposal"? - Which sender domains correlate with faster progression? Use Cases: 1. Email Thread Analysis: - Track progression: inquiry → followup → proposal → closed_won - Identify which subject lines correlate with faster closure 2. Content Workflow Tracking: - Monitor: draft → review → approved → published - Find bottlenecks and optimization opportunities 3. Safety Compliance Monitoring: - Trace: violation_detected → investigated → resolved - Track resolution times and success rates Attributes: timestamp_field: Document field containing event timestamp sequence_id_field: Field that groups related documents into sequences step_key_source: How to extract the step identifier (label/node_id/custom field) step_key_field_path: Required if step_key_source='field_path' covariates: List of predictor variables to analyze for conversion lift max_sequence_duration_days: Filter out sequences longer than this (data quality) Example: ```python # Email thread analysis configuration StepAnalyticsConfig( timestamp_field="Date", # Email timestamp sequence_id_field="Thread-Index", # Groups emails in same thread step_key_source="assignment_label", # Use taxonomy label as step covariates=[ CovariateConfig( field_path="sender_domain", covariate_type="categorical", name="Sender Domain" ), CovariateConfig( field_path="word_count", covariate_type="numeric", name="Email Length" ) ], max_sequence_duration_days=90 # Ignore threads >90 days ) ``` - `timestamp_field` string, required — Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp') - `sequence_id_field` string, required — Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id') - `step_key_source` 'assignment_label' | 'assignment_node_id' | 'field_path' — Defines how to extract the step key from documents for sequence analysis. The step key identifies which stage/state a document is in for transition analytics. Examples: ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., "inquiry", "proposal") ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., "node_sales_inquiry") FIELD_PATH: Use a custom document field (e.g., "metadata.workflow_stage") - `step_key_field_path` string, nullable — Required if step_key_source='field_path'. Dot-notation path to step value in document. - `covariates` CovariateConfig[] — Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster) - `field_path` string, required — Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority') - `covariate_type` 'categorical' | 'numeric' | 'embedding' | 'cluster_id', required — Type of covariate/predictor variable for conversion analysis. Different types enable different analysis strategies: - CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority) - NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price) - EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings) - CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster) Examples: ```python # Categorical: Which email domains convert better? CovariateConfig(field_path="sender_domain", covariate_type="categorical") # Numeric: Do longer emails convert faster? CovariateConfig(field_path="word_count", covariate_type="numeric") # Embedding: Do visually similar images follow similar paths? CovariateConfig(field_path="features.clip", covariate_type="embedding") # Cluster: Which topic clusters have highest conversion? CovariateConfig(field_path="metadata.topic_id", covariate_type="cluster_id") ``` - `name` string, required — Human-readable name for this covariate in analytics results - `binning_strategy` 'quartiles' | 'deciles' | 'custom', nullable — How to bin numeric values for lift analysis (only used for NUMERIC type) - `clustering_method` 'kmeans' | 'hdbscan', nullable — Clustering algorithm for embedding analysis (only used for EMBEDDING type) - `n_clusters` integer, nullable — Number of clusters for embedding-based predictors (only used for EMBEDDING type) - `max_sequence_duration_days` integer, nullable — Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues. ## Response `201` Successful Response - CloneTaxonomyResponse — Response after cloning a taxonomy. - `taxonomy` TaxonomyModelOutput, required — Primary Pydantic model representing a taxonomy definition. - `taxonomy_id` string — Unique identifier for the taxonomy - `version` integer — Monotonic version number of the taxonomy configuration - `taxonomy_name` string, required — A unique name for the taxonomy within the namespace. - `description` string, nullable — Optional human-readable description. - `retriever_id` string, nullable — Optional taxonomy-level retriever (prefer per-layer). - `input_mappings` InputMapping[], nullable — Optional taxonomy-level inputs (prefer per-layer). - `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 - `config` union, required — Configuration specific to the taxonomy type. - FlatTaxonomyConfigOutput — Configuration for a *flat* taxonomy - single source collection with one retriever. - `taxonomy_type` 'flat' — Discriminator identifying this as a flat taxonomy. - `retriever_id` string, required — The retriever to use for matching against the source collection. - `input_mappings` InputMapping[], required — Input mappings defining how to construct retriever inputs. - `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 - `source_collection` SourceCollectionOutput, required — A source collection for a flat taxonomy. - `collection_id` string, required — The ID of the source collection for the taxonomy. - `enrichment_fields` EnrichmentField[], nullable — Fields to copy from matched taxonomy node when enriching (append/replace semantics). If omitted, the full payload is copied. - `field_path` string, required — Dot-notation path of the field to copy from the taxonomy node. - `target_field` string, nullable — Optional target field name in the enriched document. If specified, the source field will be renamed to this name. If not specified, the field_path is used as the target name. Use this to rename fields during enrichment (e.g., label → visual_style). - `merge_mode` 'replace' | 'append' — How a field from the taxonomy node should be merged into the target doc. - `step_analytics` StepAnalyticsConfigOutput — Configuration for step-by-step transition analytics on taxonomy assignments. Enables analysis of how documents progress through taxonomy labels as a temporal sequence, answering questions like: - How long from "inquiry" to "closed_won"? - What % of "inquiry" emails reach "proposal"? - Which sender domains correlate with faster progression? Use Cases: 1. Email Thread Analysis: - Track progression: inquiry → followup → proposal → closed_won - Identify which subject lines correlate with faster closure 2. Content Workflow Tracking: - Monitor: draft → review → approved → published - Find bottlenecks and optimization opportunities 3. Safety Compliance Monitoring: - Trace: violation_detected → investigated → resolved - Track resolution times and success rates Attributes: timestamp_field: Document field containing event timestamp sequence_id_field: Field that groups related documents into sequences step_key_source: How to extract the step identifier (label/node_id/custom field) step_key_field_path: Required if step_key_source='field_path' covariates: List of predictor variables to analyze for conversion lift max_sequence_duration_days: Filter out sequences longer than this (data quality) Example: ```python # Email thread analysis configuration StepAnalyticsConfig( timestamp_field="Date", # Email timestamp sequence_id_field="Thread-Index", # Groups emails in same thread step_key_source="assignment_label", # Use taxonomy label as step covariates=[ CovariateConfig( field_path="sender_domain", covariate_type="categorical", name="Sender Domain" ), CovariateConfig( field_path="word_count", covariate_type="numeric", name="Email Length" ) ], max_sequence_duration_days=90 # Ignore threads >90 days ) ``` - `timestamp_field` string, required — Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp') - `sequence_id_field` string, required — Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id') - `step_key_source` 'assignment_label' | 'assignment_node_id' | 'field_path' — Defines how to extract the step key from documents for sequence analysis. The step key identifies which stage/state a document is in for transition analytics. Examples: ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., "inquiry", "proposal") ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., "node_sales_inquiry") FIELD_PATH: Use a custom document field (e.g., "metadata.workflow_stage") - `step_key_field_path` string, nullable — Required if step_key_source='field_path'. Dot-notation path to step value in document. - `covariates` CovariateConfig[] — Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster) - `field_path` string, required — Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority') - `covariate_type` 'categorical' | 'numeric' | 'embedding' | 'cluster_id', required — Type of covariate/predictor variable for conversion analysis. Different types enable different analysis strategies: - CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority) - NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price) - EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings) - CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster) Examples: ```python # Categorical: Which email domains convert better? CovariateConfig(field_path="sender_domain", covariate_type="categorical") # Numeric: Do longer emails convert faster? CovariateConfig(field_path="word_count", covariate_type="numeric") # Embedding: Do visually similar images follow similar paths? CovariateConfig(field_path="features.clip", covariate_type="embedding") # Cluster: Which topic clusters have highest conversion? CovariateConfig(field_path="metadata.topic_id", covariate_type="cluster_id") ``` - `name` string, required — Human-readable name for this covariate in analytics results - `binning_strategy` 'quartiles' | 'deciles' | 'custom', nullable — How to bin numeric values for lift analysis (only used for NUMERIC type) - `clustering_method` 'kmeans' | 'hdbscan', nullable — Clustering algorithm for embedding analysis (only used for EMBEDDING type) - `n_clusters` integer, nullable — Number of clusters for embedding-based predictors (only used for EMBEDDING type) - `max_sequence_duration_days` integer, nullable — Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues. - HierarchicalTaxonomyConfigOutput — Hybrid hierarchical taxonomy configuration supporting inference with manual additions. All hierarchical taxonomies are hybrid: - Base hierarchy can be inferred via schema, clustering, or LLM - Additional collections can be explicitly added with specific retrievers - Supports mixing inference strategies with manual additions/overrides Examples: 1. Pure inference: Set inference_strategy + inference_collections 2. Pure manual: Set hierarchical_nodes only 3. Hybrid: Set inference_strategy + inference_collections + hierarchical_nodes (infers base from collections, adds/overrides with explicit nodes) - `taxonomy_type` 'hierarchical' — Discriminator identifying this as a hierarchical taxonomy. - `retriever_id` string, nullable — Default retriever to use for all nodes unless overridden per-node. - `input_mappings` InputMapping[], nullable — Default input mappings for all nodes unless overridden per-node. - `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 - `inference_strategy` 'schema' | 'cluster' | 'llm' — Strategy for inferring the base hierarchy structure. Can be combined with manual overrides via hierarchical_nodes for hybrid configuration: - SCHEMA: Infer based on overlapping collection schemas - CLUSTER: Infer based on clustering algorithms and overlap detection - LLM: Infer using AI/language models - `inference_collections` string[], nullable — Collection IDs to use for hierarchy inference. The inference_strategy will analyze these collections to discover relationships. Can be combined with hierarchical_nodes for hybrid configuration. - `llm_provider` 'openai_chat_v1', nullable — LLM provider to use for hierarchy inference (default openai_chat_v1) - `llm_model` string, nullable — LLM model name (e.g., gpt-4o-mini) - `llm_prompt_template` string, nullable — Optional prompt template. Variables available: {collection_id}, {collection_name}. - `llm_sample_size` integer — Optional number of sample docs to include in prompts (0 = disabled). - `cluster_ids` string[], nullable — Cluster IDs to use for CLUSTER inference strategy - `cluster_overlap_threshold` number — Minimum overlap ratio to establish parent-child relationship between clusters - `hierarchical_nodes` HierarchicalNodeOutput[], nullable — Explicit node definitions that either: 1) Define the entire hierarchy (when inference_strategy is None), 2) Add additional nodes to an inferred hierarchy, or 3) Override specific relationships in an inferred hierarchy. Supports true hybrid: infer from some collections, manually add others. - `collection_id` string, required — REQUIRED. Collection ID representing this node in the hierarchy. Must reference an existing collection containing documents for this hierarchy level. Format: 'col_' prefix followed by alphanumeric/underscore characters. Used to: Match documents against this level, identify node in path, store enrichment data. Example: 'col_executives' for executive level, 'col_products_phones' for phones category. - `parent_collection_id` string, nullable — OPTIONAL. Collection ID of the parent node in the hierarchy. When None: This is a root node (top of hierarchy). When set: References parent node's collection_id, creating parent-child relationship. Format: Same as collection_id ('col_' prefix). Used to: Build hierarchy tree, determine inheritance order, construct path arrays. Example: 'col_managers' is parent of 'col_executives', 'col_products' is parent of 'col_electronics'. Validation: Must reference a valid collection_id from another node in same taxonomy. - `label` string, nullable — OPTIONAL. Human-readable display name for this hierarchy node. Used in UI, visualizations, and taxonomy assignment results. NOT REQUIRED - When None: collection name or auto-generated label may be used. Format: Free text, typically title case, 2-50 characters. Examples: 'Executive Leadership', 'Mobile Phones', 'Engineering Team'. Can be LLM-generated or manually specified during taxonomy creation. - `summary` string, nullable — OPTIONAL. Brief description of this hierarchy level and its contents. Used for: Documentation, UI tooltips, understanding hierarchy structure. NOT REQUIRED - When None: no summary available for this node. Format: Free text, typically 1-3 sentences, up to 500 characters. Can be LLM-generated or manually provided. - `keywords` string[], nullable — OPTIONAL. Keywords or tags describing this hierarchy level. Used for: Search, filtering, categorization, LLM understanding. NOT REQUIRED - When None: no keywords defined for this node. Format: List of strings, typically 3-10 keywords per node. Can be LLM-generated from collection contents or manually specified. - `retriever_id` string, nullable — OPTIONAL. Retriever to use for matching documents at this hierarchy level. When None: Uses taxonomy-level retriever_id (inheritance from parent config). When set: Overrides taxonomy-level retriever for this specific node. Format: 'ret_' prefix followed by alphanumeric characters. Use for: Specialized matching at certain levels (e.g., face recognition for employees, semantic search for products). Must reference an existing RetrieverModel. - `enrichment_fields` EnrichmentField[], nullable — OPTIONAL. Fields to enrich into documents when they match this hierarchy level. Specifies which properties from node collection to copy to matched documents. When None: No field-level enrichment (only taxonomy assignment recorded). Format: List of EnrichmentField objects with field_path and merge_mode. Inheritance: Child nodes inherit all parent enrichment_fields plus their own. Example: executives node adds 'executive_level' on top of inherited 'employee_id', 'department'. - `field_path` string, required — Dot-notation path of the field to copy from the taxonomy node. - `target_field` string, nullable — Optional target field name in the enriched document. If specified, the source field will be renamed to this name. If not specified, the field_path is used as the target name. Use this to rename fields during enrichment (e.g., label → visual_style). - `merge_mode` 'replace' | 'append' — How a field from the taxonomy node should be merged into the target doc. - `input_mappings` InputMapping[], nullable — OPTIONAL. Custom input mappings for the retriever at this hierarchy level. Specifies how to construct retriever inputs from document features. When None: Uses taxonomy-level input_mappings (inheritance). When set: Overrides taxonomy-level mappings for this specific node. Format: List of InputMapping objects specifying input_key, source_type, path. Use for: Different matching strategies at different levels (e.g., face at employee level, text at department level). - `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 - `step_analytics` StepAnalyticsConfigOutput — Configuration for step-by-step transition analytics on taxonomy assignments. Enables analysis of how documents progress through taxonomy labels as a temporal sequence, answering questions like: - How long from "inquiry" to "closed_won"? - What % of "inquiry" emails reach "proposal"? - Which sender domains correlate with faster progression? Use Cases: 1. Email Thread Analysis: - Track progression: inquiry → followup → proposal → closed_won - Identify which subject lines correlate with faster closure 2. Content Workflow Tracking: - Monitor: draft → review → approved → published - Find bottlenecks and optimization opportunities 3. Safety Compliance Monitoring: - Trace: violation_detected → investigated → resolved - Track resolution times and success rates Attributes: timestamp_field: Document field containing event timestamp sequence_id_field: Field that groups related documents into sequences step_key_source: How to extract the step identifier (label/node_id/custom field) step_key_field_path: Required if step_key_source='field_path' covariates: List of predictor variables to analyze for conversion lift max_sequence_duration_days: Filter out sequences longer than this (data quality) Example: ```python # Email thread analysis configuration StepAnalyticsConfig( timestamp_field="Date", # Email timestamp sequence_id_field="Thread-Index", # Groups emails in same thread step_key_source="assignment_label", # Use taxonomy label as step covariates=[ CovariateConfig( field_path="sender_domain", covariate_type="categorical", name="Sender Domain" ), CovariateConfig( field_path="word_count", covariate_type="numeric", name="Email Length" ) ], max_sequence_duration_days=90 # Ignore threads >90 days ) ``` - `timestamp_field` string, required — Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp') - `sequence_id_field` string, required — Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id') - `step_key_source` 'assignment_label' | 'assignment_node_id' | 'field_path' — Defines how to extract the step key from documents for sequence analysis. The step key identifies which stage/state a document is in for transition analytics. Examples: ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., "inquiry", "proposal") ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., "node_sales_inquiry") FIELD_PATH: Use a custom document field (e.g., "metadata.workflow_stage") - `step_key_field_path` string, nullable — Required if step_key_source='field_path'. Dot-notation path to step value in document. - `covariates` CovariateConfig[] — Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster) - `field_path` string, required — Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority') - `covariate_type` 'categorical' | 'numeric' | 'embedding' | 'cluster_id', required — Type of covariate/predictor variable for conversion analysis. Different types enable different analysis strategies: - CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority) - NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price) - EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings) - CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster) Examples: ```python # Categorical: Which email domains convert better? CovariateConfig(field_path="sender_domain", covariate_type="categorical") # Numeric: Do longer emails convert faster? CovariateConfig(field_path="word_count", covariate_type="numeric") # Embedding: Do visually similar images follow similar paths? CovariateConfig(field_path="features.clip", covariate_type="embedding") # Cluster: Which topic clusters have highest conversion? CovariateConfig(field_path="metadata.topic_id", covariate_type="cluster_id") ``` - `name` string, required — Human-readable name for this covariate in analytics results - `binning_strategy` 'quartiles' | 'deciles' | 'custom', nullable — How to bin numeric values for lift analysis (only used for NUMERIC type) - `clustering_method` 'kmeans' | 'hdbscan', nullable — Clustering algorithm for embedding analysis (only used for EMBEDDING type) - `n_clusters` integer, nullable — Number of clusters for embedding-based predictors (only used for EMBEDDING type) - `max_sequence_duration_days` integer, nullable — Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues. - `ready` boolean — Whether the taxonomy is ready for use. False for async inference (cluster/LLM) that needs processing. True for flat/explicit hierarchies. - `created_at` string, date-time — Creation timestamp for this taxonomy record - `metadata` object — Additional user-defined metadata for the taxonomy - `source_taxonomy_id` string, required — ID of the source taxonomy that was cloned. ## 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/revisions/1c7f31821424/schema)