Big-O Python SDK

Python SDK for the Big-O LLM Gateway, a 100% OpenAI-compatible API that provides unified access to multiple LLM providers (AWS Bedrock, Azure OpenAI).

Installation

pip install big-o-sdk

With optional framework integrations:

pip install big-o-sdk[llamaindex]   # + LlamaIndex LLM and embeddings
pip install big-o-sdk[haystack]     # + Haystack embeddings
pip install big-o-sdk[all]          # everything

For development:

git clone https://gitlab.com/virtuele-gemeente-assistent/big-o-sdk.git
cd big-o-sdk
uv sync

Configuration

Set credentials as environment variables or in a .env file:

BIG_O_CLIENT_ID=your-client-id
BIG_O_CLIENT_SECRET=your-client-secret
BIG_O_CHAT_MODEL=gpt-4o-mini
BIG_O_EMBEDDING_MODEL=text-embedding-3-large

Quick Start

Framework-agnostic (recommended)

Use BigOTokenProvider to get credentials for any OpenAI-compatible framework:

from big_o_sdk import BigOConfig, BigOTokenProvider

config = BigOConfig.from_env()
provider = BigOTokenProvider(config)
creds = await provider.get_credentials(model="gpt-4o-mini")
# → {"base_url": "https://...", "api_key": "eyJ...", "model": "gpt-4o-mini"}

Use the credentials with any framework:

# LangChain
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(**creds)

# LlamaIndex
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(**creds)

# Agno
from agno.models.openai import OpenAIChat

llm = OpenAIChat(**creds)

# Raw OpenAI SDK
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url=creds["base_url"], api_key=creds["api_key"])

Lightweight completions (no framework needed)

from big_o_sdk import BigOConfig, BigOClient

config = BigOConfig.from_env()
async with BigOClient(config) as client:
    answer = await client.complete("Say hello", model="gpt-4o-mini")
    print(answer)

LlamaIndex (optional)

pip install big-o-sdk[llamaindex]

from big_o_sdk import BigOConfig, BigOLLM

config = BigOConfig.from_env()
llm = BigOLLM(config)
response = await llm.acomplete("Hello!")
await llm.close()

Haystack embeddings (optional)

pip install big-o-sdk[haystack]

from big_o_sdk import BigOConfig
from big_o_sdk.embedders.haystack import BigOTextEmbedder

config = BigOConfig.from_env()
embedder = BigOTextEmbedder(config)
result = embedder.run(text="What is AI?")

Gateway status

from big_o_sdk import BigOConfig, BigOClient

config = BigOConfig.from_env()
async with BigOClient(config) as client:
    await client.health()
    await client.ping()
    models = await client.models()

BigOConfig

Authentication

JWT tokens are managed automatically:

1. Fetch token via OAuth2 Client Credentials
2. Cache and refresh 30 seconds before expiry
3. Pass transparently to the underlying client

Architecture

big_o_sdk core (always available, <1s startup)
├── BigOConfig          Configuration and credentials
├── BigOClient          Lightweight completions, chat, health, models
├── BigOTokenProvider   Fresh JWT tokens for any framework
├── BigOAuthenticator   OAuth2 token lifecycle
└── errors              Domain-specific exceptions

big_o_sdk[llamaindex] (optional)
├── BigOLLM             LlamaIndex LLM wrapper
└── BigOEmbedding       LlamaIndex embedding wrapper

big_o_sdk[haystack] (optional)
├── BigOTextEmbedder    Haystack text embedder
└── BigODocumentEmbedder Haystack document embedder

Project Structure

src/big_o_sdk/
├── config.py             BigOConfig
├── errors.py             Domain exceptions
├── auth.py               BigOAuthenticator
├── client.py             BigOClient (complete, chat, health, models)
├── token_provider.py     BigOTokenProvider
├── mixins.py             Shared token refresh logic
├── agents/
│   └── llamaindex.py     BigOLLM
└── embedders/
    ├── llamaindex.py     BigOEmbedding
    └── haystack.py       BigOTextEmbedder, BigODocumentEmbedder

Related Projects

• ai-orchestration: RAG chatbot using LlamaIndex agents and Haystack embeddings
• scrapy: Web scraper with Haystack document indexing and hybrid search

License

EUPL v1.2, see LICENSE for details.