​
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

  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: 
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

  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

OptionTypeRequiredDescription
api_keystrYesYour Suada API key
base_urlstrNoCustom API endpoint (defaults to https://suada.ai/api/public)
passthrough_modeboolNoEnable 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