vectorforgeai 0.1.3

Official Python SDK for VectorForge Cloud APIs

VectorForge Python SDK

Official Python client for VectorForge Cloud APIs.

VectorForge is a trust and confidence layer for AI and automations, providing:

• DIVTs (Digital Integrity Verification Tokens) - Cryptographic "birth certificates" for data
• AI Answer Confidence Scoring - Privacy-preserving and comprehensive scoring
• Worldstate Logging - Immutable event capture for AI operations
• Hybrid Post-Quantum Cryptography - ECDSA P-521 + ML-DSA-65 signatures

---

Installation

pip install vectorforgeai

For image support:

pip install vectorforgeai[image]

---

Quick Start

from vectorforge import VectorForgeClient

# Option 1: Use environment variables (recommended)
# export VF_API_BASE_URL="https://api.vectorforge.ai"
# export VF_API_KEY="vf_prod_YourApiKeyHere"
client = VectorForgeClient()

# Option 2: Pass config directly
client = VectorForgeClient(
    base_url="https://api.vectorforge.ai",
    api_key="vf_prod_YourApiKeyHere",
)

# Option 3: Context manager
with VectorForgeClient() as client:
    result = client.register_content("doc-123", "Hello, World!", "test_v1")

---

Register Content

The SDK sends your content to the VectorForge API, which performs canonicalization, hashing, and signing server-side.

Register Text

result = client.register_content(
    object_id="prompt:123",
    text="What is the capital of France?",
    data_type="prompt_receipt_v1",
    metadata={"user_id": "user-456"},
)

print(f"DIVT ID: {result['divt_id']}")
print(f"Ledger status: {result['ledger_status']}")

Register JSON

result = client.register_json(
    object_id="rag_snapshot:v42",
    data={
        "snapshot_type": "rag-corpus",
        "doc_hashes": ["hash1", "hash2"],
        "timestamp": "2025-11-21T10:00:00Z",
    },
    data_type="rag_snapshot_v1",
    metadata={"project": "hr-assistant"},
)

Register Embedding

result = client.register_embedding(
    object_id="chunk:doc-123:p5",
    embedding=[0.123456, -0.987654, 0.456789],
    data_type="rag_chunk_v1",
    metadata={"document_id": "doc-123", "paragraph": 5},
)

Register Image

Requires: pip install vectorforgeai[image]

with open("receipt.png", "rb") as f:
    image_bytes = f.read()

result = client.register_image(
    object_id="image:receipt-456",
    image_bytes=image_bytes,
    data_type="image_receipt_v1",
    metadata={"source": "mobile_app"},
)

---

Verify Content

# Verify text
result = client.verify_content(divt_id, "What is the capital of France?")

# Verify JSON
result = client.verify_json(divt_id, {"key": "value"})

if result["verified"]:
    print("DIVT is valid")
    print(f"  Hash valid: {result['hash_valid']}")
    print(f"  ECDSA valid: {result['ecdsa_signature_valid']}")
    print(f"  ML-DSA valid: {result['ml_dsa_signature_valid']}")

---

Complete Example

from vectorforge import VectorForgeClient

with VectorForgeClient() as client:
    # Register
    prompt_data = {
        "prompt": "What is the capital of France?",
        "response": "Paris",
        "model": "gpt-4",
        "timestamp": "2025-11-21T10:00:00Z",
    }

    reg = client.register_json(
        object_id="prompt_receipt:flow-abc-123",
        data=prompt_data,
        data_type="prompt_receipt_v1",
        metadata={"workflow": "customer_support"},
    )

    print(f"Registered: {reg['divt_id']}")

    # Verify
    ver = client.verify_json(reg["divt_id"], prompt_data)

    if ver["verified"]:
        print("Verified - content is untampered")
    else:
        print("Verification failed - content was modified")

---

Bundle API

Get a comprehensive verification bundle including DIVT, worldstate context, and scoring.

# By DIVT ID
bundle = client.get_bundle({
    "divt_id": "019abc12-3456-7890-abcd-ef0123456789",
})

print(f"Verified: {bundle['divt']['verified']}")
print(f"Generated at: {bundle['bundle_metadata']['generated_at']}")

# By object ID
bundle = client.get_bundle({
    "object_id": "prompt_receipt:flow-abc-123",
    "include_history": True,
})

---

Scoring API

Privacy Score (No Raw Content Sent)

result = client.score_privacy({
    "query_id": "query-123",
    "answer_id": "answer-456",
    "evidence": [
        {
            "object_id": "chunk:doc-1:p1",
            "divt_id": "019abc...",
            "tenant_id": "my-tenant",
            "similarity": 0.95,
            "chunk_confidence": 0.9,
        },
    ],
})

print(f"Overall confidence: {result['overall_confidence']}")
print(f"Integrity score: {result['integrity_score']}")

Full Score (With Groq Judge)

result = client.score_full({
    "query": "What is the capital of France?",
    "answer": "The capital of France is Paris.",
    "evidence": [
        {
            "object_id": "chunk:doc-1:p1",
            "divt_id": "019abc...",
            "tenant_id": "my-tenant",
            "text": "Paris is the capital city of France.",
            "similarity": 0.95,
        },
    ],
    "options": {"log_worldstate": "minimal"},
})

print(f"Support: {result.get('support_score')}")
print(f"Faithfulness: {result.get('faithfulness_score')}")

---

Worldstate

Get Single Record

item = client.get_worldstate_item({
    "wsl_id": "019abc12-3456-7890-abcd-ef0123456789",
    "include_data": True,
})

print(f"Kind: {item['kind']}")

List Records

result = client.list_worldstate({
    "kind": "prompt_receipt",
    "created_from": "2025-11-01T00:00:00Z",
    "limit": 50,
})

for item in result["items"]:
    print(f"{item['wsl_id']}: {item.get('data_summary')}")

# Paginate
cursor = result.get("cursor")
while cursor:
    page = client.list_worldstate({"cursor": cursor})
    cursor = page.get("cursor")

---

Stream Events (SSE)

from datetime import datetime, timedelta

one_hour_ago = (datetime.utcnow() - timedelta(hours=1)).isoformat() + "Z"

client.stream_events(
    {
        "since": one_hour_ago,
        "types": ["divt_registered", "scoring_event"],
        "limit": 50,
    },
    on_event=lambda event: print(f"[{event['type']}] {event['id']}"),
)

---

Error Handling

from vectorforge import VectorForgeClient, VectorForgeAPIError

try:
    result = client.register_content("doc-123", "Hello", "test_v1")
except VectorForgeAPIError as e:
    print(f"{e.status_code}: {e.message}")
    print(f"Code: {e.error}")

Common errors:

• invalid_api_key (401) - API key invalid or expired
• quota_exceeded (429) - Monthly limit reached
• rate_limit_exceeded (429) - Too many requests
• plan_limitation (403) - Feature not on your plan

---

Requirements

• Python >= 3.9
• Dependencies: requests >= 2.28.0
• Optional: Pillow >= 10.0.0 (for image registration)

---

Related

• Node.js SDK
• MCP Server
• CLI

---

License

MIT