fix: improve error messages for unsupported index configurations

[Junio243]

Problem

Fixes #78

Currently, when users attempt to create indexes with unsupported metric/data type combinations (e.g., cosine metric with INT8 vectors) or call optimize() on collections with unsupported index configurations, they receive generic RuntimeError exceptions from the C++ core with minimal context:

• Scenario 1: Creating HNSW/IVF/Flat indexes on INT8 vector fields with MetricType.COSINE fails with:

  AssertionError: result=[{"code":8, "message":"Create vector column indexer failed: vector_int8_field"}]
  

• Scenario 2: Calling collection.optimize() on IVF indexes with cosine metric fails with:

  RuntimeError: Failed to merge index
  

These error messages don't explain:

• Why the operation failed
• What combination is unsupported
• How to fix it

Root Cause

The Python wrapper in python/zvec/model/collection.py directly calls C++ methods (self._obj.CreateIndex and self._obj.Optimize) without catching or enriching the errors, resulting in cryptic messages that don't help users diagnose the issue.

Solution

This PR improves error handling in the Python layer to provide clearer, more actionable error messages:

Changes Made

1. Enhanced create_index() method:

   • Wrapped self._obj.CreateIndex() in a try-except block
   • Catches RuntimeError from C++ and re-raises with detailed context
   • Updated docstring to document known limitations (e.g., cosine with INT8)
   • Added explicit RuntimeError to the Raises section

2. Enhanced optimize() method:

   • Wrapped self._obj.Optimize() in a try-except block
   • Catches RuntimeError and provides contextual information
   • Added RuntimeError to the Raises section in docstring

Example Error Messages

Before (cryptic):

RuntimeError: Create vector column indexer failed: vector_int8_field

After (informative):

RuntimeError: Failed to create index on vector field 'vector_int8_field' with HnswIndexParam. 
This may occur when using a metric or data type that is not yet supported for this index type. 
Original error: Create vector column indexer failed: vector_int8_field

Before (for optimize):

RuntimeError: Failed to merge index

After:

RuntimeError: Failed to optimize collection at './my_collection'. 
This may be triggered by unsupported index configurations or metrics. 
Original error: Failed to merge index

Benefits

• ✅ Better Developer Experience: Users immediately understand the problem is a limitation, not a bug in their code
• ✅ Clearer Debugging: Error messages include field name, index type, and possible causes
• ✅ Documentation: Updated docstrings warn about known limitations
• ✅ Non-Breaking: Only adds error context; doesn't change API or behavior
• ✅ Future-Proof: When C++ core adds support for more combinations, the error handling gracefully adapts

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• Documentation update
• Error handling improvement

Testing

This change affects error paths that are already failing in issue #78. The fix:

1. Preserves the original exception chain (using from exc)
2. Adds context without swallowing the original error
3. Only triggers when C++ core raises RuntimeError

Notes for Reviewers

• This is a temporary UX improvement while the C++ core adds support for missing metric/type combinations
• The error messages explicitly state "may occur" to account for other potential causes
• Original error is preserved in the exception chain for debugging
• Docstring updates provide proactive guidance to prevent the error

Related Issues

• Closes [Bug]: Issue with creating indexes and executing optimize for certain data types when using cosine metric scenario #78
• Related to ongoing work on metric/data type support in the C++ core

[Copilot]

Pull request overview

This PR improves the Python Collection wrapper’s UX by enriching exceptions coming from the C++ core when index creation or optimization fails due to unsupported configurations (issue #78).

Changes:

• Add contextual error wrapping for Collection.create_index() failures originating from the C++ core.
• Add contextual error wrapping for Collection.optimize() failures originating from the C++ core.
• Update docstrings to document known limitations and newly raised RuntimeErrors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

There are blank lines with trailing indentation whitespace (e.g., around this separator before the try/except). This can cause lint/pre-commit failures and adds noise to diffs; please remove the trailing whitespace on empty lines.

[Junio243]

@copilot open a new pull request to apply changes based on this feedback

[Junio243]

@copilot open a new pull request to apply changes based on this feedback

[Junio243]

@copilot open a new pull request to apply changes based on the comments in this thread

[Junio243]

@copilot open a new pull request to apply changes based on the comments in this thread

[Junio243]

@copilot open a new pull request to apply changes based on the comments in this thread