# ModelSignature Python SDK
[](https://badge.fury.io/py/modelsignature)
[](https://pypi.org/project/modelsignature/)
[](https://opensource.org/licenses/MIT)
**Cryptographic identity verification for AI models — like SSL certificates for AI conversations.**
ModelSignature provides a comprehensive SDK for AI model identity verification, provider management, and community trust features. Prove your AI model's identity with cryptographically secure verification links.
## 🚀 Features
- **🔒 Cryptographic Verification**: Generate secure identity proofs for your AI models
- **👤 Provider Management**: Complete profile and compliance management
- **🔑 API Key Management**: Create, list, and revoke multiple API keys
- **📊 Model Lifecycle**: Archive, version control, and visibility management
- **🔍 Search & Discovery**: Find models and providers across the ecosystem
- **🚨 Incident Reporting**: Community safety and reliability reporting
- **⚡ Enhanced Error Handling**: Detailed error types with structured information
- **🎯 Type Safety**: Full enum support and type hints throughout
## Installation
```bash
pip install modelsignature
```
Supports Python 3.8+ with minimal dependencies.
## Quick Start
### Basic Identity Verification
```python
from modelsignature import ModelSignatureClient, IdentityQuestionDetector
client = ModelSignatureClient(api_key="your_api_key")
detector = IdentityQuestionDetector()
# Detect identity questions
if detector.is_identity_question("Who are you?"):
verification = client.create_verification(
model_id="your_model_id",
user_fingerprint="session_123",
)
print(f"Verify at: {verification.verification_url}")
```
### Enhanced Model Registration
```python
from modelsignature import ModelCapability, InputType, OutputType
# Register with comprehensive metadata
model = client.register_model(
display_name="GPT-4 Enhanced",
api_model_identifier="gpt4-enhanced",
endpoint="https://api.example.com/v1/chat",
version="2.0.0",
description="Enhanced GPT-4 with improved reasoning",
model_type="language",
capabilities=[
ModelCapability.TEXT_GENERATION.value,
ModelCapability.REASONING.value,
ModelCapability.CODE_GENERATION.value,
],
input_types=[InputType.TEXT.value, InputType.IMAGE.value],
output_types=[OutputType.TEXT.value, OutputType.JSON.value],
serving_regions=["us-east-1", "eu-west-1"],
context_window=128000,
uptime_sla=99.95,
performance_benchmarks={
"mmlu": 88.4,
"humaneval": 85.2,
},
enable_health_monitoring=True,
)
```
### Provider Profile Management
```python
from modelsignature import HeadquartersLocation
# Update provider profile
hq = HeadquartersLocation(
city="San Francisco",
state="California",
country="United States"
)
client.update_provider_profile(
provider_id="your_provider_id",
company_name="AI Labs Inc",
founded_year=2020,
headquarters_location=hq,
support_email="support@ailabs.com",
)
# Update compliance information
client.update_provider_compliance(
provider_id="your_provider_id",
compliance_certifications=["SOC2", "ISO27001", "GDPR"],
ai_specific_certifications="Partnership on AI member",
)
```
### API Key Management
```python
# List API keys
keys = client.list_api_keys()
for key in keys:
print(f"{key.name}: {key.key_prefix}*** ({'Active' if key.is_active else 'Inactive'})")
# Create new API key
new_key = client.create_api_key("Production Key")
print(f"New key: {new_key.api_key}")
# Revoke API key
client.revoke_api_key(key_id="key_123")
```
### Model Lifecycle Management
```python
# Archive a model
client.archive_model("model_123", reason="Replaced by v2")
# Update model visibility
client.update_model_visibility("model_123", is_public=True)
# Get model version history
history = client.get_model_history("model_123")
print(f"Model has {history['total_versions']} versions")
# Get community statistics
stats = client.get_model_community_stats("model_123")
print(f"Total verifications: {stats['total_verifications']}")
```
### Search and Discovery
```python
# Search across models and providers
results = client.search("GPT-4", limit=10)
print(f"Found {results['total']} results")
# List public models
models = client.list_public_models(limit=50)
for model in models:
print(f"{model['name']} by {model['provider_name']}")
# Get public provider info
provider = client.get_public_provider("provider_123")
print(f"{provider['company_name']} - Trust Level: {provider['trust_level']}")
```
### Enhanced Error Handling
```python
from modelsignature import ConflictError, ValidationError, NotFoundError
try:
model = client.register_model(...)
except ConflictError as e:
print(f"Model exists: {e.existing_resource}")
# Handle conflict, maybe create new version
except ValidationError as e:
print(f"Invalid data: {e.errors}")
# Fix validation issues
except NotFoundError as e:
print(f"Resource not found: {e}")
# Handle missing resource
```
## 🎯 Available Enums
The SDK provides enums for type-safe operations:
```python
from modelsignature import (
ModelCapability, # TEXT_GENERATION, REASONING, CODE_GENERATION, etc.
InputType, # TEXT, IMAGE, AUDIO, VIDEO, PDF, etc.
OutputType, # TEXT, IMAGE, JSON, CODE, etc.
TrustLevel, # UNVERIFIED, BASIC, STANDARD, ADVANCED, PREMIUM
IncidentCategory, # HARMFUL_CONTENT, TECHNICAL_ERROR, IMPERSONATION, etc.
IncidentSeverity, # LOW, MEDIUM, HIGH, CRITICAL
)
# Use enum values
capabilities = [ModelCapability.TEXT_GENERATION.value, ModelCapability.REASONING.value]
```
## 📚 Examples
- **[Basic Usage](examples/basic_usage.py)**: Simple identity verification
- **[Enhanced Usage](examples/enhanced_usage.py)**: Comprehensive feature showcase
- **[OpenAI Integration](examples/openai_integration.py)**: Function calling integration
- **[Anthropic Integration](examples/anthropic_integration.py)**: Tool integration
- **[Middleware Example](examples/middleware_example.py)**: Request interception
## 🛡️ Error Handling
The SDK provides specific exception types for better error handling:
| Exception | Description | Status Codes |
|-----------|-------------|--------------|
| `AuthenticationError` | Invalid or missing API key | 401 |
| `PermissionError` | Insufficient permissions | 403 |
| `NotFoundError` | Resource not found | 404 |
| `ConflictError` | Resource already exists | 409 |
| `ValidationError` | Invalid request parameters | 422 |
| `RateLimitError` | Too many requests | 429 |
| `ServerError` | Internal server error | 5xx |
All exceptions include:
- `status_code`: HTTP status code
- `response`: Full API response data
- Additional context (e.g., `existing_resource` for conflicts)
## 🚀 Advanced Usage
### Custom Configuration
```python
client = ModelSignatureClient(
api_key="your_key",
base_url="https://api.modelsignature.com", # Custom base URL
timeout=30, # Request timeout
max_retries=3, # Retry attempts
debug=True, # Enable debug logging
)
```
### Caching Verifications
```python
# Verifications are automatically cached to avoid redundant API calls
verification1 = client.create_verification("model_123", "user_456")
verification2 = client.create_verification("model_123", "user_456") # Returns cached result
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and add tests
4. Run tests: `python -m pytest`
5. Submit a pull request
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🔗 Links
- [ModelSignature Website](https://modelsignature.com)
- [API Documentation](https://docs.modelsignature.com)
- [GitHub Repository](https://github.com/ModelSignature/python-sdk)
- [PyPI Package](https://pypi.org/project/modelsignature)
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/20/ac/e26a85455ea4c78dbd203bf7c75246cb7f3b36d601a50e546ec1bf0cbcb6/modelsignature-0.2.0.tar.gz",
"platform": null,
"description": "# ModelSignature Python SDK\n\n[](https://badge.fury.io/py/modelsignature)\n[](https://pypi.org/project/modelsignature/)\n[](https://opensource.org/licenses/MIT)\n\n**Cryptographic identity verification for AI models \u2014 like SSL certificates for AI conversations.**\n\nModelSignature provides a comprehensive SDK for AI model identity verification, provider management, and community trust features. Prove your AI model's identity with cryptographically secure verification links.\n\n## \ud83d\ude80 Features\n\n- **\ud83d\udd12 Cryptographic Verification**: Generate secure identity proofs for your AI models\n- **\ud83d\udc64 Provider Management**: Complete profile and compliance management\n- **\ud83d\udd11 API Key Management**: Create, list, and revoke multiple API keys\n- **\ud83d\udcca Model Lifecycle**: Archive, version control, and visibility management\n- **\ud83d\udd0d Search & Discovery**: Find models and providers across the ecosystem\n- **\ud83d\udea8 Incident Reporting**: Community safety and reliability reporting\n- **\u26a1 Enhanced Error Handling**: Detailed error types with structured information\n- **\ud83c\udfaf Type Safety**: Full enum support and type hints throughout\n\n## Installation\n\n```bash\npip install modelsignature\n```\n\nSupports Python 3.8+ with minimal dependencies.\n\n## Quick Start\n\n### Basic Identity Verification\n\n```python\nfrom modelsignature import ModelSignatureClient, IdentityQuestionDetector\n\nclient = ModelSignatureClient(api_key=\"your_api_key\")\ndetector = IdentityQuestionDetector()\n\n# Detect identity questions\nif detector.is_identity_question(\"Who are you?\"):\n verification = client.create_verification(\n model_id=\"your_model_id\",\n user_fingerprint=\"session_123\",\n )\n print(f\"Verify at: {verification.verification_url}\")\n```\n\n### Enhanced Model Registration\n\n```python\nfrom modelsignature import ModelCapability, InputType, OutputType\n\n# Register with comprehensive metadata\nmodel = client.register_model(\n display_name=\"GPT-4 Enhanced\",\n api_model_identifier=\"gpt4-enhanced\",\n endpoint=\"https://api.example.com/v1/chat\",\n version=\"2.0.0\",\n description=\"Enhanced GPT-4 with improved reasoning\",\n model_type=\"language\",\n capabilities=[\n ModelCapability.TEXT_GENERATION.value,\n ModelCapability.REASONING.value,\n ModelCapability.CODE_GENERATION.value,\n ],\n input_types=[InputType.TEXT.value, InputType.IMAGE.value],\n output_types=[OutputType.TEXT.value, OutputType.JSON.value],\n serving_regions=[\"us-east-1\", \"eu-west-1\"],\n context_window=128000,\n uptime_sla=99.95,\n performance_benchmarks={\n \"mmlu\": 88.4,\n \"humaneval\": 85.2,\n },\n enable_health_monitoring=True,\n)\n```\n\n### Provider Profile Management\n\n```python\nfrom modelsignature import HeadquartersLocation\n\n# Update provider profile\nhq = HeadquartersLocation(\n city=\"San Francisco\",\n state=\"California\",\n country=\"United States\"\n)\n\nclient.update_provider_profile(\n provider_id=\"your_provider_id\",\n company_name=\"AI Labs Inc\",\n founded_year=2020,\n headquarters_location=hq,\n support_email=\"support@ailabs.com\",\n)\n\n# Update compliance information\nclient.update_provider_compliance(\n provider_id=\"your_provider_id\",\n compliance_certifications=[\"SOC2\", \"ISO27001\", \"GDPR\"],\n ai_specific_certifications=\"Partnership on AI member\",\n)\n```\n\n### API Key Management\n\n```python\n# List API keys\nkeys = client.list_api_keys()\nfor key in keys:\n print(f\"{key.name}: {key.key_prefix}*** ({'Active' if key.is_active else 'Inactive'})\")\n\n# Create new API key\nnew_key = client.create_api_key(\"Production Key\")\nprint(f\"New key: {new_key.api_key}\")\n\n# Revoke API key\nclient.revoke_api_key(key_id=\"key_123\")\n```\n\n### Model Lifecycle Management\n\n```python\n# Archive a model\nclient.archive_model(\"model_123\", reason=\"Replaced by v2\")\n\n# Update model visibility\nclient.update_model_visibility(\"model_123\", is_public=True)\n\n# Get model version history\nhistory = client.get_model_history(\"model_123\")\nprint(f\"Model has {history['total_versions']} versions\")\n\n# Get community statistics\nstats = client.get_model_community_stats(\"model_123\")\nprint(f\"Total verifications: {stats['total_verifications']}\")\n```\n\n### Search and Discovery\n\n```python\n# Search across models and providers\nresults = client.search(\"GPT-4\", limit=10)\nprint(f\"Found {results['total']} results\")\n\n# List public models\nmodels = client.list_public_models(limit=50)\nfor model in models:\n print(f\"{model['name']} by {model['provider_name']}\")\n\n# Get public provider info\nprovider = client.get_public_provider(\"provider_123\")\nprint(f\"{provider['company_name']} - Trust Level: {provider['trust_level']}\")\n```\n\n### Enhanced Error Handling\n\n```python\nfrom modelsignature import ConflictError, ValidationError, NotFoundError\n\ntry:\n model = client.register_model(...)\nexcept ConflictError as e:\n print(f\"Model exists: {e.existing_resource}\")\n # Handle conflict, maybe create new version\nexcept ValidationError as e:\n print(f\"Invalid data: {e.errors}\")\n # Fix validation issues\nexcept NotFoundError as e:\n print(f\"Resource not found: {e}\")\n # Handle missing resource\n```\n\n## \ud83c\udfaf Available Enums\n\nThe SDK provides enums for type-safe operations:\n\n```python\nfrom modelsignature import (\n ModelCapability, # TEXT_GENERATION, REASONING, CODE_GENERATION, etc.\n InputType, # TEXT, IMAGE, AUDIO, VIDEO, PDF, etc.\n OutputType, # TEXT, IMAGE, JSON, CODE, etc.\n TrustLevel, # UNVERIFIED, BASIC, STANDARD, ADVANCED, PREMIUM\n IncidentCategory, # HARMFUL_CONTENT, TECHNICAL_ERROR, IMPERSONATION, etc.\n IncidentSeverity, # LOW, MEDIUM, HIGH, CRITICAL\n)\n\n# Use enum values\ncapabilities = [ModelCapability.TEXT_GENERATION.value, ModelCapability.REASONING.value]\n```\n\n## \ud83d\udcda Examples\n\n- **[Basic Usage](examples/basic_usage.py)**: Simple identity verification\n- **[Enhanced Usage](examples/enhanced_usage.py)**: Comprehensive feature showcase\n- **[OpenAI Integration](examples/openai_integration.py)**: Function calling integration\n- **[Anthropic Integration](examples/anthropic_integration.py)**: Tool integration\n- **[Middleware Example](examples/middleware_example.py)**: Request interception\n\n## \ud83d\udee1\ufe0f Error Handling\n\nThe SDK provides specific exception types for better error handling:\n\n| Exception | Description | Status Codes |\n|-----------|-------------|--------------|\n| `AuthenticationError` | Invalid or missing API key | 401 |\n| `PermissionError` | Insufficient permissions | 403 |\n| `NotFoundError` | Resource not found | 404 |\n| `ConflictError` | Resource already exists | 409 |\n| `ValidationError` | Invalid request parameters | 422 |\n| `RateLimitError` | Too many requests | 429 |\n| `ServerError` | Internal server error | 5xx |\n\nAll exceptions include:\n- `status_code`: HTTP status code\n- `response`: Full API response data\n- Additional context (e.g., `existing_resource` for conflicts)\n\n## \ud83d\ude80 Advanced Usage\n\n### Custom Configuration\n\n```python\nclient = ModelSignatureClient(\n api_key=\"your_key\",\n base_url=\"https://api.modelsignature.com\", # Custom base URL\n timeout=30, # Request timeout\n max_retries=3, # Retry attempts\n debug=True, # Enable debug logging\n)\n```\n\n### Caching Verifications\n\n```python\n# Verifications are automatically cached to avoid redundant API calls\nverification1 = client.create_verification(\"model_123\", \"user_456\")\nverification2 = client.create_verification(\"model_123\", \"user_456\") # Returns cached result\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and add tests\n4. Run tests: `python -m pytest`\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Links\n\n- [ModelSignature Website](https://modelsignature.com)\n- [API Documentation](https://docs.modelsignature.com)\n- [GitHub Repository](https://github.com/ModelSignature/python-sdk)\n- [PyPI Package](https://pypi.org/project/modelsignature)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Cryptographic identity verification for AI models \u2014 like SSL certificates for AI conversations",
"version": "0.2.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": "e0116590e2c7420d6785ad6e9a17c39f18d360805f3b4ffb9226e31adac973af",
"md5": "e605a3ec0bfd9ca37b87180ed18d455b",
"sha256": "b461d89e8a5aab22e4ae37c2589f0562ba58a8aa285929ce789d33d0b87f56d2"
},
"downloads": -1,
"filename": "modelsignature-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e605a3ec0bfd9ca37b87180ed18d455b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16343,
"upload_time": "2025-07-27T06:51:22",
"upload_time_iso_8601": "2025-07-27T06:51:22.927597Z",
"url": "https://files.pythonhosted.org/packages/e0/11/6590e2c7420d6785ad6e9a17c39f18d360805f3b4ffb9226e31adac973af/modelsignature-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "20ace26a85455ea4c78dbd203bf7c75246cb7f3b36d601a50e546ec1bf0cbcb6",
"md5": "435e3ca3ac5ea8b333a3f7456704b926",
"sha256": "39a55dab0a7a16ecfee9f82aa7f5105f0cc3aef6c407b7ce437d3d617aca6683"
},
"downloads": -1,
"filename": "modelsignature-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "435e3ca3ac5ea8b333a3f7456704b926",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23330,
"upload_time": "2025-07-27T06:51:24",
"upload_time_iso_8601": "2025-07-27T06:51:24.347212Z",
"url": "https://files.pythonhosted.org/packages/20/ac/e26a85455ea4c78dbd203bf7c75246cb7f3b36d601a50e546ec1bf0cbcb6/modelsignature-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 06:51:24",
"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
