> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudoapp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation & Setup

> Install and configure the Sudo SDK

## Installation

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

<CodeGroup>
  ```bash npm theme={null}
  npm add sudo-ai
  ```

  ```bash pnpm theme={null}
  pnpm add sudo-ai
  ```

  ```bash yarn theme={null}
  yarn add sudo-ai zod

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

  ```bash bun theme={null}
  bun add sudo-ai
  ```

  ```bash pip theme={null}
  pip install sudo-ai
  ```

  ```bash poetry theme={null}
  poetry add sudo-ai
  ```

  ```bash uv theme={null}
  uv add sudo-ai
  ```
</CodeGroup>

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

## Authentication

The SDK uses API key authentication. You can obtain your API key from the [Sudo Developer Portal](https://sudoapp.dev/dev/login).

### Environment Variable (Recommended)

Set your API key as an environment variable:

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

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

  // Your code here
  ```

  ```python Python theme={null}
  import os
  from sudo import Sudo

  with Sudo(
      server_url="https://sudoapp.dev/api",
      api_key=os.getenv("SUDO_API_KEY"),
  ) as client:
      # Your code here
      pass
  ```
</CodeGroup>

### Direct Configuration

Alternatively, you can pass the API key directly:

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

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

  // Your code here
  ```

  ```python Python theme={null}
  from sudo import Sudo

  with Sudo(
      server_url="https://sudoapp.dev/api",
      api_key="your-api-key-here",
  ) as client:
      # Your code here
      pass
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## Basic Configuration

### Server URL

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

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  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"
  });
  ```

  ```python Python theme={null}
  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"
  )
  ```
</CodeGroup>

### Retry Configuration

Configure retry behavior for failed requests:

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

### Custom HTTP Client

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

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  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
  });
  ```

  ```python Python theme={null}
  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
  )
  ```
</CodeGroup>

## Async Support

Both SDKs support asynchronous operations:

### Async/Await

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

### Synchronous Usage (Python Only)

```python theme={null}
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:

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  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}`);
      }
    }
  }
  ```

  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

## Debugging

Enable debug logging to troubleshoot issues:

### Using Environment Variable

```bash theme={null}
export SUDO_DEBUG=true
```

### Language-Specific Debug Configuration

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  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
  ```

  ```python Python theme={null}
  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
  )
  ```
</CodeGroup>

## IDE Support

### VS Code

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

**TypeScript:**

```json theme={null}
{
    "typescript.preferences.includePackageJsonAutoImports": "on"
}
```

**Python:**

```json theme={null}
{
    "python.analysis.typeCheckingMode": "strict"
}
```

### Other IDEs

**PyCharm (Python):**

* Install the [PyCharm Pydantic Plugin](https://docs.pydantic.dev/latest/integrations/pycharm/)
* 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:

1. **[Try System Endpoints](/sdk/sudo-sdk/system-endpoints)** - Test your setup with health checks
2. **[Create AI Responses](/sdk/sudo-sdk/ai-responses)** - Start building AI-powered features
3. **[Explore Streaming](/sdk/sudo-sdk/streaming)** - Add real-time capabilities

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

  **Python:**

  ```bash theme={null}
  pip install sudo-ai==0.1.0
  ```

  **TypeScript:**

  ```bash theme={null}
  npm install sudo-ai@0.1.1
  ```
</Note>