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

# 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):

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):

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:

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.

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)

pip install bbi-bucky[bedrock]

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

Snowflake Cortex

pip install bbi-bucky[cortex]

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

Custom providers

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