Skip to content

SDK Architecture

This document provides an overview of the Unique Python SDK architecture, design patterns, and core components.

Overview

The Unique Python SDK is designed to provide seamless access to the Unique AI platform's REST API. It follows a resource-oriented architecture inspired by the Stripe SDK, making it intuitive for developers familiar with modern API clients.

Core Components

1. API Resources

API Resources are the primary interface for interacting with the Unique AI platform. Each resource corresponds to a specific entity or functionality in the API.

Key Resources:

2. Unique API Proxy

The Unique API proxy provides a secure, OpenAI-compatible gateway for accessing any language model through the Unique platform.

Key Benefits:

  • Secure Access: All LLM requests are authenticated and routed through Unique's secure infrastructure
  • Usage Tracking: Model usage can be recorded and tracked for monitoring and cost management (when enabled)
  • OpenAI Compatibility: Use the standard OpenAI SDK with the same APIs - just reference the OpenAI documentation
  • Unified Interface: Access multiple LLM providers (OpenAI, Azure, Anthropic, etc.) through a single, consistent interface

How It Works:

The proxy accepts OpenAI-compatible requests and routes them through Unique's infrastructure. Simply configure your OpenAI client to point to Unique's proxy endpoint and include authentication headers. The API interface remains identical to OpenAI's, so you can use existing OpenAI code with minimal changes.

See the OpenAI Integration Tutorial for a complete example.

3. Webhook System

The webhook system provides secure, event-driven communication from the Unique platform to your application with HMAC-SHA256 signature verification.

4. Utility Functions

The SDK includes utility modules for:

  • Token management and counting
  • File I/O operations
  • Chat history management
  • Source processing and formatting

Design Patterns

Resource-Oriented Design

Each API endpoint is represented as a resource class with standardized CRUD operations.

Async/Sync Duality

Most operations have both synchronous and asynchronous versions:

1
2
3
4
5
# Synchronous
message = unique_sdk.Message.create(user_id, company_id, **params)

# Asynchronous
message = await unique_sdk.Message.create_async(user_id, company_id, **params)

Automatic Retry with Exponential Backoff

Transient errors are automatically retried with increasing delays (3 retries with 2x backoff factor).

Error Hierarchy

The SDK uses a structured error hierarchy:

  • APIError: Base class for all API errors
  • InvalidRequestError: Client-side validation errors (400)
  • AuthenticationError: Authentication failures (401)
  • PermissionError: Authorization failures (403)
  • NotFoundError: Resource not found (404)
  • RateLimitError: Rate limit exceeded (429)
  • ServerError: Server-side errors (500+)

Security

  • HMAC-SHA256 signature verification for webhooks
  • API Key authentication for all requests
  • Secure credential storage via environment variables
  • Unique API Proxy provides secure, authenticated access to LLMs with optional usage tracking and enterprise-grade security

Performance

  • Connection pooling for efficient HTTP requests
  • Automatic retry with exponential backoff
  • Async support for concurrent operations
  • Bulk operations where available

Next Steps

Now that you understand the SDK architecture:

  1. Get Started - Install and configure the SDK
  2. Try the Quickstart - Make your first API call
  3. Explore API Resources - Browse all available APIs
  4. See Tutorials - Learn from step-by-step tutorials