docs: Add nested splits feature documentation

changelog/plugins/20250501-nested-splits.mdx

@@ -0,0 +1,34 @@
+---
+title: "Nested Splits Support"
+description: "Enhanced data transformation with nested splits"
+---
+
+# Nested Splits Support
+
+> **Note:** This feature is currently for internal use only and is not customer-facing.
+
+**May 1, 2025**
+
+We're excited to announce support for nested splits in Flatfile's data transformation capabilities. This feature enhances the platform's ability to handle complex data transformations by tracking mapping rules server-side and enabling reference to previewed data in agent tool calls.
+
+## Key Improvements
+
+- **Server-side mapping rules**: Mapping rules are now tracked server-side, allowing for more complex transformations
+- **Previewed data reference**: Agent tool calls can now reference data that has been previewed through previous transformations
+- **Enhanced split functionality**: The split tool now supports nested operations where one split can build upon another
+- **Improved data transformation workflow**: Create multi-stage data transformations with preserved context
+
+## Use Cases
+
+Nested splits are particularly useful for:
+
+- Complex address parsing (splitting an address into components, then further splitting those components)
+- Name parsing with multiple levels of detail
+- Date and time processing with hierarchical transformations
+- Any scenario requiring sequential, dependent data transformations
+
+## Implementation
+
+The nested splits functionality is available through the preprocessing service and can be accessed using the split tool. For detailed implementation guidance, see our [Nested Splits guide](/learning-center/guides/nested-splits).
+
+This enhancement significantly expands Flatfile's data transformation capabilities, enabling more sophisticated data processing workflows that were previously difficult to implement.

learning-center/guides/list.mdx

@@ -15,9 +15,6 @@ mode: "wide"
   >
     Create additional fields on the fly during data import.
   </Card>
-  <Card title="Advanced Filters" icon="filter" href="./advanced-filters">
-    Filter data with complex conditions and combinations.
-  </Card>
   <Card title="Leverage AI transformations" icon="microchip-ai" href="./ai">
     Use AI Assist to make bulk edits to your data efficiently and accurately.
   </Card>
@@ -69,15 +66,15 @@ mode: "wide"
   <Card title="Multi-Part Jobs" icon="puzzle" href="./multi-part_jobs">
     Split up Jobs into Parts for better management.
   </Card>
+  <Card title="Nested Splits" icon="code-branch" href="./nested-splits">
+    Split data into multiple fields with nested transformations.
+  </Card>
   <Card title="Scoping with Namespaces" icon="filter-list" href="./namespaces">
     Narrow down the scope of Spaces, Workbooks, and Sheets.
   </Card>
   <Card title="Share secrets" icon="user-secret" href="./secrets">
     Securely use credentials in listeners.
   </Card>
-  <Card title="Space Restore" icon="clock-rotate-left" href="./space-restore">
-    Restore a space to a previous point in time.
-  </Card>
   <Card title="Theme your Space" icon="palette" href="./theming">
     Customize the look and feel of Flatfile to match your brand.
   </Card>

learning-center/guides/nested-splits.mdx

@@ -0,0 +1,123 @@
+---
+title: "Nested Splits"
+description: "Split data into multiple fields with nested transformations"
+icon: "code-branch"
+---
+
+# Nested Splits
+
+> **Note:** This feature is currently for internal use only and is not customer-facing.
+
+Flatfile's split functionality allows you to transform a single field into multiple destination fields. With the introduction of nested splits, you can now create more complex transformations by referencing previewed data in agent tool calls.
+
+## Overview
+
+Nested splits enhance Flatfile's data transformation capabilities by:
+
+1. Tracking mapping rules server-side
+2. Enabling reference to previewed data in agent tool calls
+3. Supporting complex, multi-level data transformations
+4. Preserving transformation context across operations
+
+This feature is particularly useful when you need to perform sequential transformations on your data, where later transformations depend on the results of earlier ones.
+
+## How Nested Splits Work
+
+When you use the split tool in Flatfile, the system now:
+
+1. Stores the mapping rules on the server
+2. Makes these rules available to subsequent agent tool calls
+3. Allows agents to reference the transformed data
+4. Maintains the relationship between source and transformed data
+
+## Using Nested Splits
+
+Nested splits are available through the preprocessing service and can be accessed using the split tool. Here's how to implement nested splits in your data transformation workflow:
+
+### Basic Split Operation
+
+A basic split operation transforms a single source field into multiple destination fields:
+
+```javascript
+// Example of a basic split operation
+const splitResult = await generateSplit(
+  sourceField,      // The field to split
+  data,             // Sample data from the field
+  fieldNames,       // Destination field names
+  prompt            // Optional user instructions
+);
+```
+
+### Nested Split Operation
+
+With nested splits, you can now reference the results of previous splits in subsequent transformations:
+
+```javascript
+// First split operation
+const firstSplitResult = await generateSplit(
+  sourceField,
+  data,
+  initialFieldNames,
+  prompt
+);
+
+// Second split operation that references results from the first
+const secondSplitResult = await generateSplit(
+  firstSplitResult.data.rule.destinationFields[0], // Reference a field created by the first split
+  transformedData,
+  secondaryFieldNames,
+  additionalPrompt
+);
+```
+
+## Example Use Cases
+
+### Address Parsing
+
+Split a full address into components, then further split the street address:
+
+1. First split: "123 Main St, Apt 4, New York, NY 10001" → ["123 Main St, Apt 4", "New York", "NY", "10001"]
+2. Nested split: "123 Main St, Apt 4" → ["123", "Main St", "Apt 4"]
+
+### Name Parsing
+
+Split a full name, then further process components:
+
+1. First split: "Dr. John A. Smith Jr." → ["Dr.", "John A.", "Smith", "Jr."]
+2. Nested split: "John A." → ["John", "A."]
+
+### Date and Time Processing
+
+Split a datetime stamp, then further process the date:
+
+1. First split: "2025-05-01 14:30:45" → ["2025-05-01", "14:30:45"]
+2. Nested split: "2025-05-01" → ["2025", "05", "01"]
+
+## Implementation Details
+
+The nested splits functionality is implemented in the preprocessing service and leverages several key components:
+
+1. **Mapping Rules**: Rules are now tracked server-side and can be referenced in subsequent operations
+2. **Virtual Machine**: Processes the mapping rules and applies them to the data
+3. **Run Class**: Manages the application of mapping rules to the data
+4. **Split Tool**: Provides the interface for creating split operations
+
+## Best Practices
+
+When working with nested splits:
+
+1. **Plan Your Transformation Chain**: Map out the sequence of splits before implementation
+2. **Use Descriptive Field Names**: Clear naming helps track the transformation flow
+3. **Validate Intermediate Results**: Check the output of each split before proceeding
+4. **Consider Performance**: Complex nested operations may impact processing time
+5. **Test with Sample Data**: Verify transformations with representative data samples
+
+## Limitations
+
+- Deeply nested splits (more than 3-4 levels) may become difficult to manage
+- Performance may be affected with very large datasets and complex transformations
+- All splits in a chain must be defined within the same agent session
+
+## Conclusion
+
+Nested splits significantly enhance Flatfile's data transformation capabilities, allowing for more sophisticated data processing workflows. By tracking mapping rules server-side and enabling reference to previewed data, you can create powerful, multi-stage data transformations that were previously difficult to implement.