Metadata-Version: 2.4
Name: bbi-bucky
Version: 1.1.0
Summary: BBI Bucky — pluggable AI chatbot framework for enterprise applications
Author-email: BBI Engineering <engineering@bbi.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/bbi-engineering/bbi-bucky-framework
Project-URL: Documentation, https://github.com/bbi-engineering/bbi-bucky-framework#readme
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Provides-Extra: bedrock
Requires-Dist: boto3>=1.28.0; extra == "bedrock"
Provides-Extra: cortex
Requires-Dist: aiohttp>=3.8.0; extra == "cortex"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: ruamel
Requires-Dist: ruamel.yaml>=0.17.0; extra == "ruamel"
Provides-Extra: api
Requires-Dist: fastapi>=0.100.0; extra == "api"
Requires-Dist: uvicorn>=0.23.0; extra == "api"
Provides-Extra: chromadb
Requires-Dist: chromadb>=0.4.0; extra == "chromadb"
Requires-Dist: sentence-transformers>=2.2.0; extra == "chromadb"
Provides-Extra: all
Requires-Dist: bbi-bucky[api,bedrock,chromadb,cortex,ruamel,yaml]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# bbi-bucky

Pluggable AI chatbot framework for enterprise applications. Drop a YAML config and three lines of Python to add an AI assistant to any FastAPI app.

## Install

```bash
# Core only (config, contracts, agent pipeline)
pip install bbi-bucky

# With AWS Bedrock (Claude)
pip install bbi-bucky[bedrock]

# With Snowflake Cortex
pip install bbi-bucky[cortex]

# With FastAPI router factory
pip install bbi-bucky[api]

# With RAG (ChromaDB)
pip install bbi-bucky[chromadb]

# YAML config loading
pip install bbi-bucky[yaml]        # PyYAML
pip install bbi-bucky[ruamel]      # ruamel.yaml

# Everything
pip install bbi-bucky[all]
```

## Quick start

**1. Create a config file** (`bucky.yaml`):

```yaml
app_name: "My App Assistant"
llm:
  provider: "bedrock"
  model: "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
  temperature: 0.7
  max_tokens: 4096
  aws_region: "us-east-1"
agent:
  max_history: 10
  system_prompt_override: |
    You are a helpful assistant for My App.
```

**2. Wire it up** (3 lines):

```python
from bbi_bucky import create_chat_router, load_config

config = load_config(yaml_path="bucky.yaml")
app.include_router(create_chat_router(config=config))
```

This gives you `/api/bucky/chat`, `/api/bucky/chat/stream` (SSE), and `/api/bucky/health` out of the box.

**3. Or use the LLM service directly:**

```python
from bbi_bucky import load_config
from bbi_bucky.llm.unified import UnifiedLLMService

config = load_config(yaml_path="bucky.yaml")
llm = UnifiedLLMService(config.llm)

# Non-streaming
response = await llm.invoke("What is Kubernetes?", system_prompt="Be concise.")

# Streaming
async for chunk in llm.stream("Explain microservices"):
    print(chunk, end="")
```

## Configuration

All config is loaded from YAML, with environment variable overrides and code overrides layered on top.

```python
config = load_config(
    yaml_path="bucky.yaml",          # YAML file (optional)
    env_prefix="BBI_BUCKY_",         # Env var prefix (e.g. BBI_BUCKY_LLM_PROVIDER=cortex)
    overrides={"llm": {"model": "llama3.1-70b"}},  # Code overrides (highest priority)
)
```

Priority: YAML < environment variables < code overrides.

## LLM Providers

### AWS Bedrock (Claude)

```bash
pip install bbi-bucky[bedrock]
```

Uses the Bedrock Converse API. Supports streaming. Credentials from environment or explicit config.

### Snowflake Cortex

```bash
pip install bbi-bucky[cortex]
```

REST API with SSE streaming. SPCS-compatible (auto-detects `/snowflake/session/token`).

### Custom providers

```python
from bbi_bucky.llm.factory import LLMFactory

LLMFactory.register("my_provider", MyCustomProvider)
```

Your provider just needs `generate()` and `stream()` methods matching the `LLMProvider` protocol.

## Features

- **Zero-config defaults**: Only `pydantic` is required. Everything else is optional.
- **YAML + env var config**: Single source of truth, overridable per-environment.
- **Multiple LLM providers**: Bedrock and Cortex built-in, custom providers via `register()`.
- **SSE streaming**: Named events (`response.text.delta`, `activity.started`, etc.).
- **Agent pipeline**: Intent classification, context gathering, RAG retrieval, response generation.
- **RAG support**: ChromaDB backend included, or bring your own via `IRAGService`.
- **Conversation memory**: In-memory by default, extensible via `IConversationMemory`.
- **API contracts**: `ApiResponseEnvelope` on all endpoints (RFC 9457 errors).
- **Router factory**: `create_chat_router()` gives you a full FastAPI router in one call.

## Requirements

- Python 3.11+
- `pydantic >= 2.0` (only hard dependency)

## License

MIT
