Metadata-Version: 2.4
Name: vectorforgeai
Version: 0.1.3
Summary: Official Python SDK for VectorForge Cloud APIs
Project-URL: Homepage, https://vectorforge.ai
Project-URL: Documentation, https://docs.vectorforge.ai
Project-URL: Repository, https://github.com/VectorForgeAI/API
Project-URL: Issues, https://github.com/VectorForgeAI/API/issues
Author-email: VectorForge <support@vectorforge.ai>
License: MIT
Keywords: ai,cryptography,divt,integrity,receipts,vectorforge,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: image
Requires-Dist: pillow>=10.0.0; extra == 'image'
Description-Content-Type: text/markdown

# VectorForge Python SDK

Official Python client for [VectorForge Cloud APIs](https://vectorforge.ai).

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

```bash
pip install vectorforgeai
```

For image support:

```bash
pip install vectorforgeai[image]
```

---

## Quick Start

```python
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

```python
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

```python
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

```python
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]`

```python
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

```python
# 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

```python
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.

```python
# 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)

```python
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)

```python
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

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

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

### List Records

```python
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)

```python
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

```python
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](https://www.npmjs.com/package/@vectorforge-ai/sdk)
- [MCP Server](https://www.npmjs.com/package/@vectorforge-ai/mcp-server)
- [CLI](https://www.npmjs.com/package/@vectorforge-ai/cli)

---

## License

MIT
