# Citrate Python SDK
A comprehensive Python SDK for interacting with the Citrate AI blockchain platform. Deploy AI models, execute inferences, manage encryption, and handle payments with ease.
## Features
- **Model Deployment**: Deploy AI models to Citrate blockchain with encryption and access control
- **Inference Execution**: Run AI inference on deployed models with pay-per-use pricing
- **Encryption & Security**: End-to-end encryption for model weights and inference data
- **Payment Integration**: Built-in payment handling for model access and revenue sharing
- **Multi-format Support**: CoreML, ONNX, TensorFlow, PyTorch model support
## Installation
```bash
pip install citrate-sdk
```
## Quick Start
```python
from citrate_sdk import CitrateClient, ModelConfig
# Connect to Citrate network
client = CitrateClient("https://mainnet.citrate.ai")
# Deploy encrypted model
model = client.deploy_model(
model_path="./my_model.mlpackage",
config=ModelConfig(
encrypted=True,
access_price=0.01, # ETH per inference
access_list=["0x123..."]
)
)
# Execute inference
result = client.inference(
model_id=model.id,
input_data={"text": "Hello world"},
encrypted=True
)
print(f"Model output: {result.output_data}")
```
## Authentication
### Using Private Key
```python
from citrate_sdk import CitrateClient
# Initialize with private key
client = CitrateClient(
rpc_url="https://mainnet.citrate.ai",
private_key="0x1234..."
)
```
### Generate New Key
```python
from citrate_sdk.crypto import KeyManager
# Generate new key pair
key_manager = KeyManager()
print(f"Address: {key_manager.get_address()}")
print(f"Private Key: {key_manager.get_private_key()}")
```
## Model Deployment
### Basic Deployment
```python
from citrate_sdk import ModelConfig, ModelType, AccessType
config = ModelConfig(
name="My Model",
description="A powerful AI model",
model_type=ModelType.COREML,
access_type=AccessType.PUBLIC
)
deployment = client.deploy_model("./model.mlpackage", config)
print(f"Model ID: {deployment.model_id}")
```
### Encrypted Deployment
```python
from citrate_sdk import EncryptionConfig
config = ModelConfig(
encrypted=True,
encryption_config=EncryptionConfig(
threshold_shares=3,
total_shares=5
),
access_type=AccessType.PAID,
access_price=1000000000000000000 # 1 ETH in wei
)
deployment = client.deploy_model("./model.mlpackage", config)
```
## Inference Execution
### Public Model Inference
```python
# Run inference on public model
result = client.inference(
model_id="model_abc123",
input_data={
"text": "Classify this text",
"image": "base64_encoded_image"
}
)
print(f"Prediction: {result.output_data}")
print(f"Confidence: {result.confidence}")
print(f"Gas used: {result.gas_used}")
```
### Paid Model Access
```python
# Purchase access to paid model
tx_hash = client.purchase_model_access(
model_id="model_xyz789",
payment_amount=1000000000000000000 # 1 ETH
)
# Execute inference after purchase
result = client.inference(
model_id="model_xyz789",
input_data={"text": "Premium inference"}
)
```
### Encrypted Inference
```python
# Run encrypted inference
result = client.inference(
model_id="encrypted_model_456",
input_data={"sensitive_data": "private input"},
encrypted=True
)
```
## Model Management
### List Available Models
```python
# List all public models
models = client.list_models(limit=50)
for model in models:
print(f"{model['name']}: {model['model_id']}")
```
### Get Model Information
```python
info = client.get_model_info("model_abc123")
print(f"Owner: {info['owner']}")
print(f"Price: {info['access_price']} wei")
print(f"Total inferences: {info['total_inferences']}")
```
## Encryption & Security
### Manual Encryption
```python
from citrate_sdk.crypto import KeyManager
key_manager = KeyManager("0x1234...")
# Encrypt arbitrary data
encrypted = key_manager.encrypt_data("sensitive information")
# Decrypt data
decrypted = key_manager.decrypt_data(encrypted)
```
### Shared Key Derivation
```python
# Generate ECDH shared key with another party
peer_public_key = "0x5678..."
shared_key = key_manager.derive_shared_key(peer_public_key)
```
## Error Handling
```python
from citrate_sdk.errors import (
ModelNotFoundError,
InsufficientFundsError,
InferenceError
)
try:
result = client.inference("invalid_model", {"data": "test"})
except ModelNotFoundError:
print("Model doesn't exist")
except InsufficientFundsError:
print("Not enough funds for inference")
except InferenceError as e:
print(f"Inference failed: {e}")
```
## Configuration
### Custom RPC Endpoint
```python
# Connect to local development node
client = CitrateClient("http://localhost:8545")
# Connect to testnet
client = CitrateClient("https://testnet.citrate.ai")
```
### Advanced Configuration
```python
from citrate_sdk import CitrateClient
client = CitrateClient(
rpc_url="https://mainnet.citrate.ai",
private_key="0x1234...",
)
# Customize timeouts and gas limits
result = client.inference(
model_id="model_123",
input_data={"text": "test"},
max_gas=2000000 # Higher gas limit
)
```
## Examples
### Image Classification
```python
import base64
from citrate_sdk import CitrateClient, ModelConfig, ModelType
client = CitrateClient(private_key="0x1234...")
# Deploy image classifier
config = ModelConfig(
name="Image Classifier",
model_type=ModelType.COREML,
access_type=AccessType.PAID,
access_price=100000000000000000 # 0.1 ETH
)
model = client.deploy_model("./classifier.mlpackage", config)
# Classify image
with open("image.jpg", "rb") as f:
image_data = base64.b64encode(f.read()).decode()
result = client.inference(
model_id=model.model_id,
input_data={"image": image_data}
)
print(f"Classification: {result.output_data['label']}")
print(f"Confidence: {result.output_data['confidence']}")
```
### Text Generation
```python
# Deploy text generation model
config = ModelConfig(
name="Text Generator",
model_type=ModelType.PYTORCH,
access_type=AccessType.PUBLIC
)
model = client.deploy_model("./text_gen.pt", config)
# Generate text
result = client.inference(
model_id=model.model_id,
input_data={
"prompt": "The future of AI is",
"max_tokens": 100,
"temperature": 0.7
}
)
print(f"Generated: {result.output_data['text']}")
```
## API Reference
### CitrateClient
#### Methods
- `deploy_model(model_path, config)` - Deploy AI model
- `inference(model_id, input_data, **kwargs)` - Execute inference
- `get_model_info(model_id)` - Get model information
- `list_models(owner=None, limit=100)` - List available models
- `purchase_model_access(model_id, amount)` - Purchase model access
### ModelConfig
#### Parameters
- `name` - Model name
- `description` - Model description
- `model_type` - ModelType enum (COREML, ONNX, etc.)
- `access_type` - AccessType enum (PUBLIC, PRIVATE, PAID)
- `encrypted` - Enable encryption (bool)
- `access_price` - Price per inference in wei (int)
### KeyManager
#### Methods
- `get_address()` - Get Ethereum address
- `encrypt_data(data)` - Encrypt string data
- `decrypt_data(encrypted)` - Decrypt string data
- `derive_shared_key(peer_pubkey)` - ECDH key derivation
## Development
### Testing
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/
# Run with coverage
pytest --cov=citrate_sdk tests/
```
### Code Formatting
```bash
# Format code
black citrate_sdk/
# Check style
flake8 citrate_sdk/
# Type checking
mypy citrate_sdk/
```
## Support
- **Documentation**: https://docs.citrate.ai
- **GitHub**: https://github.com/citrate-ai/citrate
- **Discord**: https://discord.gg/citrate
- **Issues**: https://github.com/citrate-ai/citrate/issues
## License
Apache License 2.0 - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/citrate-ai/citrate-v3",
"name": "citrate-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Citrate Team <developers@citrate.ai>",
"keywords": "citrate, blockchain, ai, dag, web3, machine-learning",
"author": "Citrate Team",
"author_email": "Citrate Team <developers@citrate.ai>",
"download_url": "https://files.pythonhosted.org/packages/9b/12/b0d1a3b32ea758444613ee2aa4dd1e285243748a7f420d1738c52bc19e9c/citrate_sdk-0.1.0.tar.gz",
"platform": null,
"description": "# Citrate Python SDK\n\nA comprehensive Python SDK for interacting with the Citrate AI blockchain platform. Deploy AI models, execute inferences, manage encryption, and handle payments with ease.\n\n## Features\n\n- **Model Deployment**: Deploy AI models to Citrate blockchain with encryption and access control\n- **Inference Execution**: Run AI inference on deployed models with pay-per-use pricing\n- **Encryption & Security**: End-to-end encryption for model weights and inference data\n- **Payment Integration**: Built-in payment handling for model access and revenue sharing\n- **Multi-format Support**: CoreML, ONNX, TensorFlow, PyTorch model support\n\n## Installation\n\n```bash\npip install citrate-sdk\n```\n\n## Quick Start\n\n```python\nfrom citrate_sdk import CitrateClient, ModelConfig\n\n# Connect to Citrate network\nclient = CitrateClient(\"https://mainnet.citrate.ai\")\n\n# Deploy encrypted model\nmodel = client.deploy_model(\n model_path=\"./my_model.mlpackage\",\n config=ModelConfig(\n encrypted=True,\n access_price=0.01, # ETH per inference\n access_list=[\"0x123...\"]\n )\n)\n\n# Execute inference\nresult = client.inference(\n model_id=model.id,\n input_data={\"text\": \"Hello world\"},\n encrypted=True\n)\n\nprint(f\"Model output: {result.output_data}\")\n```\n\n## Authentication\n\n### Using Private Key\n\n```python\nfrom citrate_sdk import CitrateClient\n\n# Initialize with private key\nclient = CitrateClient(\n rpc_url=\"https://mainnet.citrate.ai\",\n private_key=\"0x1234...\"\n)\n```\n\n### Generate New Key\n\n```python\nfrom citrate_sdk.crypto import KeyManager\n\n# Generate new key pair\nkey_manager = KeyManager()\nprint(f\"Address: {key_manager.get_address()}\")\nprint(f\"Private Key: {key_manager.get_private_key()}\")\n```\n\n## Model Deployment\n\n### Basic Deployment\n\n```python\nfrom citrate_sdk import ModelConfig, ModelType, AccessType\n\nconfig = ModelConfig(\n name=\"My Model\",\n description=\"A powerful AI model\",\n model_type=ModelType.COREML,\n access_type=AccessType.PUBLIC\n)\n\ndeployment = client.deploy_model(\"./model.mlpackage\", config)\nprint(f\"Model ID: {deployment.model_id}\")\n```\n\n### Encrypted Deployment\n\n```python\nfrom citrate_sdk import EncryptionConfig\n\nconfig = ModelConfig(\n encrypted=True,\n encryption_config=EncryptionConfig(\n threshold_shares=3,\n total_shares=5\n ),\n access_type=AccessType.PAID,\n access_price=1000000000000000000 # 1 ETH in wei\n)\n\ndeployment = client.deploy_model(\"./model.mlpackage\", config)\n```\n\n## Inference Execution\n\n### Public Model Inference\n\n```python\n# Run inference on public model\nresult = client.inference(\n model_id=\"model_abc123\",\n input_data={\n \"text\": \"Classify this text\",\n \"image\": \"base64_encoded_image\"\n }\n)\n\nprint(f\"Prediction: {result.output_data}\")\nprint(f\"Confidence: {result.confidence}\")\nprint(f\"Gas used: {result.gas_used}\")\n```\n\n### Paid Model Access\n\n```python\n# Purchase access to paid model\ntx_hash = client.purchase_model_access(\n model_id=\"model_xyz789\",\n payment_amount=1000000000000000000 # 1 ETH\n)\n\n# Execute inference after purchase\nresult = client.inference(\n model_id=\"model_xyz789\",\n input_data={\"text\": \"Premium inference\"}\n)\n```\n\n### Encrypted Inference\n\n```python\n# Run encrypted inference\nresult = client.inference(\n model_id=\"encrypted_model_456\",\n input_data={\"sensitive_data\": \"private input\"},\n encrypted=True\n)\n```\n\n## Model Management\n\n### List Available Models\n\n```python\n# List all public models\nmodels = client.list_models(limit=50)\n\nfor model in models:\n print(f\"{model['name']}: {model['model_id']}\")\n```\n\n### Get Model Information\n\n```python\ninfo = client.get_model_info(\"model_abc123\")\n\nprint(f\"Owner: {info['owner']}\")\nprint(f\"Price: {info['access_price']} wei\")\nprint(f\"Total inferences: {info['total_inferences']}\")\n```\n\n## Encryption & Security\n\n### Manual Encryption\n\n```python\nfrom citrate_sdk.crypto import KeyManager\n\nkey_manager = KeyManager(\"0x1234...\")\n\n# Encrypt arbitrary data\nencrypted = key_manager.encrypt_data(\"sensitive information\")\n\n# Decrypt data\ndecrypted = key_manager.decrypt_data(encrypted)\n```\n\n### Shared Key Derivation\n\n```python\n# Generate ECDH shared key with another party\npeer_public_key = \"0x5678...\"\nshared_key = key_manager.derive_shared_key(peer_public_key)\n```\n\n## Error Handling\n\n```python\nfrom citrate_sdk.errors import (\n ModelNotFoundError,\n InsufficientFundsError,\n InferenceError\n)\n\ntry:\n result = client.inference(\"invalid_model\", {\"data\": \"test\"})\nexcept ModelNotFoundError:\n print(\"Model doesn't exist\")\nexcept InsufficientFundsError:\n print(\"Not enough funds for inference\")\nexcept InferenceError as e:\n print(f\"Inference failed: {e}\")\n```\n\n## Configuration\n\n### Custom RPC Endpoint\n\n```python\n# Connect to local development node\nclient = CitrateClient(\"http://localhost:8545\")\n\n# Connect to testnet\nclient = CitrateClient(\"https://testnet.citrate.ai\")\n```\n\n### Advanced Configuration\n\n```python\nfrom citrate_sdk import CitrateClient\n\nclient = CitrateClient(\n rpc_url=\"https://mainnet.citrate.ai\",\n private_key=\"0x1234...\",\n)\n\n# Customize timeouts and gas limits\nresult = client.inference(\n model_id=\"model_123\",\n input_data={\"text\": \"test\"},\n max_gas=2000000 # Higher gas limit\n)\n```\n\n## Examples\n\n### Image Classification\n\n```python\nimport base64\nfrom citrate_sdk import CitrateClient, ModelConfig, ModelType\n\nclient = CitrateClient(private_key=\"0x1234...\")\n\n# Deploy image classifier\nconfig = ModelConfig(\n name=\"Image Classifier\",\n model_type=ModelType.COREML,\n access_type=AccessType.PAID,\n access_price=100000000000000000 # 0.1 ETH\n)\n\nmodel = client.deploy_model(\"./classifier.mlpackage\", config)\n\n# Classify image\nwith open(\"image.jpg\", \"rb\") as f:\n image_data = base64.b64encode(f.read()).decode()\n\nresult = client.inference(\n model_id=model.model_id,\n input_data={\"image\": image_data}\n)\n\nprint(f\"Classification: {result.output_data['label']}\")\nprint(f\"Confidence: {result.output_data['confidence']}\")\n```\n\n### Text Generation\n\n```python\n# Deploy text generation model\nconfig = ModelConfig(\n name=\"Text Generator\",\n model_type=ModelType.PYTORCH,\n access_type=AccessType.PUBLIC\n)\n\nmodel = client.deploy_model(\"./text_gen.pt\", config)\n\n# Generate text\nresult = client.inference(\n model_id=model.model_id,\n input_data={\n \"prompt\": \"The future of AI is\",\n \"max_tokens\": 100,\n \"temperature\": 0.7\n }\n)\n\nprint(f\"Generated: {result.output_data['text']}\")\n```\n\n## API Reference\n\n### CitrateClient\n\n#### Methods\n\n- `deploy_model(model_path, config)` - Deploy AI model\n- `inference(model_id, input_data, **kwargs)` - Execute inference\n- `get_model_info(model_id)` - Get model information\n- `list_models(owner=None, limit=100)` - List available models\n- `purchase_model_access(model_id, amount)` - Purchase model access\n\n### ModelConfig\n\n#### Parameters\n\n- `name` - Model name\n- `description` - Model description\n- `model_type` - ModelType enum (COREML, ONNX, etc.)\n- `access_type` - AccessType enum (PUBLIC, PRIVATE, PAID)\n- `encrypted` - Enable encryption (bool)\n- `access_price` - Price per inference in wei (int)\n\n### KeyManager\n\n#### Methods\n\n- `get_address()` - Get Ethereum address\n- `encrypt_data(data)` - Encrypt string data\n- `decrypt_data(encrypted)` - Decrypt string data\n- `derive_shared_key(peer_pubkey)` - ECDH key derivation\n\n## Development\n\n### Testing\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest tests/\n\n# Run with coverage\npytest --cov=citrate_sdk tests/\n```\n\n### Code Formatting\n\n```bash\n# Format code\nblack citrate_sdk/\n\n# Check style\nflake8 citrate_sdk/\n\n# Type checking\nmypy citrate_sdk/\n```\n\n## Support\n\n- **Documentation**: https://docs.citrate.ai\n- **GitHub**: https://github.com/citrate-ai/citrate\n- **Discord**: https://discord.gg/citrate\n- **Issues**: https://github.com/citrate-ai/citrate/issues\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python SDK for Citrate AI blockchain platform",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/citrate-ai/citrate/issues",
"Changelog": "https://github.com/citrate-ai/citrate/blob/main/CHANGELOG.md",
"Documentation": "https://docs.citrate.ai",
"Homepage": "https://citrate.ai",
"Repository": "https://github.com/citrate-ai/citrate"
},
"split_keywords": [
"citrate",
" blockchain",
" ai",
" dag",
" web3",
" machine-learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "770d1db3e93d6580214750a7039bd3cdf64c793b5243d9ec02b4fd18a9756b57",
"md5": "2552b6b0b6c7c7aff8d443ab414b209d",
"sha256": "fc58526eb7e1825dec21abe7e99ea54e4f65a19fab80e22d094af79d83437d09"
},
"downloads": -1,
"filename": "citrate_sdk-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2552b6b0b6c7c7aff8d443ab414b209d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20207,
"upload_time": "2025-10-27T05:38:23",
"upload_time_iso_8601": "2025-10-27T05:38:23.128878Z",
"url": "https://files.pythonhosted.org/packages/77/0d/1db3e93d6580214750a7039bd3cdf64c793b5243d9ec02b4fd18a9756b57/citrate_sdk-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9b12b0d1a3b32ea758444613ee2aa4dd1e285243748a7f420d1738c52bc19e9c",
"md5": "aab0723a2959bdd684eb21adc38615f5",
"sha256": "e354c9b0280c10393dc2c7f52da89cdebcbf9da916ee4ea15ce597001ea4f26f"
},
"downloads": -1,
"filename": "citrate_sdk-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "aab0723a2959bdd684eb21adc38615f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22095,
"upload_time": "2025-10-27T05:38:24",
"upload_time_iso_8601": "2025-10-27T05:38:24.945699Z",
"url": "https://files.pythonhosted.org/packages/9b/12/b0d1a3b32ea758444613ee2aa4dd1e285243748a7f420d1738c52bc19e9c/citrate_sdk-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 05:38:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "citrate-ai",
"github_project": "citrate-v3",
"github_not_found": true,
"lcname": "citrate-sdk"
}
JSON
