Installation & Setup

Installation

The Sudo SDK is available for both Python and TypeScript/JavaScript. Choose your preferred language and package manager below.

npm add sudo-ai

pnpm add sudo-ai

yarn add sudo-ai zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.

bun add sudo-ai

pip install sudo-ai

poetry add sudo-ai

uv add sudo-ai

Python: Requires Python 3.9 or later
TypeScript/JavaScript: Requires Node.js 14+ and supports both CommonJS and ES Modules

Authentication

The SDK uses API key authentication. You can obtain your API key from the Sudo Developer Portal.

Environment Variable (Recommended)

Set your API key as an environment variable:

TypeScript

import { Sudo } from "sudo-ai";

const sudo = new Sudo({
  serverURL: "https://sudoapp.dev/api",
  apiKey: process.env.SUDO_API_KEY ?? "",
});

// Your code here

Direct Configuration

Alternatively, you can pass the API key directly:

TypeScript

import { Sudo } from "sudo-ai";

const sudo = new Sudo({
  serverURL: "https://sudoapp.dev/api",
  apiKey: "your-api-key-here",
});

// Your code here

Never hardcode your API key in your source code, especially in code that will be committed to version control. Always use environment variables or secure configuration management.

Basic Configuration

Server URL

By default, the SDK points to the production Sudo API. You can customize this:

TypeScript

import { Sudo } from "sudo-ai";

// Production (default)
const sudo = new Sudo({
  serverURL: "https://sudoapp.dev/api",
  apiKey: "your-api-key"
});

// Custom endpoint
const customSudo = new Sudo({
  serverURL: "https://your-custom-endpoint.com/api",
  apiKey: "your-api-key"
});

from sudo import Sudo

# Production (default)
client = Sudo(
    server_url="https://sudoapp.dev/api",
    api_key="your-api-key"
)

# Custom endpoint
client = Sudo(
    server_url="https://your-custom-endpoint.com/api",
    api_key="your-api-key"
)

Retry Configuration

Configure retry behavior for failed requests:

TypeScript

import { Sudo } from "sudo-ai";

const sudo = new Sudo({
  serverURL: "https://sudoapp.dev/api",
  apiKey: "your-api-key",
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100
    },
    retryConnectionErrors: false
  }
});

// Client will use custom retry configuration

from sudo import Sudo
from sudo.utils import BackoffStrategy, RetryConfig

retry_config = RetryConfig(
    strategy="backoff",
    backoff=BackoffStrategy(
        initial_interval=1,
        max_interval=50,
        exponent=1.1,
        max_elapsed_time=100
    ),
    retry_connection_errors=False
)

with Sudo(
    server_url="https://sudoapp.dev/api",
    api_key="your-api-key",
    retry_config=retry_config
) as client:
    # Client will use custom retry configuration
    pass

Custom HTTP Client

For advanced use cases, you can provide a custom HTTP client:

TypeScript

import { Sudo } from "sudo-ai";
import { HTTPClient } from "sudo-ai/lib/http";

const httpClient = new HTTPClient({
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "value");
  return nextRequest;
});

const sudo = new Sudo({
  serverURL: "https://sudoapp.dev/api",
  apiKey: "your-api-key",
  httpClient
});

from sudo import Sudo
import httpx

# Custom headers for all requests
http_client = httpx.Client(headers={"x-custom-header": "value"})

client = Sudo(
    server_url="https://sudoapp.dev/api",
    api_key="your-api-key",
    client=http_client
)

Async Support

Both SDKs support asynchronous operations:

Async/Await

TypeScript

import { Sudo } from "sudo-ai";

const sudo = new Sudo({
  serverURL: "https://sudoapp.dev/api",
  apiKey: process.env.SUDO_API_KEY ?? "",
});

async function main() {
  try {
    const result = await sudo.system.healthCheck();
    console.log(result);
  } catch (error) {
    console.error("Error:", error);
  }
}

main();

import asyncio
import os
from sudo import Sudo

async def main():
    async with Sudo(
        server_url="https://sudoapp.dev/api",
        api_key=os.getenv("SUDO_API_KEY"),
    ) as client:
        response = await client.system.health_check_async()
        print(response)

asyncio.run(main())

Synchronous Usage (Python Only)

import os
from sudo import Sudo

with Sudo(
    server_url="https://sudoapp.dev/api",
    api_key=os.getenv("SUDO_API_KEY"),
) as client:
    response = client.system.health_check()
    print(response)

Error Handling

Both SDKs provide comprehensive error handling:

TypeScript

import { Sudo } from "sudo-ai";
import * as errors from "sudo-ai/models/errors";

const sudo = new Sudo({
  serverURL: "https://sudoapp.dev/api",
  apiKey: process.env.SUDO_API_KEY ?? "",
});

try {
  const result = await sudo.system.getSupportedModels();
  console.log(result);
} catch (error) {
  if (error instanceof errors.SudoError) {
    console.log(`SDK Error: ${error.message}`);
    console.log(`Status Code: ${error.statusCode}`);
    
    if (error instanceof errors.ErrorResponse) {
      console.log(`Error Details: ${error.data$.error}`);
    }
  }
}

import os
from sudo import Sudo, errors

with Sudo(
    server_url="https://sudoapp.dev/api",
    api_key=os.getenv("SUDO_API_KEY"),
) as client:
    try:
        response = client.system.get_supported_models()
        print(response)
    except errors.ErrorResponse as e:
        print(f"API Error: {e.message}")
        print(f"Status Code: {e.status_code}")
        print(f"Error Details: {e.data.error}")
    except errors.SudoError as e:
        print(f"SDK Error: {e.message}")
        print(f"Status Code: {e.status_code}")

Debugging

Enable debug logging to troubleshoot issues:

Using Environment Variable

export SUDO_DEBUG=true

Language-Specific Debug Configuration

TypeScript

import { Sudo } from "sudo-ai";

const sudo = new Sudo({
  serverURL: "https://sudoapp.dev/api",
  apiKey: process.env.SUDO_API_KEY ?? "",
  debugLogger: console
});

// Warning: This will reveal secrets like API tokens in console output
// Only use during local development

import logging
from sudo import Sudo

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("sudo")

client = Sudo(
    server_url="https://sudoapp.dev/api",
    api_key="your-api-key",
    debug_logger=logger
)

IDE Support

VS Code

Both SDKs work well with VS Code out of the box. For enhanced type checking: TypeScript:

{
    "typescript.preferences.includePackageJsonAutoImports": "on"
}

Python:

{
    "python.analysis.typeCheckingMode": "strict"
}

Other IDEs

PyCharm (Python):

Install the PyCharm Pydantic Plugin
Enable Pydantic support in project settings

WebStorm (TypeScript):

TypeScript support is built-in
Enable TypeScript language service

Next Steps

Now that you have the SDK installed and configured:

Try System Endpoints - Test your setup with health checks
Create AI Responses - Start building AI-powered features
Explore Streaming - Add real-time capabilities

Both SDKs follow semantic versioning. Pin to a specific version in production to ensure stability:Python:

pip install sudo-ai==0.1.0

TypeScript:

npm install sudo-ai@0.1.1

Overview

SDKs

API Reference

Installation

Authentication

Environment Variable (Recommended)

Direct Configuration

Basic Configuration

Server URL

Retry Configuration

Custom HTTP Client

Async Support

Async/Await

Synchronous Usage (Python Only)

Error Handling

Debugging

Using Environment Variable

Language-Specific Debug Configuration

IDE Support

VS Code

Other IDEs

Next Steps

​Installation

​Authentication

​Environment Variable (Recommended)

​Direct Configuration

​Basic Configuration

​Server URL

​Retry Configuration

​Custom HTTP Client

​Async Support

​Async/Await

​Synchronous Usage (Python Only)

​Error Handling

​Debugging

​Using Environment Variable

​Language-Specific Debug Configuration

​IDE Support

​VS Code

​Other IDEs

​Next Steps

Installation

Authentication

Environment Variable (Recommended)

Direct Configuration

Basic Configuration

Server URL

Retry Configuration

Custom HTTP Client

Async Support

Async/Await

Synchronous Usage (Python Only)

Error Handling

Debugging

Using Environment Variable

Language-Specific Debug Configuration

IDE Support

VS Code

Other IDEs

Next Steps