[Feature Request]: Add support for custom input validation hooks

[ModelingSolver]

Python -VV

Description:
I have identified a need to perform heuristic validation on user prompts before they are sent to the Mistral API (e.g., to filter out empty prompts or enforce security rules).

Proposed Solution:
I have implemented a HeuristicGuardHook that integrates with the existing hook system. It allows developers to validate messages content before the request is processed.

Technical Implementation:

    Created HeuristicGuardHook in the hook directory.

    Registered it via registration.py.

    The current implementation successfully blocks invalid requests by raising a ValueError.

Note to maintainers:
Since this repository contains generated code, I have not submitted a Pull Request. However, I have a working implementation and a suite of tests on my fork here: [https://github.com/ModelingSolver/client-python]

I would be happy to discuss how this logic could be integrated into your generation templates or if there is a preferred way to contribute this kind of custom logic.

Pip Freeze

aiohappyeyeballs==2.6.2
aiohttp==3.14.1
aiosignal==1.4.0
annotated-doc==0.0.4
annotated-types==0.7.0
anyio==4.13.0
attrs==26.1.0
certifi==2026.2.25
cffi==2.0.0
charset-normalizer==3.4.7
click==8.3.1
colorama==0.4.6
contourpy==1.3.3
cycler==0.12.1
eval_type_backport==0.4.0
filelock==3.25.2
fonttools==4.63.0
frozenlist==1.8.0
fsspec==2026.3.0
h11==0.16.0
hf-xet==1.4.3
httpcore==1.0.9
httpx==0.28.1
huggingface_hub==1.8.0
idna==3.11
importlib_metadata==8.7.1
Jinja2==3.1.6
joblib==1.5.3
jsonpath-python==1.1.6
kagglehub==1.0.2
kagglesdk==0.1.30
kiwisolver==1.5.0
markdown-it-py==4.0.0
MarkupSafe==3.0.3
matplotlib==3.11.0
mdurl==0.1.2
-e git+https://github.com/ModelingSolver/client-python.git@e995c505956d0fae2f3ed49cc386d0ab4baac5be#egg=mistralai
mpmath==1.3.0
multidict==6.7.1
networkx==3.6.1
numpy==2.2.5
opentelemetry-api==1.39.1
opentelemetry-semantic-conventions==0.60b1
packaging==26.0
pandas==3.0.3
pillow==12.2.0
propcache==0.5.2
protobuf==7.35.1
psutil==7.2.2
pycparser==3.0
pydantic==2.13.4
pydantic_core==2.46.4
Pygments==2.20.0
pyparsing==3.3.2
python-dateutil==2.9.0.post0
PyYAML==6.0.3
regex==2026.3.32
requests==2.33.1
rich==14.3.3
safetensors==0.7.0
scikit-learn==1.8.0
scipy==1.17.1
sentence-transformers==5.3.0
setuptools==81.0.0
shellingham==1.5.4
six==1.17.0
soundfile==0.14.0
sympy==1.14.0
threadpoolctl==3.6.0
tokenizers==0.22.2
torch==2.11.0
tqdm==4.67.3
transformers==5.4.0
typer==0.24.1
typing-inspection==0.4.2
typing_extensions==4.15.0
tzdata==2026.2
urllib3==2.7.0
wfdb==4.3.1
yarl==1.24.2
zipp==4.1.0

Reproduction Steps

To verify the integration and the functionality of the HeuristicGuardHook, follow these steps:

1/ Environment Setup:
Ensure you are using the dependencies listed below (exact versions may vary depending on the environment):

(aiohappyeyeballs==2.6.2
aiohttp==3.14.1
aiosignal==1.4.0
annotated-doc==0.0.4
annotated-types==0.7.0
anyio==4.13.0
attrs==26.1.0
certifi==2026.2.25
cffi==2.0.0
charset-normalizer==3.4.7
click==8.3.1
colorama==0.4.6
contourpy==1.3.3
cycler==0.12.1
eval_type_backport==0.4.0
filelock==3.25.2
fonttools==4.63.0
frozenlist==1.8.0
fsspec==2026.3.0
h11==0.16.0
hf-xet==1.4.3
httpcore==1.0.9
httpx==0.28.1
huggingface_hub==1.8.0
idna==3.11
importlib_metadata==8.7.1
Jinja2==3.1.6
joblib==1.5.3
jsonpath-python==1.1.6
kagglehub==1.0.2
kagglesdk==0.1.30
kiwisolver==1.5.0
markdown-it-py==4.0.0
MarkupSafe==3.0.3
matplotlib==3.11.0
mdurl==0.1.2
-e git+https://github.com/ModelingSolver/client-python.git@e995c505956d0fae2f3ed49cc386d0ab4baac5be#egg=mistralai
mpmath==1.3.0
multidict==6.7.1
networkx==3.6.1
numpy==2.2.5
opentelemetry-api==1.39.1
opentelemetry-semantic-conventions==0.60b1
packaging==26.0
pandas==3.0.3
pillow==12.2.0
propcache==0.5.2
protobuf==7.35.1
psutil==7.2.2
pycparser==3.0
pydantic==2.13.4
pydantic_core==2.46.4
Pygments==2.20.0
pyparsing==3.3.2
python-dateutil==2.9.0.post0
PyYAML==6.0.3
regex==2026.3.32
requests==2.33.1
rich==14.3.3
safetensors==0.7.0
scikit-learn==1.8.0
scipy==1.17.1
sentence-transformers==5.3.0
setuptools==81.0.0
shellingham==1.5.4
six==1.17.0
soundfile==0.14.0
sympy==1.14.0
threadpoolctl==3.6.0
tokenizers==0.22.2
torch==2.11.0
tqdm==4.67.3
transformers==5.4.0
typer==0.24.1
typing-inspection==0.4.2
typing_extensions==4.15.0
tzdata==2026.2
urllib3==2.7.0
wfdb==4.3.1
yarl==1.24.2
zipp==4.1.0
)

2/ Implementation:
Place the HeuristicGuardHook class in src/mistralai/client/_hooks/heuristic_hook.py.
Register the hook in src/mistralai/client/_hooks/registration.py so the client executes it during request preparation.

3/ Verification Script:
Run the following test script, which attempts a request that fails the heuristic guard:

from mistralai import Mistral
# Configure the client
client = Mistral(api_key="your_key")
# This will trigger the HeuristicGuard and raise a ValueError
try:
    client.chat.complete(model="mistral-large-latest", messages=[{"role": "user", "content": "Trigger block"}])
except ValueError as e:
    print(f"Success: Caught expected error: {e}")

Expected Behavior

Expected Behavior:
The client should raise a ValueError("Blocked by HeuristicGuard") before the HTTP request is sent, effectively preventing invalid traffic from reaching the API.

Additional Context

I am implementing a local security layer for my application that interacts with the Mistral API. Given the nature of my use case, I need to ensure that user inputs are validated against specific heuristic rules before they leave the client environment.

Integrating this as a hook within the SDK is the cleanest approach, as it allows for a standardized validation flow for all Mistral API requests without duplicating logic in my main application code.

Suggested Solutions

Based on my implementation, I recommend the following approaches for the team to consider:

-Native Hook Integration (Recommended):
Expose a formal hook registration mechanism in the client initialization. This would allow users to inject custom classes that implement a standard ValidationHook interface without modifying the generated core code.

-Template-Driven Validation:
If the client is generated via a tool (like Speakeasy), consider adding a "pre-request-validation" step in the generation templates. This would allow developers to define validation rules in a configuration file, which the generator would then inject into the chat.complete call flow.

-Middleware Support:
Adopt an approach similar to httpx or requests middleware, where users can pass a list of callables to the client constructor. Each callable would receive the request payload and have the ability to abort the request by raising an exception, ensuring security and input hygiene.