feat: Add index serialization and complete API migration

This commit completes the Python bindings migration by:

1. Adding Index Serialization Support:
   - Added serialize() method to save AutocompleteIndex to bytes
   - Added deserialize() static method to restore from bytes
   - Enables persistent caching for faster application startup
   - Useful for production deployments with large indices

2. API Migration Improvements:
   - Migrated replace_with_links() to use load_thesaurus_from_json_and_replace()
   - Removed duplicate code and unnecessary thesaurus allocation
   - Better alignment with Rust API design
   - Improved performance through direct function calls

3. Comprehensive Testing:
   - Added TestSerialization class with 3 test cases
   - Tests verify roundtrip preservation of data
   - Tests confirm deserialized indices work correctly
   - Brings total test count to 41 (from 38)

4. Type Safety:
   - Updated type stubs with serialize/deserialize signatures
   - Full IDE support for new caching functionality
   - Clear documentation with usage examples

Benefits:
- Production-ready caching for autocomplete indices
- Reduced application startup time (load from cache vs rebuild)
- Complete feature parity with Rust API
- Better code maintainability through function reuse

Example Usage:
```python
# Build once, cache for reuse
index = build_index(large_thesaurus)
with open("cache.bin", "wb") as f:
    f.write(index.serialize())

# Fast startup - load from cache
with open("cache.bin", "rb") as f:
    index = AutocompleteIndex.deserialize(f.read())
```

Author: claude

crates/terraphim_automata_py/python/terraphim_automata/__init__.pyi

@@ -86,6 +86,41 @@ class AutocompleteIndex:
         """
         ...
 
+    def serialize(self) -> bytes:
+        """
+        Serialize the index to bytes for caching
+
+        Returns:
+            Bytes representation of the index
+
+        Example:
+            >>> index = build_index(thesaurus_json)
+            >>> data = index.serialize()
+            >>> # Save to file
+            >>> with open("index.bin", "wb") as f:
+            ...     f.write(data)
+        """
+        ...
+
+    @staticmethod
+    def deserialize(data: bytes) -> "AutocompleteIndex":
+        """
+        Deserialize an index from bytes
+
+        Args:
+            data: Bytes representation of the index
+
+        Returns:
+            AutocompleteIndex object
+
+        Example:
+            >>> # Load from file
+            >>> with open("index.bin", "rb") as f:
+            ...     data = f.read()
+            >>> index = AutocompleteIndex.deserialize(data)
+        """
+        ...
+
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
 

crates/terraphim_automata_py/python/tests/test_autocomplete.py

@@ -189,6 +189,65 @@ def test_fuzzy_search_max_results(self, index):
         assert len(results) <= 2
 
 
+class TestSerialization:
+    """Test index serialization and deserialization"""
+
+    def test_serialize_and_deserialize(self, index):
+        """Test that an index can be serialized and deserialized"""
+        from terraphim_automata import AutocompleteIndex
+
+        # Serialize the index
+        serialized = index.serialize()
+        assert isinstance(serialized, bytes)
+        assert len(serialized) > 0
+
+        # Deserialize to a new index
+        deserialized = AutocompleteIndex.deserialize(serialized)
+        assert deserialized.name == index.name
+        assert len(deserialized) == len(index)
+
+    def test_deserialized_index_works(self, index):
+        """Test that a deserialized index works correctly"""
+        from terraphim_automata import AutocompleteIndex
+
+        # Serialize and deserialize
+        serialized = index.serialize()
+        deserialized = AutocompleteIndex.deserialize(serialized)
+
+        # Test search works on both
+        original_results = index.search("machine")
+        deserialized_results = deserialized.search("machine")
+
+        assert len(original_results) == len(deserialized_results)
+        for orig, deser in zip(original_results, deserialized_results):
+            assert orig.term == deser.term
+            assert orig.id == deser.id
+
+    def test_roundtrip_preserves_data(self):
+        """Test that serialize->deserialize preserves all data"""
+        from terraphim_automata import AutocompleteIndex
+
+        # Build a small index
+        thesaurus = """{
+            "name": "Test",
+            "data": {
+                "test term": {"id": 42, "nterm": "test", "url": "https://example.com"}
+            }
+        }"""
+        original = build_index(thesaurus)
+
+        # Serialize and deserialize
+        serialized = original.serialize()
+        restored = AutocompleteIndex.deserialize(serialized)
+
+        # Verify data is preserved
+        results = restored.search("test")
+        assert len(results) == 1
+        assert results[0].term == "test term"
+        assert results[0].id == 42
+        assert results[0].url == "https://example.com"
+
+
 class TestErrorHandling:
     """Test error handling"""
 

crates/terraphim_automata_py/src/lib.rs

@@ -1,9 +1,9 @@
 use pyo3::prelude::*;
 use pyo3::exceptions::{PyValueError, PyRuntimeError};
 use ::terraphim_automata::autocomplete::{
-    autocomplete_search, build_autocomplete_index, fuzzy_autocomplete_search,
-    fuzzy_autocomplete_search_levenshtein, AutocompleteConfig, AutocompleteIndex,
-    AutocompleteResult,
+    autocomplete_search, build_autocomplete_index, deserialize_autocomplete_index,
+    fuzzy_autocomplete_search, fuzzy_autocomplete_search_levenshtein, serialize_autocomplete_index,
+    AutocompleteConfig, AutocompleteIndex, AutocompleteResult,
 };
 use ::terraphim_automata::matcher::{
     extract_paragraphs_from_automata, find_matches, LinkType, Matched,
@@ -185,6 +185,42 @@ impl PyAutocompleteIndex {
         Ok(results.into_iter().map(PyAutocompleteResult::from).collect())
     }
 
+    /// Serialize the index to bytes for caching
+    ///
+    /// Returns:
+    ///     Bytes representation of the index
+    ///
+    /// Example:
+    ///     >>> index = build_index(thesaurus_json)
+    ///     >>> data = index.serialize()
+    ///     >>> # Save to file
+    ///     >>> with open("index.bin", "wb") as f:
+    ///     ...     f.write(data)
+    fn serialize(&self) -> PyResult<Vec<u8>> {
+        serialize_autocomplete_index(&self.inner)
+            .map_err(|e| PyRuntimeError::new_err(format!("Failed to serialize index: {}", e)))
+    }
+
+    /// Deserialize an index from bytes
+    ///
+    /// Args:
+    ///     data: Bytes representation of the index
+    ///
+    /// Returns:
+    ///     AutocompleteIndex object
+    ///
+    /// Example:
+    ///     >>> # Load from file
+    ///     >>> with open("index.bin", "rb") as f:
+    ///     ...     data = f.read()
+    ///     >>> index = AutocompleteIndex.deserialize(data)
+    #[staticmethod]
+    fn deserialize(data: &[u8]) -> PyResult<PyAutocompleteIndex> {
+        let index = deserialize_autocomplete_index(data)
+            .map_err(|e| PyRuntimeError::new_err(format!("Failed to deserialize index: {}", e)))?;
+        Ok(PyAutocompleteIndex { inner: index })
+    }
+
     fn __repr__(&self) -> String {
         format!(
             "AutocompleteIndex(name='{}', len={})",