fix: add parameter validation to core methods for type safety

[lxcxjxhx]

Problem

The llama-cpp-python library lacks parameter validation in several critical methods, which can lead to confusing errors or undefined behavior when users pass invalid arguments. Specifically:

1. Llama.__init__ (llama_cpp/llama.py lines 60-234): No validation for model_path (can be empty/None/non-string) or n_ctx (can be <= 0)
2. Llama.create_completion (llama_cpp/llama.py lines 1818-1920): No validation for sampling parameters like temperature, top_p, and top_k
3. Llama.tokenize (llama_cpp/llama.py lines 605-621): No type validation for the text parameter
4. Llama.detokenize (llama_cpp/llama.py lines 623-639): No type validation for the tokens parameter or its elements

These missing validations can cause:

• Cryptic errors deep in the C++ layer
• Segmentation faults or undefined behavior
• Difficult debugging for users
• Inconsistent error messages

Solution

Add explicit parameter validation at the Python layer with clear, descriptive error messages. This provides:

• Early failure with actionable error messages
• Type safety guarantees
• Better developer experience
• Prevention of undefined behavior in the underlying C++ code

Changes

1. Llama.__init__ validation (llama_cpp/llama.py:202-209)

# Parameter validation
if not model_path:
    raise ValueError("model_path cannot be empty or None")

if not isinstance(model_path, str):
    raise TypeError("model_path must be a string")

if n_ctx <= 0:
    raise ValueError(f"n_ctx must be > 0, got {n_ctx}")

2. Llama.create_completion validation (llama_cpp/llama.py:1904-1911)

# Parameter validation
if temperature < 0.0:
    raise ValueError(f"temperature must be >= 0.0, got {temperature}")

if not 0.0 <= top_p <= 1.0:
    raise ValueError(f"top_p must be in [0.0, 1.0], got {top_p}")

if top_k < 0:
    raise ValueError(f"top_k must be >= 0, got {top_k}")

3. Llama.tokenize validation (llama_cpp/llama.py:632-634)

# Type validation
if not isinstance(text, (str, bytes)):
    raise TypeError(f"text must be str or bytes, got {type(text).__name__}")

4. Llama.detokenize validation (llama_cpp/llama.py:656-661)

# Type validation
if not isinstance(tokens, list):
    raise TypeError(f"tokens must be a list, got {type(tokens).__name__}")

if not all(isinstance(t, int) for t in tokens):
    raise TypeError("all elements in tokens must be integers")

5. Updated docstrings

Updated the Raises sections in docstrings to document the new exceptions.

Testing

Created comprehensive test suite in tests/test_type_safety_validation.py with 41 test cases covering:

TestInitValidation (10 tests):

• Empty/None model_path raises ValueError
• Non-string model_path (int, list, dict) raises TypeError
• n_ctx <= 0 raises ValueError
• Valid parameters pass validation

TestTokenizeValidation (8 tests):

• Invalid types (int, list, None, dict, float) raise TypeError
• Valid types (str, bytes, empty str) are accepted

TestDetokenizeValidation (10 tests):

• Invalid container types (str, int, None, tuple, dict) raise TypeError
• Lists with non-int elements (str, float, None) raise TypeError
• Valid lists (including empty) are accepted

TestCreateCompletionValidation (13 tests):

• Negative temperature raises ValueError
• top_p outside [0.0, 1.0] raises ValueError
• Negative top_k raises ValueError
• Valid parameters and boundary values (0.0, 1.0) pass validation
• Multiple invalid parameters fail on first check

All tests pass successfully:

======================= 41 passed, 39 warnings in 0.38s =======================

Backward Compatibility

These changes maintain backward compatibility:

1. No breaking changes to valid code: All existing code that passes valid parameters will continue to work exactly as before
2. Early failure for invalid code: Code that previously caused cryptic errors or undefined behavior now fails fast with clear messages
3. No API changes: Method signatures remain unchanged
4. No behavioral changes: Valid inputs produce identical outputs

The validation is purely additive - it catches errors earlier and provides better error messages, but does not change the behavior for any valid use case.

Files Modified

• llama_cpp/llama.py: Added validation logic and updated docstrings
• tests/test_type_safety_validation.py: New comprehensive test suite (41 tests)

---

此PR由AI辅助生成，已通过静态检查，但核心逻辑变更请重点复核。