---

Installation

# 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.

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

---

Model Registration

Register your model to get a feedback page where users can submit reports:

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 or API. See full documentation for details.

---

Receiving User Feedback

View Incident Reports

# 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:

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

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

# 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

# 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

# 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

client = ModelSignatureClient(
    api_key="your_key",
    base_url="https://api.modelsignature.com",
    timeout=30,
    max_retries=3,
    debug=True
)

---

Error Handling

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/ directory for integration patterns:

• Embedding Example - LoRA fine-tuning
• Incident Reporting - User feedback workflow
• OpenAI Integration - Function calling
• Anthropic Integration - Tool integration
• Middleware Example - Request interception

---

Documentation

• API Documentation
• Web Dashboard
• Quick Start Guide
• Integration Examples

---

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
• Issues: GitHub Issues
• Email: support@modelsignature.com

---

License

MIT License - see LICENSE file for details.