SDK Guides

In-depth guides for using the Harpocrates SDKs in JavaScript and Python.

JavaScript SDK

Installation

npm install harpocrates

Initializing the Client

import { Harpocrates } from "harpocrates";

const client = new Harpocrates({
  apiKey: process.env.HARPOCRATES_API_KEY,
  network: "mainnet", // or "testnet"
  timeout: 30000, // Request timeout in ms
});

Making Inference Requests

async function classifyDocument(text) {
  try {
    // Encrypt the sensitive input
    const encrypted = await client.encrypt(text);
    
    // Perform inference
    const result = await client.infer({
      model: "llm-secure-7b",
      input: encrypted,
      parameters: {
        temperature: 0.3,
        max_tokens: 100
      }
    });
    
    // Decrypt the response
    const output = await client.decrypt(result.output);
    
    return output;
  } catch (error) {
    console.error("Inference failed:", error);
    throw error;
  }
}

Working with Encrypted Input/Output

// Encrypt data before sending
const encryptedData = await client.encrypt("Sensitive medical records...");

// Send to Harpocrates
const response = await client.infer({
  model: "llm-secure-7b",
  input: encryptedData
});

// Decrypt the result
const plaintext = await client.decrypt(response.output);

// Optional: Verify the computation was done correctly
const isValid = await client.verifyAttestation(response.attestation);
if (!isValid) {
  throw new Error("Attestation verification failed!");
}

Handling Attestation Proofs

const result = await client.infer({
  model: "llm-secure-7b",
  input: encryptedPrompt,
  return_attestation: true
});

// Verify the ZK proof
const verification = await client.verifyAttestation(result.attestation);

console.log("Enclave verified:", verification.enclave_verified);
console.log("Proof verified:", verification.proof_verified);
console.log("On-chain receipt:", verification.on_chain_receipt);

The SDK automatically manages encryption keys and handles key exchange with the TEE enclave securely.

Python SDK

Installation

pip install harpocrates

Initializing the Client

from harpocrates import Harpocrates
import os

client = Harpocrates(
    api_key=os.getenv("HARPOCRATES_API_KEY"),
    network="mainnet",  # or "testnet"
    timeout=30  # Request timeout in seconds
)

Making Inference Requests

def classify_document(text: str) -> str:
    try:
        # Encrypt the sensitive input
        encrypted = client.encrypt(text)
        
        # Perform inference
        result = client.infer(
            model="llm-secure-7b",
            input=encrypted,
            parameters={
                "temperature": 0.3,
                "max_tokens": 100
            }
        )
        
        # Decrypt the response
        output = client.decrypt(result.output)
        
        return output
    except Exception as e:
        print(f"Inference failed: {e}")
        raise

Using Encryption Helpers

# Encrypt data before sending
encrypted_data = client.encrypt("Sensitive medical records...")

# Send to Harpocrates
response = client.infer(
    model="llm-secure-7b",
    input=encrypted_data
)

# Decrypt the result
plaintext = client.decrypt(response.output)

# Optional: Verify the computation
is_valid = client.verify_attestation(response.attestation)
if not is_valid:
    raise ValueError("Attestation verification failed!")

Verifying ZK Proofs

result = client.infer(
    model="llm-secure-7b",
    input=encrypted_prompt,
    return_attestation=True
)

# Verify the ZK proof
verification = client.verify_attestation(result.attestation)

print(f"Enclave verified: {verification.enclave_verified}")
print(f"Proof verified: {verification.proof_verified}")
print(f"On-chain receipt: {verification.on_chain_receipt}")

Async/Await Support

import asyncio
from harpocrates import AsyncHarpocrates

async def main():
    client = AsyncHarpocrates(
        api_key=os.getenv("HARPOCRATES_API_KEY")
    )
    
    encrypted = await client.encrypt("Confidential data")
    result = await client.infer(
        model="llm-secure-7b",
        input=encrypted
    )
    output = await client.decrypt(result.output)
    
    return output

asyncio.run(main())

Error Handling

Both SDKs provide typed exceptions for different error scenarios:

JavaScript

import { 
  HarpocratesError, 
  AuthenticationError, 
  RateLimitError,
  EncryptionError
} from "harpocrates";

try {
  const result = await client.infer({...});
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limit exceeded, retry after:", error.retryAfter);
  } else if (error instanceof EncryptionError) {
    console.error("Encryption failed:", error.message);
  } else {
    console.error("Unknown error:", error);
  }
}

Python

from harpocrates import (
    HarpocratesError,
    AuthenticationError,
    RateLimitError,
    EncryptionError
)

try:
    result = client.infer(...)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limit exceeded, retry after: {e.retry_after}")
except EncryptionError as e:
    print(f"Encryption failed: {e}")
except HarpocratesError as e:
    print(f"Unknown error: {e}")