Documentation

SDKs & Libraries

Official client libraries for Python and Node.js. Auto-generated from our OpenAPI spec with full type safety, automatic retries, and streaming support.

Overview

While you can use the Bolor Intelligence REST API directly with any HTTP client, our official SDKs provide a more productive developer experience. Every SDK includes:

  • •Full type definitions for all request and response objects
  • •Automatic retry logic with exponential backoff for rate limits and transient errors
  • •Built-in webhook signature verification helpers
  • •Streaming support for long-running operations
  • •Comprehensive error handling with typed exceptions
Py

Python SDK

Python 3.8+

pip install bolor-ai
JS

Node.js SDK

Node.js 18+, TypeScript supported

npm install @bolor-ai/sdk

Python SDK

Installation

terminal
# Using pip
pip install bolor-ai

# Using Poetry
poetry add bolor-ai

# Using uv
uv add bolor-ai

Quick Start

python
from bolor import BolorClient

# Initialize the client
client = BolorClient(api_key="sk-your-api-key")

# --- OrchestrAI: Route a query ---
response = client.orchestrai.route(
    query="Analyze the risk factors in this quarterly report",
    max_latency_ms=10000,
    min_confidence=0.8
)
print(f"Answer: {response.text}")
print(f"Model: {response.model_used}, Confidence: {response.confidence}")

# --- AgentGuard: Verify an action ---
verification = client.agentguard.verify(
    agent_id="support_agent_v2",
    action={
        "tool": "refund_api",
        "method": "POST",
        "params": {"amount": 150.00, "order_id": "ORD-12345"}
    }
)
if verification.approved:
    print("Action approved, safe to execute")
else:
    print(f"Action blocked: {verification.reason}")

# --- MindVault: Store and recall knowledge ---
client.mindvault.store(
    subject="Customer Acme Corp",
    content="Renewed enterprise contract for 3 years at $500k/year",
    metadata={"type": "contract", "value": 1500000}
)

memories = client.mindvault.recall(
    query="What do we know about Acme Corp?",
    limit=5
)
for memory in memories:
    print(f"- {memory.content} (relevance: {memory.score:.2f})")

Async Support

python
from bolor import AsyncBolorClient
import asyncio

async def main():
    client = AsyncBolorClient(api_key="sk-your-api-key")

    # Run multiple queries concurrently
    results = await asyncio.gather(
        client.orchestrai.route(query="Summarize this document"),
        client.orchestrai.route(query="Extract key entities"),
        client.orchestrai.route(query="Identify sentiment"),
    )

    for result in results:
        print(f"{result.model_used}: {result.text[:100]}...")

    await client.close()

asyncio.run(main())

Error Handling

python
from bolor import BolorClient
from bolor.exceptions import (
    AuthenticationError,
    RateLimitError,
    ValidationError,
    ServerError,
)

client = BolorClient(api_key="sk-your-api-key")

try:
    response = client.orchestrai.route(query="Hello")
except AuthenticationError:
    print("Invalid API key or insufficient permissions")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except ServerError:
    print("Server error, please try again later")

Node.js SDK

Installation

terminal
# Using npm
npm install @bolor-ai/sdk

# Using yarn
yarn add @bolor-ai/sdk

# Using pnpm
pnpm add @bolor-ai/sdk

Quick Start

typescript
import { BolorClient } from "@bolor-ai/sdk";

const client = new BolorClient({
  apiKey: "sk-your-api-key",
});

// --- OrchestrAI: Route a query ---
const response = await client.orchestrai.route({
  query: "Analyze the risk factors in this quarterly report",
  maxLatencyMs: 10000,
  minConfidence: 0.8,
});
console.log(`Answer: ${response.text}`);
console.log(`Model: ${response.modelUsed}, Confidence: ${response.confidence}`);

// --- AgentGuard: Verify an action ---
const verification = await client.agentguard.verify({
  agentId: "support_agent_v2",
  action: {
    tool: "refund_api",
    method: "POST",
    params: { amount: 150.0, orderId: "ORD-12345" },
  },
});

if (verification.approved) {
  console.log("Action approved, safe to execute");
} else {
  console.log(`Action blocked: ${verification.reason}`);
}

// --- MindVault: Store and recall knowledge ---
await client.mindvault.store({
  subject: "Customer Acme Corp",
  content: "Renewed enterprise contract for 3 years at $500k/year",
  metadata: { type: "contract", value: 1500000 },
});

const memories = await client.mindvault.recall({
  query: "What do we know about Acme Corp?",
  limit: 5,
});

for (const memory of memories) {
  console.log(`- ${memory.content} (relevance: ${memory.score.toFixed(2)})`);
}

Webhook Verification Helper

typescript
import { verifyWebhookSignature } from "@bolor-ai/sdk";
import express from "express";

const app = express();

app.post("/webhooks/bolor", express.raw({ type: "*/*" }), (req, res) => {
  const signature = req.headers["x-bolor-signature"] as string;

  const isValid = verifyWebhookSignature({
    payload: req.body.toString(),
    signature,
    secret: process.env.BOLOR_WEBHOOK_SECRET!,
  });

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString());
  console.log(`Received event: ${event.type}`);

  res.status(200).send("OK");
});

Error Handling

typescript
import {
  BolorClient,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  ServerError,
} from "@bolor-ai/sdk";

const client = new BolorClient({ apiKey: "sk-your-api-key" });

try {
  const response = await client.orchestrai.route({
    query: "Hello",
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key or insufficient permissions");
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ValidationError) {
    console.error(`Invalid request: ${error.message}`);
  } else if (error instanceof ServerError) {
    console.error("Server error, please try again later");
  }
}

SDK Configuration

Both SDKs support the following configuration options. These can be passed during client initialization.

OptionDefaultDescription
apiKeyrequiredYour Bolor Intelligence API key
baseUrlhttps://api.bolor.ai/v1API base URL (useful for self-hosted deployments)
timeout30000Request timeout in milliseconds
maxRetries3Maximum number of retries for failed requests
debugfalseEnable debug logging for request/response details

Environment Variables

Both SDKs automatically read configuration from environment variables if no explicit values are provided.

.env
# Required
BOLOR_API_KEY=sk-your-api-key

# Optional
BOLOR_BASE_URL=https://api.bolor.ai/v1
BOLOR_TIMEOUT=30000
BOLOR_MAX_RETRIES=3
BOLOR_DEBUG=false

# Webhook verification
BOLOR_WEBHOOK_SECRET=whsec_your_signing_secret

Next Steps