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

# SDK Overview

> Overview of OpenFiles SDKs - import paths, configuration options, and technical reference.

## Import Paths

<CodeGroup>
  ```typescript TypeScript theme={null}
  // OpenAI integration
  import OpenAI from '@openfiles-ai/sdk/openai'

  // Tools integration
  import { OpenFilesTools } from '@openfiles-ai/sdk/tools'

  // Core client
  import { OpenFilesClient } from '@openfiles-ai/sdk/core'
  ```

  ```python Python theme={null}
  # OpenAI integration
  from openfiles_ai import OpenAI

  # Tools integration
  from openfiles_ai.tools import OpenFilesTools

  # Core client
  from openfiles_ai import OpenFilesClient
  ```
</CodeGroup>

## Configuration Options

### OpenAI Integration

<CodeGroup>
  ```typescript TypeScript theme={null}
  const ai = new OpenAI({
    apiKey: string,                    // OpenAI API key (required)
    openFilesApiKey: string,           // OpenFiles API key (required)  
    basePath?: string,                 // File path prefix (optional)
    timeout?: number,                  // Request timeout ms (default: 60000)
    maxRetries?: number                // Failed request retries (default: 3)
  })
  ```

  ```python Python theme={null}
  ai = OpenAI(
      api_key='sk-...',                # OpenAI API key (required)
      openfiles_api_key='oa-...',      # OpenFiles API key (required)
      base_path='my-project',          # File path prefix (optional)
      timeout=60000,                   # Request timeout ms (default: 60000)
      max_retries=3                    # Failed request retries (default: 3)
  )
  ```
</CodeGroup>

### Tools Integration

<CodeGroup>
  ```typescript TypeScript theme={null}
  const tools = new OpenFilesTools({
    apiKey: string,                    // OpenFiles API key (required)
    basePath?: string,                 // File path prefix (optional)
    timeout?: number,                  // Request timeout ms (default: 60000)
    maxRetries?: number                // Failed request retries (default: 3)
  })

  // Access provider-specific tools
  tools.openai.definitions           // OpenAI tool definitions
  tools.anthropic.definitions        // Anthropic tool definitions
  ```

  ```python Python theme={null}
  tools = OpenFilesTools(
      api_key='oa-...',                # OpenFiles API key (required)
      base_path='my-project',          # File path prefix (optional)
      timeout=60000,                   # Request timeout ms (default: 60000)
      max_retries=3                    # Failed request retries (default: 3)
  )

  # Access provider-specific tools
  tools.openai.definitions           # OpenAI tool definitions
  tools.anthropic.definitions        # Anthropic tool definitions
  ```
</CodeGroup>

### Core Client

<CodeGroup>
  ```typescript TypeScript theme={null}
  const client = new OpenFilesClient({
    apiKey: string,                    // OpenFiles API key (required)
    baseUrl?: string,                  // API base URL (default: https://api.openfiles.ai/functions/v1/api)
    basePath?: string,                 // File path prefix (optional) 
    timeout?: number,                  // Request timeout ms (default: 60000)
    maxRetries?: number                // Failed request retries (default: 3)
  })
  ```

  ```python Python theme={null}
  client = OpenFilesClient(
      api_key='oa-...',                # OpenFiles API key (required)
      base_url='https://api.openfiles.ai/functions/v1/api',  # API base URL
      base_path='my-project',          # File path prefix (optional)
      timeout=60000,                   # Request timeout ms (default: 60000)
      max_retries=3                    # Failed request retries (default: 3)
  )
  ```
</CodeGroup>

## File Constraints

| Constraint          | Limit           | Notes                       |
| ------------------- | --------------- | --------------------------- |
| File size           | 10MB            | Per file operation          |
| Path length         | 1000 characters | Including all path segments |
| Filename length     | 255 characters  | Per path segment            |
| Request timeout     | 60 seconds      | Configurable up to 300s     |
| Concurrent requests | 100             | Per API key                 |

## Path Format

* Use forward slashes: `folder/subfolder/file.txt`
* No leading slashes: `file.txt` not `/file.txt`
* No trailing slashes: `folder/file.txt` not `folder/file.txt/`
* Case sensitive on all platforms

## Error Handling

### HTTP Status Codes

* `400` - Bad Request (invalid parameters)
* `401` - Unauthorized (invalid API key)
* `404` - Not Found (file doesn't exist)
* `409` - Conflict (file already exists for write operations)
* `413` - Payload Too Large (file exceeds size limit)
* `429` - Rate Limited (too many requests)
* `500` - Internal Server Error

### SDK Error Types

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { FileOperationError } from '@openfiles-ai/sdk/core'

  try {
    await client.writeFile({ path: 'file.txt', content: 'hello' })
  } catch (error) {
    if (error instanceof FileOperationError) {
      console.log(error.statusCode)  // HTTP status
      console.log(error.code)        // Error code
      console.log(error.message)     // Error description
    }
  }
  ```

  ```python Python theme={null}
  from openfiles_ai.exceptions import FileOperationError

  try:
      await client.write_file(path='file.txt', content='hello')
  except FileOperationError as error:
      print(error.status_code)  # HTTP status
      print(error.code)         # Error code
      print(error.message)      # Error description
  ```
</CodeGroup>

## Platform Support

| Platform     | OpenAI Integration | Tools | Core Client |
| ------------ | ------------------ | ----- | ----------- |
| Node.js 18+  | ✅                  | ✅     | ✅           |
| Python 3.8+  | ✅                  | ✅     | ✅           |
| Deno         | ❌                  | ✅     | ✅           |
| Bun          | ✅                  | ✅     | ✅           |
| Edge Runtime | ❌                  | ✅     | ✅           |
| Browser      | ❌                  | ✅     | ✅           |

## Choose Your Integration

<CardGroup cols={3}>
  <Card title="OpenAI Integration" icon="robot" href="/guides/openai-integration">
    **Easiest**: Drop-in replacement for OpenAI SDK with automatic file operations
  </Card>

  <Card title="Tools Integration" icon="wrench" href="/guides/tools-integration">
    **Flexible**: Works with any AI provider (OpenAI, Anthropic, etc.)
  </Card>

  <Card title="Core Client" icon="code" href="/guides/core-client">
    **Control**: Direct API access for custom integrations
  </Card>
</CardGroup>