Metadata-Version: 2.4
Name: big-o-sdk
Version: 1.2.1
Summary: Python SDK for the Big-O LLM Gateway — OpenAI-compatible access to AWS Bedrock and Azure OpenAI with LlamaIndex and Haystack integrations
Author: Virtuele Gemeente Assistent
License: EUPL-1.2
Project-URL: Homepage, https://gitlab.com/virtuele-gemeente-assistent/big-o-sdk
Project-URL: Repository, https://gitlab.com/virtuele-gemeente-assistent/big-o-sdk
Project-URL: Documentation, https://gitlab.com/virtuele-gemeente-assistent/big-o-sdk/-/tree/main/docs
Keywords: llm,openai,bedrock,azure,llamaindex,haystack,gateway,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.12.0; extra == "llamaindex"
Requires-Dist: llama-index-llms-openai-like>=0.4.0; extra == "llamaindex"
Requires-Dist: llama-index-embeddings-openai>=0.4.0; extra == "llamaindex"
Provides-Extra: haystack
Requires-Dist: haystack-ai>=2.21.0; extra == "haystack"
Requires-Dist: requests>=2.33.0; extra == "haystack"
Provides-Extra: all
Requires-Dist: big-o-sdk[haystack,llamaindex]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# Big-O Python SDK

Python SDK for the [Big-O LLM Gateway](https://devops.versnellers.nl/bigo/api/docs), a 100% OpenAI-compatible API that provides unified access to multiple LLM providers (AWS Bedrock, Azure OpenAI).

## Installation

```bash
pip install big-o-sdk
```

With optional framework integrations:

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

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

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

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

```python
# 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)

```python
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)

```bash
pip install big-o-sdk[llamaindex]
```

```python
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)

```bash
pip install big-o-sdk[haystack]
```

```python
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

```python
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

| Environment Variable | Default |
|---------------------|---------|
| `BIG_O_CLIENT_ID` | (required) |
| `BIG_O_CLIENT_SECRET` | (required) |
| `BIG_O_BASE_URL` | `https://devops.versnellers.nl/bigo/api` |
| `BIG_O_CHAT_MODEL` | `gpt-4o-mini` |
| `BIG_O_EMBEDDING_MODEL` | `text-embedding-3-large` |
| `BIG_O_CONTEXT_WINDOW` | `128000` |

## 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](https://gitlab.com/virtuele-gemeente-assistent/generative-ai/ai-orchestration): RAG chatbot using LlamaIndex agents and Haystack embeddings
- [scrapy](https://gitlab.com/virtuele-gemeente-assistent/scrapy): Web scraper with Haystack document indexing and hybrid search

## License

EUPL v1.2, see [LICENSE](LICENSE) for details.
