<div align="center">
<img src="assets/logo.png" alt="ModelSignature" width="400"/>
# ModelSignature Python SDK
[](https://pypi.org/project/modelsignature/)
[](https://pypi.org/project/modelsignature/)
[](https://opensource.org/licenses/MIT)
**Model Feedback & Reports, Right in Your Chat!**
Receive end-user feedback & bug reports on your AI model, no matter who's hosting.
</div>
---
## Installation
```bash
# Core SDK - API client for model management
pip install modelsignature
# With embedding - includes LoRA fine-tuning for baking feedback links into models
pip install 'modelsignature[embedding]'
```
The `embedding` extra adds PyTorch, Transformers, and PEFT for fine-tuning.
**Requirements:** Python 3.8+
---
## Quick Start
Embed a feedback link directly into your model using LoRA fine-tuning. Users can ask "Where can I report issues?" and get your feedback page URL - works anywhere your model is deployed.
```python
import modelsignature as msig
# One-line embedding with LoRA fine-tuning
result = msig.embed_signature_link(
model="mistralai/Mistral-7B-Instruct-v0.3",
link="https://modelsignature.com/models/model_abc123",
api_key="your_api_key", # Validates ownership
mode="adapter", # or "merge"
fp="4bit" # Memory optimization
)
# After deployment, users can ask:
# "I'd like to report a bug" → "Submit feedback at https://modelsignature.com/models/model_abc123"
```
**Why embed feedback links?**
- Users can report bugs & issues directly from the chat
- Works on HuggingFace, Replicate, or any hosting platform
- Feedback channel persists with the model
- One-time setup, no runtime overhead
**Training time:** ~40-50 minutes on T4 GPU (Google Colab free tier)
[📔 Google Colab Notebook](https://colab.research.google.com/github/ModelSignature/python-sdk/blob/main/notebooks/ModelSignature_Embedding_Simple.ipynb)
---
## Model Registration
Register your model to get a feedback page where users can submit reports:
```python
from modelsignature import ModelSignatureClient
client = ModelSignatureClient(api_key="your_api_key")
model = client.register_model(
display_name="My Assistant",
api_model_identifier="my-assistant-v1", # Immutable - used for versioning
endpoint="https://api.example.com/v1/chat",
version="1.0.0",
description="Customer support AI assistant",
model_type="language",
is_public=True
)
print(f"Feedback page: https://modelsignature.com/models/{model.model_id}")
```
**Note:** Provider registration can be done via [web dashboard](https://modelsignature.com/dashboard) or [API](https://docs.modelsignature.com#register-provider). See [full documentation](https://docs.modelsignature.com) for details.
---
## Receiving User Feedback
### View Incident Reports
```python
# Get all incidents reported for your models
incidents = client.get_my_incidents(status="reported")
for incident in incidents:
print(f"Issue: {incident['title']}")
print(f"Category: {incident['category']}")
print(f"Severity: {incident['severity']}")
print(f"Description: {incident['description']}")
```
### Categories & Severity Levels
Users can report issues in these categories:
- **Technical Error** - Bugs, incorrect outputs, failures
- **Harmful Content** - Safety concerns, inappropriate responses
- **Hallucination** - False or fabricated information
- **Bias** - Unfair or skewed responses
- **Other** - General feedback
Severity levels: `low`, `medium`, `high`, `critical`
---
## Key Features
**Direct Feedback Channel**
- Users report bugs & issues directly from chat
- Incident dashboard for tracking reports
- Community statistics and trust metrics
- Verified vs. anonymous reports
**Model Management**
- Versioning with immutable identifiers
- Health monitoring and uptime tracking
- Archive/unarchive model versions
- Trust scoring system (unverified → premium)
**Optional: Cryptographic Verification**
- JWT tokens for identity verification (enterprise use case)
- mTLS deployment authentication
- Response binding to prevent output substitution
- Sigstore bundle support for model integrity
---
## Alternative: Runtime Wrapper
For self-hosted deployments, you can generate verification links at runtime instead of embedding:
```python
from modelsignature import ModelSignatureClient, IdentityQuestionDetector
client = ModelSignatureClient(api_key="your_api_key")
detector = IdentityQuestionDetector()
# In your inference loop
if detector.is_identity_question(user_input):
verification = client.create_verification(
model_id="model_abc123",
user_fingerprint="session_xyz"
)
return verification.verification_url
```
Generates short-lived verification URLs (15 min expiry). No model modification required.
---
## Advanced Usage
### Programmatic Incident Reporting
```python
from modelsignature import IncidentCategory, IncidentSeverity
# Report incidents programmatically
incident = client.report_incident(
model_id="model_abc123",
category=IncidentCategory.TECHNICAL_ERROR.value,
title="Incorrect math calculations",
description="Model consistently returns wrong answers for basic arithmetic",
severity=IncidentSeverity.MEDIUM.value
)
```
### Model Versioning
```python
# Create new version (same identifier)
model_v2 = client.register_model(
api_model_identifier="my-assistant", # Same as v1
version="2.0.0",
force_new_version=True, # Required
# ...
)
# Get version history
history = client.get_model_history(model_v2.model_id)
```
### Community Statistics
```python
# Get community stats for your model
stats = client.get_model_community_stats("model_abc123")
print(f"Total feedback reports: {stats['total_verifications']}")
print(f"Open incidents: {stats['unresolved_incidents']}")
print(f"Trust level: {stats['provider_trust_level']}")
```
### API Key Management
```python
# List API keys
keys = client.list_api_keys()
# Create new key
new_key = client.create_api_key("Production Key")
print(f"Key: {new_key.api_key}") # Only shown once
# Revoke key
client.revoke_api_key(key_id="key_123")
```
---
## Configuration
```python
client = ModelSignatureClient(
api_key="your_key",
base_url="https://api.modelsignature.com",
timeout=30,
max_retries=3,
debug=True
)
```
---
## Error Handling
```python
from modelsignature import ConflictError, ValidationError, AuthenticationError
try:
model = client.register_model(...)
except ConflictError as e:
# Model already exists - create new version
print(f"Conflict: {e.existing_resource}")
except ValidationError as e:
# Invalid parameters
print(f"Validation error: {e.errors}")
except AuthenticationError as e:
# Invalid API key
print(f"Auth failed: {e}")
```
**Available exceptions:** `AuthenticationError`, `PermissionError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `ServerError`
---
## Examples
Check the [examples/](examples/) directory for integration patterns:
- [Embedding Example](examples/embedding_example.py) - LoRA fine-tuning
- [Incident Reporting](examples/incident_reporting_example.py) - User feedback workflow
- [OpenAI Integration](examples/openai_integration.py) - Function calling
- [Anthropic Integration](examples/anthropic_integration.py) - Tool integration
- [Middleware Example](examples/middleware_example.py) - Request interception
---
## Documentation
- [API Documentation](https://docs.modelsignature.com)
- [Web Dashboard](https://modelsignature.com/dashboard)
- [Quick Start Guide](https://docs.modelsignature.com#quick-start)
- [Integration Examples](https://docs.modelsignature.com#integration-patterns)
---
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Run tests: `python -m pytest`
4. Submit a pull request
---
## Support
- **Documentation:** [docs.modelsignature.com](https://docs.modelsignature.com)
- **Issues:** [GitHub Issues](https://github.com/ModelSignature/python-sdk/issues)
- **Email:** support@modelsignature.com
---
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "modelsignature",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "ModelSignature Team <team@modelsignature.com>",
"keywords": "ai, ml, verification, cryptography, identity, llm, chatbot",
"author": null,
"author_email": "ModelSignature Team <team@modelsignature.com>",
"download_url": "https://files.pythonhosted.org/packages/ab/aa/d2aae699e7944616da535f0d70a7684f7704686afcb49f342d17d1cc1911/modelsignature-0.3.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"assets/logo.png\" alt=\"ModelSignature\" width=\"400\"/>\n\n # ModelSignature Python SDK\n\n [](https://pypi.org/project/modelsignature/)\n [](https://pypi.org/project/modelsignature/)\n [](https://opensource.org/licenses/MIT)\n\n **Model Feedback & Reports, Right in Your Chat!**\n\n Receive end-user feedback & bug reports on your AI model, no matter who's hosting.\n</div>\n\n---\n\n## Installation\n\n```bash\n# Core SDK - API client for model management\npip install modelsignature\n\n# With embedding - includes LoRA fine-tuning for baking feedback links into models\npip install 'modelsignature[embedding]'\n```\n\nThe `embedding` extra adds PyTorch, Transformers, and PEFT for fine-tuning.\n\n**Requirements:** Python 3.8+\n\n---\n\n## Quick Start\n\nEmbed a feedback link directly into your model using LoRA fine-tuning. Users can ask \"Where can I report issues?\" and get your feedback page URL - works anywhere your model is deployed.\n\n```python\nimport modelsignature as msig\n\n# One-line embedding with LoRA fine-tuning\nresult = msig.embed_signature_link(\n model=\"mistralai/Mistral-7B-Instruct-v0.3\",\n link=\"https://modelsignature.com/models/model_abc123\",\n api_key=\"your_api_key\", # Validates ownership\n mode=\"adapter\", # or \"merge\"\n fp=\"4bit\" # Memory optimization\n)\n\n# After deployment, users can ask:\n# \"I'd like to report a bug\" \u2192 \"Submit feedback at https://modelsignature.com/models/model_abc123\"\n```\n\n**Why embed feedback links?**\n- Users can report bugs & issues directly from the chat\n- Works on HuggingFace, Replicate, or any hosting platform\n- Feedback channel persists with the model\n- One-time setup, no runtime overhead\n\n**Training time:** ~40-50 minutes on T4 GPU (Google Colab free tier)\n\n[\ud83d\udcd4 Google Colab Notebook](https://colab.research.google.com/github/ModelSignature/python-sdk/blob/main/notebooks/ModelSignature_Embedding_Simple.ipynb)\n\n---\n\n## Model Registration\n\nRegister your model to get a feedback page where users can submit reports:\n\n```python\nfrom modelsignature import ModelSignatureClient\n\nclient = ModelSignatureClient(api_key=\"your_api_key\")\n\nmodel = client.register_model(\n display_name=\"My Assistant\",\n api_model_identifier=\"my-assistant-v1\", # Immutable - used for versioning\n endpoint=\"https://api.example.com/v1/chat\",\n version=\"1.0.0\",\n description=\"Customer support AI assistant\",\n model_type=\"language\",\n is_public=True\n)\n\nprint(f\"Feedback page: https://modelsignature.com/models/{model.model_id}\")\n```\n\n**Note:** Provider registration can be done via [web dashboard](https://modelsignature.com/dashboard) or [API](https://docs.modelsignature.com#register-provider). See [full documentation](https://docs.modelsignature.com) for details.\n\n---\n\n## Receiving User Feedback\n\n### View Incident Reports\n\n```python\n# Get all incidents reported for your models\nincidents = client.get_my_incidents(status=\"reported\")\n\nfor incident in incidents:\n print(f\"Issue: {incident['title']}\")\n print(f\"Category: {incident['category']}\")\n print(f\"Severity: {incident['severity']}\")\n print(f\"Description: {incident['description']}\")\n```\n\n### Categories & Severity Levels\n\nUsers can report issues in these categories:\n- **Technical Error** - Bugs, incorrect outputs, failures\n- **Harmful Content** - Safety concerns, inappropriate responses\n- **Hallucination** - False or fabricated information\n- **Bias** - Unfair or skewed responses\n- **Other** - General feedback\n\nSeverity levels: `low`, `medium`, `high`, `critical`\n\n---\n\n## Key Features\n\n**Direct Feedback Channel**\n- Users report bugs & issues directly from chat\n- Incident dashboard for tracking reports\n- Community statistics and trust metrics\n- Verified vs. anonymous reports\n\n**Model Management**\n- Versioning with immutable identifiers\n- Health monitoring and uptime tracking\n- Archive/unarchive model versions\n- Trust scoring system (unverified \u2192 premium)\n\n**Optional: Cryptographic Verification**\n- JWT tokens for identity verification (enterprise use case)\n- mTLS deployment authentication\n- Response binding to prevent output substitution\n- Sigstore bundle support for model integrity\n\n---\n\n## Alternative: Runtime Wrapper\n\nFor self-hosted deployments, you can generate verification links at runtime instead of embedding:\n\n```python\nfrom modelsignature import ModelSignatureClient, IdentityQuestionDetector\n\nclient = ModelSignatureClient(api_key=\"your_api_key\")\ndetector = IdentityQuestionDetector()\n\n# In your inference loop\nif detector.is_identity_question(user_input):\n verification = client.create_verification(\n model_id=\"model_abc123\",\n user_fingerprint=\"session_xyz\"\n )\n return verification.verification_url\n```\n\nGenerates short-lived verification URLs (15 min expiry). No model modification required.\n\n---\n\n## Advanced Usage\n\n### Programmatic Incident Reporting\n\n```python\nfrom modelsignature import IncidentCategory, IncidentSeverity\n\n# Report incidents programmatically\nincident = client.report_incident(\n model_id=\"model_abc123\",\n category=IncidentCategory.TECHNICAL_ERROR.value,\n title=\"Incorrect math calculations\",\n description=\"Model consistently returns wrong answers for basic arithmetic\",\n severity=IncidentSeverity.MEDIUM.value\n)\n```\n\n### Model Versioning\n\n```python\n# Create new version (same identifier)\nmodel_v2 = client.register_model(\n api_model_identifier=\"my-assistant\", # Same as v1\n version=\"2.0.0\",\n force_new_version=True, # Required\n # ...\n)\n\n# Get version history\nhistory = client.get_model_history(model_v2.model_id)\n```\n\n### Community Statistics\n\n```python\n# Get community stats for your model\nstats = client.get_model_community_stats(\"model_abc123\")\nprint(f\"Total feedback reports: {stats['total_verifications']}\")\nprint(f\"Open incidents: {stats['unresolved_incidents']}\")\nprint(f\"Trust level: {stats['provider_trust_level']}\")\n```\n\n### API Key Management\n\n```python\n# List API keys\nkeys = client.list_api_keys()\n\n# Create new key\nnew_key = client.create_api_key(\"Production Key\")\nprint(f\"Key: {new_key.api_key}\") # Only shown once\n\n# Revoke key\nclient.revoke_api_key(key_id=\"key_123\")\n```\n\n---\n\n## Configuration\n\n```python\nclient = ModelSignatureClient(\n api_key=\"your_key\",\n base_url=\"https://api.modelsignature.com\",\n timeout=30,\n max_retries=3,\n debug=True\n)\n```\n\n---\n\n## Error Handling\n\n```python\nfrom modelsignature import ConflictError, ValidationError, AuthenticationError\n\ntry:\n model = client.register_model(...)\nexcept ConflictError as e:\n # Model already exists - create new version\n print(f\"Conflict: {e.existing_resource}\")\nexcept ValidationError as e:\n # Invalid parameters\n print(f\"Validation error: {e.errors}\")\nexcept AuthenticationError as e:\n # Invalid API key\n print(f\"Auth failed: {e}\")\n```\n\n**Available exceptions:** `AuthenticationError`, `PermissionError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `ServerError`\n\n---\n\n## Examples\n\nCheck the [examples/](examples/) directory for integration patterns:\n\n- [Embedding Example](examples/embedding_example.py) - LoRA fine-tuning\n- [Incident Reporting](examples/incident_reporting_example.py) - User feedback workflow\n- [OpenAI Integration](examples/openai_integration.py) - Function calling\n- [Anthropic Integration](examples/anthropic_integration.py) - Tool integration\n- [Middleware Example](examples/middleware_example.py) - Request interception\n\n---\n\n## Documentation\n\n- [API Documentation](https://docs.modelsignature.com)\n- [Web Dashboard](https://modelsignature.com/dashboard)\n- [Quick Start Guide](https://docs.modelsignature.com#quick-start)\n- [Integration Examples](https://docs.modelsignature.com#integration-patterns)\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Run tests: `python -m pytest`\n4. Submit a pull request\n\n---\n\n## Support\n\n- **Documentation:** [docs.modelsignature.com](https://docs.modelsignature.com)\n- **Issues:** [GitHub Issues](https://github.com/ModelSignature/python-sdk/issues)\n- **Email:** support@modelsignature.com\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Cryptographic identity verification for AI models \u2014 like SSL certificates for AI conversations",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/ModelSignature/python-sdk/issues",
"Changelog": "https://github.com/ModelSignature/python-sdk/blob/main/CHANGELOG.md",
"Documentation": "https://docs.modelsignature.com",
"Homepage": "https://modelsignature.com",
"Repository": "https://github.com/ModelSignature/python-sdk"
},
"split_keywords": [
"ai",
" ml",
" verification",
" cryptography",
" identity",
" llm",
" chatbot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "02264fbcce32a9e2b4f3d6a541b66038460425d4541aab0489553cfe41f3f984",
"md5": "66d6aa0d3d66111d86211abca3769ea5",
"sha256": "4e8e028d8e3bcbb4fe3d4f7cb38aaa3148b9123739eb85fc5fcc90a3881b9a32"
},
"downloads": -1,
"filename": "modelsignature-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66d6aa0d3d66111d86211abca3769ea5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 44600,
"upload_time": "2025-10-17T23:35:25",
"upload_time_iso_8601": "2025-10-17T23:35:25.917845Z",
"url": "https://files.pythonhosted.org/packages/02/26/4fbcce32a9e2b4f3d6a541b66038460425d4541aab0489553cfe41f3f984/modelsignature-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "abaad2aae699e7944616da535f0d70a7684f7704686afcb49f342d17d1cc1911",
"md5": "c3c0e441b7f3643eb6bccd11bbd226c7",
"sha256": "80d90cb4fe42bb4e4b3b6a63755e29598299400a96e53d7242a0dde3157cf175"
},
"downloads": -1,
"filename": "modelsignature-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "c3c0e441b7f3643eb6bccd11bbd226c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50744,
"upload_time": "2025-10-17T23:35:27",
"upload_time_iso_8601": "2025-10-17T23:35:27.291362Z",
"url": "https://files.pythonhosted.org/packages/ab/aa/d2aae699e7944616da535f0d70a7684f7704686afcb49f342d17d1cc1911/modelsignature-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-17 23:35:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ModelSignature",
"github_project": "python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
}
],
"tox": true,
"lcname": "modelsignature"
}
JSON
