Python SDK

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:

pip install suada

Or using poetry:

poetry add suada

Quick Start

Here’s a basic example to get you started:

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:

# .env
SUADA_API_KEY=your-api-key

Then load it in your application:

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)

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:

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:

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:

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

Tool Configuration
- Write clear, descriptive tool descriptions
- Set appropriate temperature for your use case
- Implement tool-specific error handling
- Consider adding custom tool validation
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
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
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
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:

response = suada.chat(
    message="Analyze our financial data",
    privacy_mode=True
)

Error Handling

The SDK provides robust error handling with descriptive exceptions:

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

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
Error Handling
- Implement try-except blocks around API calls
- Use specific exception types for better error handling
- Log errors appropriately for debugging
Type Safety
- Take advantage of Pydantic models and type hints
- Use mypy for static type checking
- Enable strict type checking in your development environment
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)
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:

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:

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:

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:

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:

# 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

Frontend SDKs

Backend SDKs

Overview

Prerequisites

Installation

Quick Start

Authentication

Setting up your API Key

Core Concepts

Chat Messages

Response Format

Advanced Features

Passthrough Mode

LangChain Integration

LangChain Best Practices

Privacy Mode

Error Handling

Best Practices

Configuration Options

FAQ

How do I handle rate limiting?

How do I maintain conversation context?

How can I enable debug logging?

Can I use the SDK in async/await code?

Development Setup

Support

​Overview

​Prerequisites

​Installation

​Quick Start

​Authentication

​Setting up your API Key

​Core Concepts

​Chat Messages

​Response Format

​Advanced Features

​Passthrough Mode

​LangChain Integration

​LangChain Best Practices

​Privacy Mode

​Error Handling

​Best Practices

​Configuration Options

​FAQ

​How do I handle rate limiting?

​How do I maintain conversation context?

​How can I enable debug logging?

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

​Development Setup

​Support

Overview

Prerequisites

Installation

Quick Start

Authentication

Setting up your API Key

Core Concepts

Chat Messages

Response Format

Advanced Features

Passthrough Mode

LangChain Integration

LangChain Best Practices

Privacy Mode

Error Handling

Best Practices

Configuration Options

FAQ

How do I handle rate limiting?

How do I maintain conversation context?

How can I enable debug logging?

Can I use the SDK in async/await code?

Development Setup

Support