Functor Logo
GitHub

Functor SDK Overview

Functor SDK is the official Python SDK for Functor system. It provides a clean, type-safe, and intuitive interface for all API operations with both synchronous and asynchronous support. The SDK interfaces with the MainOrchestrator-based architecture through REST API endpoints, including enhanced smart query, enhanced SQL processing, and enhanced re-ranking capabilities.

Key Features

  • Clean API Design - Namespaced organization for intuitive usage
  • Type Safety - Full Pydantic model validation
  • Dual Interface - Both async and sync methods available
  • Error Handling - Rich exception hierarchy with detailed information
  • Automatic Retry - Built-in exponential backoff for resilience
  • Context Managers - Proper resource management
  • Environment Config - Auto-detect credentials from environment

Installation

Install the SDK using pip or uv:

# Using pip
pip install functor-sdk


# Using uv
uv pip install functor-sdk

Quick Start

Get started with a simple query in just a few lines:

quickstart.py
from functor_sdk import FunctorClient


# Create a client
client = FunctorClient(api_key="your-api-key")


# Execute a query
result = client.queries.execute("What is machine learning?")
print(result.answer)
print(f"Pipeline: {result.pipeline_used}")
print(f"Citations: {len(result.citations)}")

Namespaces

The SDK is organized into logical namespaces for different operations:

Queries

Execute natural language queries with automatic routing

client.queries.execute()

Ingestion

Upload and process data with unified ingestion, quality checks, and domain detection

client.ingestion.ingest_unified()

Knowledge Graphs

Full CRUD operations for entities, relations, chunks, and bulk operations

client.knowledge_graphs.create_entity()

Sources

Complete CRUD operations for data sources

client.sources.list_for_kg()

Visualizations

Access visualization endpoints

client.visualizations.list()

Health

System health and monitoring

client.health.check()

Async vs Sync

Every method is available in both async and sync versions:

import asyncio
from functor_sdk import FunctorClient


async def main():
    async with FunctorClient(api_key="your-key") as client:
        # Use async methods with _async suffix
        result = await client.queries.execute_async("What is AI?")
        print(result.answer)


asyncio.run(main())

Authentication

The SDK supports multiple authentication methods:

# API Key (recommended)
client = FunctorClient(api_key="your-api-key")


# Bearer Token
client = FunctorClient(token="your-bearer-token")


# Environment Variables
# Set FUNCTOR_API_KEY or FUNCTOR_TOKEN
client = FunctorClient()  # Auto-detects from environment

Error Handling

The SDK provides detailed exception types for precise error handling:

from functor_sdk import (
    FunctorClient,
    FunctorAPIError,
    FunctorAuthenticationError,
    FunctorNotFoundError,
    FunctorTimeoutError
)


client = FunctorClient(api_key="your-key")


try:
    result = client.queries.execute("What is quantum computing?")
except FunctorAuthenticationError:
    print("Invalid API key")
except FunctorNotFoundError as e:
    print(f"Resource not found: {e.message}")
except FunctorTimeoutError:
    print("Request timed out")
except FunctorAPIError as e:
    print(f"API error {e.status_code}: {e.message}")

Next Steps