backboard-sdk 1.3.0

Python SDK for the Backboard API - Build conversational AI applications with persistent memory and intelligent document processing

Backboard Python SDK

A developer-friendly Python SDK for the Backboard API. Build conversational AI applications with persistent memory and intelligent document processing.

New to Backboard? We include $10 in free credits to get you started and support 1,800+ LLMs across major providers.

✨ New in v1.2.0

• Simplified Tool Definitions: Use plain JSON objects instead of verbose SDK classes
• Enhanced Tool Call Handling: Object-oriented access with automatic JSON parsing
• Simplified Tool Outputs: Use plain dictionaries for tool results
• Improved Developer Experience: Less boilerplate, more intuitive APIs

Installation

pip install backboard-sdk

Quick Start

import asyncio
from backboard import BackboardClient

async def main():
    client = BackboardClient(api_key="your_api_key_here")

    assistant = await client.create_assistant(
        name="Support Bot",
        description="A helpful customer support assistant",
    )

    thread = await client.create_thread(assistant.assistant_id)

    response = await client.add_message(
        thread_id=thread.thread_id,
        content="Hello! Can you help me with my account?",
        llm_provider="openai",
        model_name="gpt-4o",
        stream=False,
    )

    print(response.latest_message.content)

    # Streaming
    async for event in await client.add_message(
        thread_id=thread.thread_id,
        content="Stream me a short response",
        stream=True,
    ):
        if event.get("type") == "content_streaming":
            print(event.get("content", ""), end="", flush=True)

if __name__ == "__main__":
    asyncio.run(main())

Features

Assistants

• Create, list, get, update, and delete assistants
• Configure custom tools and capabilities
• Upload documents for assistant-level context

Threads

• Create conversation threads under assistants
• Maintain persistent conversation history
• Support for message attachments

Documents

• Upload documents to assistants or threads
• Automatic processing and indexing for RAG
• Support for PDF, Office files, text, and more
• Real-time processing status tracking

Messages

• Send messages with optional file attachments
• Streaming and non-streaming responses
• Tool calling support
• Custom LLM provider and model selection

API Reference

Client Initialization

client = BackboardClient(api_key="your_api_key")
# or use as an async context manager
# async with BackboardClient(api_key="your_api_key") as client:
#     ...

Assistants

# Create assistant
assistant = await client.create_assistant(
    name="My Assistant",
    description="Assistant description",
    tools=[tool_definition],  # Optional
)

# List assistants
assistants = await client.list_assistants(skip=0, limit=100)

# Get assistant
assistant = await client.get_assistant(assistant_id)

# Update assistant
assistant = await client.update_assistant(
    assistant_id,
    name="New Name",
    description="New description",
)

# Delete assistant
result = await client.delete_assistant(assistant_id)

Threads

# Create thread
thread = await client.create_thread(assistant_id)

# List threads
threads = await client.list_threads(skip=0, limit=100)

# Get thread with messages
thread = await client.get_thread(thread_id)

# Delete thread
result = await client.delete_thread(thread_id)

Messages

# Send message
response = await client.add_message(
    thread_id=thread_id,
    content="Your message here",
    files=["path/to/file.pdf"],  # Optional attachments
    llm_provider="openai",  # Optional
    model_name="gpt-4o",  # Optional
    stream=False,
)

# Streaming messages
async for chunk in await client.add_message(thread_id, content="Hello", stream=True):
    if chunk.get('type') == 'content_streaming':
        print(chunk.get('content', ''), end='', flush=True)

Tool Integration (Simplified in v1.1.7)

Tool Definitions

# Use plain JSON objects (no verbose SDK classes needed!)
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"}
                },
                "required": ["location"]
            }
        }
    }
]

assistant = await client.create_assistant(
    name="Weather Assistant",
    tools=tools,
)

Tool Call Handling

import json

# Enhanced object-oriented access with automatic JSON parsing
response = await client.add_message(thread_id, content="What's the weather in NYC?")

if response.status == 'REQUIRES_ACTION' and response.tool_calls:
    outputs = []
    for tc in response.tool_calls:
        function_name = tc.function.name
        function_args = tc.function.parsed_arguments
        tool_call_id = tc.id
        # Build your tool output
        result = json.dumps({"ok": True, "args": function_args})
        outputs.append({"tool_call_id": tool_call_id, "output": result})

    await client.submit_tool_outputs(
        thread_id=thread_id,
        run_id=response.run_id,
        tool_outputs=outputs,
    )

Documents

# Upload document to assistant
document = await client.upload_document_to_assistant(
    assistant_id=assistant_id,
    file_path="path/to/document.pdf",
)

# Upload document to thread
document = await client.upload_document_to_thread(
    thread_id=thread_id,
    file_path="path/to/document.pdf",
)

# List assistant documents
documents = await client.list_assistant_documents(assistant_id)

# List thread documents
documents = await client.list_thread_documents(thread_id)

# Get document status
document = await client.get_document_status(document_id)

# Delete document
result = await client.delete_document(document_id)

Error Handling

The SDK includes comprehensive error handling:

from backboard import (
    BackboardAPIError,
    BackboardValidationError,
    BackboardNotFoundError,
    BackboardRateLimitError,
    BackboardServerError,
)

async def demo_err():
    try:
        await client.get_assistant("invalid_id")
    except BackboardNotFoundError:
        print("Assistant not found")
    except BackboardValidationError as e:
        print(f"Validation error: {e}")
    except BackboardAPIError as e:
        print(f"API error: {e}")

Supported File Types

The SDK supports uploading the following file types:

• PDF files (.pdf)
• Microsoft Office files (.docx, .xlsx, .pptx, .doc, .xls, .ppt)
• Text files (.txt, .csv, .md, .markdown)
• Code files (.py, .js, .html, .css, .xml)
• JSON files (.json, .jsonl)

Requirements

• Python 3.8+
• httpx >= 0.27.0

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://backboard.io/docs
• Email: [e-mail]