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

# Official SDKs, Client Libraries & Code Examples

> Integrate MITHUNAI into Python, TypeScript, Node.js, and browser applications using our typed client libraries and streaming helpers.

MITHUNAI provides official client libraries for Python and TypeScript that wrap authentication, request retries, token budgeting, and Server-Sent Events (SSE) streaming into ergonomic, typed interfaces. All SDK methods map directly to the `/arukz/api/v1` specification and handle tenant scoping and error parsing automatically.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    APP["Your Application\n(Node.js / Python / Go)"]
    SDK["MITHUNAI SDK\n(Auto-Retry, SSE Parser, Types)"]
    API["MITHUNAI Gateway\n(/arukz/api/v1)"]

    APP --> SDK --> API
```

***

## TypeScript / JavaScript SDK

The `@mithunai/sdk` package supports Node.js 18+, Bun, Deno, and modern browser runtimes with zero external dependencies.

### Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm add @mithunai/sdk
# or: npm install @mithunai/sdk
# or: yarn add @mithunai/sdk
```

### Asking a Grounded Question with Streaming

```typescript Ask with Streaming SSE theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { MithunAIClient } from '@mithunai/sdk'

const client = new MithunAIClient({
  apiKey: process.env.MITHUNAI_API_KEY!,
  baseUrl: 'https://app.mithunai.com/arukz/api/v1',
})

// Start a conversation
const conversation = await client.conversations.create({
  assistantId: 'asst_prod_01',
})

// Stream answer tokens and inspect citations
const stream = await client.conversations.streamMessage(conversation.id, {
  text: 'How do I configure custom domain origins for the widget?',
})

for await (const chunk of stream) {
  if (chunk.type === 'token') {
    process.stdout.write(chunk.delta)
  } else if (chunk.type === 'citations') {
    console.log('\n\nVerified Sources:')
    for (const citation of chunk.sources) {
      console.log(`- [${citation.title}](${citation.url}) (Page ${citation.page ?? 1})`)
    }
  } else if (chunk.type === 'abstention') {
    console.warn('\nAssistant abstained: Evidence insufficient in corpus.')
  }
}
```

***

## Python SDK

The `mithunai` package provides asynchronous (`asyncio`) and synchronous clients with full Pydantic v2 type hints.

### Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install mithunai
# or: uv add mithunai
```

### Sync & Async Usage Examples

```python Async Streaming in Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import asyncio
from mithunai import AsyncMithunAI

async def main():
    async with AsyncMithunAI(api_key="arukz_sk_...") as client:
        # Create conversation
        conv = await client.conversations.create(assistant_id="asst_prod_01")

        # Stream response
        async for event in client.conversations.stream(
            conversation_id=conv.id,
            text="What are the escalation procedures for cache invalidation?",
        ):
            if event.is_token:
                print(event.text, end="", flush=True)
            elif event.is_citation:
                print(f"\n[Citation: {event.source.title} -> {event.source.url}]")

asyncio.run(main())
```

***

## Error Handling & Retry Policies

Both SDKs include exponential backoff with jitter for transient errors:

| Status Code        | SDK Behavior                                                            | Recommended Action                                               |
| :----------------- | :---------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `401 Unauthorized` | Throws `AuthenticationError` immediately without retrying.              | Verify that your `arukz_sk_` key is active and not expired.      |
| `403 Forbidden`    | Throws `PermissionDeniedError`.                                         | Confirm your key holds the required role (`Editor`, `Admin`).    |
| `404 Not Found`    | Throws `NotFoundError` (protects tenant boundaries).                    | Confirm the requested ID exists within your organization.        |
| `429 Rate Limit`   | Automatically retries up to 3 times following the `Retry-After` header. | Implement client-side queueing or request a rate-limit increase. |
| `502 / 503 / 504`  | Retries with exponential backoff (250ms, 500ms, 1000ms).                | Handled transparently by the client.                             |