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

# Python SDK

> Learn how to integrate Suada with your Python applications

## Overview

The Suada Python SDK provides a Pythonic interface to interact with the Suada API. Built with type safety in mind using Pydantic, it offers a robust and intuitive way to integrate Suada's capabilities into your Python applications.

## Prerequisites

* Python 3.8 or higher
* A Suada API key
* pip package manager

## Installation

Install the Suada Python SDK using pip:

```bash theme={null}
pip install suada
```

Or using poetry:

```bash theme={null}
poetry add suada
```

## Quick Start

Here's a basic example to get you started:

```python theme={null}
from suada import Suada, SuadaConfig

# Initialize the client
suada = Suada(
    config=SuadaConfig(
        api_key="your-api-key"
    )
)

# Send a chat message
try:
    response = suada.chat(
        message="What insights can you provide about our recent performance?"
    )
    print(response.answer)
except Exception as e:
    print(f"Error: {str(e)}")
```

## Authentication

### Setting up your API Key

We recommend storing your API key in environment variables:

```bash theme={null}
# .env
SUADA_API_KEY=your-api-key
```

Then load it in your application:

```python theme={null}
import os
from dotenv import load_dotenv
from suada import Suada, SuadaConfig

# Load environment variables
load_dotenv()

# Initialize the client
suada = Suada(
    config=SuadaConfig(
        api_key=os.getenv("SUADA_API_KEY")
    )
)
```

## Core Concepts

### Chat Messages

The chat endpoint is the primary way to interact with Suada. Each chat request can include:

* A message (required)
* Chat history (optional)
* Configuration options (optional)

```python theme={null}
response = suada.chat(
    message="How's our business performing?",
    chat_history=previous_messages,  # Optional
    privacy_mode=True               # Optional
)
```

### Response Format

Chat responses include several key components:

```python theme={null}
from pydantic import BaseModel
from typing import List, Optional, Dict

class SuadaResponse(BaseModel):
    # The main response text
    answer: str
    
    # Internal reasoning process (optional)
    thoughts: Optional[str] = None
    
    # Actions taken during processing (optional)
    actions: Optional[List[Dict[str, str]]] = None
    
    # Suggested follow-up question (optional)
    follow_up_question: Optional[str] = None
    
    # Reasoning behind the response (optional)
    reasoning: Optional[str] = None
    
    # Reference sources (optional)
    sources: Optional[List[str]] = None
    
    # Conversation tracking ID (optional)
    conversation_id: Optional[str] = None
    
    # Response timestamp
    timestamp: int
```

## Advanced Features

### Passthrough Mode

Passthrough mode allows you to associate Suada conversations with your application's user system:

```python theme={null}
suada = Suada(
    config=SuadaConfig(
        api_key="your-api-key",
        passthrough_mode=True
    )
)

# When using passthrough mode, include external_user_identifier
response = suada.chat(
    message="What's our revenue trend?",
    external_user_identifier="user-123"  # Required in passthrough mode
)
```

### LangChain Integration

The SDK provides seamless integration with LangChain, allowing you to use Suada's capabilities within your LangChain applications:

```python theme={null}
from suada import Suada, SuadaConfig
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain.chat_models import ChatOpenAI
from langchain.prompts import PromptTemplate
from langchain.memory import ConversationBufferMemory

# Initialize Suada
suada = Suada(
    config=SuadaConfig(
        api_key="your-api-key"
    )
)

# Create a Suada tool for LangChain
suada_tool = suada.create_tool(
    name="business_analyst",
    description="Use this tool to get business insights and analysis",
    external_user_identifier="user-123"  # Required if using passthrough mode
)

# Create an OpenAI agent with the Suada tool
model = ChatOpenAI(temperature=0)
tools = [suada_tool]

# Create a prompt template
prompt = PromptTemplate.from_template("""
    You are a helpful assistant that uses Suada's business analyst capabilities.
    
    Current conversation:
    {chat_history}
    
    Human: {input}
    Assistant: Let me help you with that.
""")

# Create the agent
agent = create_openai_functions_agent(
    llm=model,
    tools=tools,
    prompt=prompt
)

# Optional: Add conversation memory
memory = ConversationBufferMemory(
    memory_key="chat_history",
    return_messages=True
)

# Create the executor
executor = AgentExecutor.from_agent_and_tools(
    agent=agent,
    tools=tools,
    memory=memory,
    verbose=True
)

# Use the agent
result = executor.invoke({
    "input": "What's our revenue trend for the last quarter?"
})
print(result["output"])
```

#### LangChain Best Practices

1. **Tool Configuration**
   * Write clear, descriptive tool descriptions
   * Set appropriate temperature for your use case
   * Implement tool-specific error handling
   * Consider adding custom tool validation

2. **Agent Setup**
   * Use structured prompts for consistent behavior
   * Implement conversation memory when needed
   * Consider using different agent types based on your needs
   * Test agent behavior with various input types

3. **Error Handling**
   * Implement proper error handling for both Suada and LangChain
   * Add retry logic for transient failures
   * Log agent actions for debugging
   * Consider implementing fallback mechanisms

4. **Memory Management**
   * Choose appropriate memory types for your use case
   * Implement memory cleanup when needed
   * Consider memory persistence for long-running conversations
   * Handle memory size limitations

5. **Performance Optimization**
   * Reuse agent instances when possible
   * Implement appropriate timeouts
   * Consider caching for frequently used data
   * Monitor memory usage in long-running applications

### Privacy Mode

Enable privacy mode to ensure sensitive information is handled with additional security:

```python theme={null}
response = suada.chat(
    message="Analyze our financial data",
    privacy_mode=True
)
```

## Error Handling

The SDK provides robust error handling with descriptive exceptions:

```python theme={null}
from suada import Suada, SuadaConfig, SuadaError, SuadaAPIError

suada = Suada(config=SuadaConfig(api_key="your-api-key"))

try:
    response = suada.chat(
        message="What's our revenue?"
    )
except SuadaAPIError as e:
    # Handle API-specific errors
    print(f"API Error: {e.message}, Status: {e.status}, Code: {e.code}")
except SuadaError as e:
    # Handle general SDK errors
    print(f"SDK Error: {e.message}")
except Exception as e:
    # Handle unexpected errors
    print(f"Unexpected error: {str(e)}")
```

## Best Practices

1. **Environment Variables**
   * Store API keys and sensitive configuration in environment variables
   * Use python-dotenv for environment variable management
   * Never commit API keys to version control

2. **Error Handling**
   * Implement try-except blocks around API calls
   * Use specific exception types for better error handling
   * Log errors appropriately for debugging

3. **Type Safety**
   * Take advantage of Pydantic models and type hints
   * Use mypy for static type checking
   * Enable strict type checking in your development environment

4. **Response Processing**
   * Always check for the presence of optional fields
   * Handle missing data gracefully
   * Implement proper error handling for data parsing

## Configuration Options

| Option            | Type | Required | Description                                                                                  |
| ----------------- | ---- | -------- | -------------------------------------------------------------------------------------------- |
| api\_key          | str  | Yes      | Your Suada API key                                                                           |
| base\_url         | str  | No       | Custom API endpoint (defaults to [https://suada.ai/api/public](https://suada.ai/api/public)) |
| passthrough\_mode | bool | No       | Enable user-specific resources                                                               |

## FAQ

### How do I handle rate limiting?

The SDK automatically implements exponential backoff for rate limits. You can customize the retry behavior:

```python theme={null}
from suada import Suada, SuadaConfig

suada = Suada(
    config=SuadaConfig(
        api_key="your-api-key",
        max_retries=3,
        retry_delay=1.0
    )
)
```

### How do I maintain conversation context?

Use the chat\_history parameter to maintain conversation context:

```python theme={null}
messages = []
response1 = suada.chat(message="How's our revenue?")
messages.append({"role": "user", "content": "How's our revenue?"})
messages.append({"role": "assistant", "content": response1.answer})

response2 = suada.chat(
    message="Compare that to last year",
    chat_history=messages
)
```

### How can I enable debug logging?

Use Python's built-in logging module:

```python theme={null}
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("suada")
```

### Can I use the SDK in async/await code?

Yes, the SDK provides async support:

```python theme={null}
from suada import AsyncSuada, SuadaConfig

async def main():
    async_suada = AsyncSuada(
        config=SuadaConfig(api_key="your-api-key")
    )
    response = await async_suada.chat(
        message="What's our performance?"
    )
```

## Development Setup

For contributors and developers:

```bash theme={null}
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy suada

# Run linting
flake8 suada
black suada
isort suada
```

### Support

* Email Support: [hello@suada.ai](mailto:hello@suada.ai)