bbi-bucky 1.0.0__tar.gz

bbi_bucky-1.0.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: bbi-bucky
+Version: 1.0.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

bbi_bucky-1.0.0/README.md

@@ -0,0 +1,138 @@
+# 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

bbi_bucky-1.0.0/bbi_bucky/__init__.py

@@ -0,0 +1,49 @@
+"""BBI Bucky — AI chatbot framework for BBI applications."""
+
+from bbi_bucky.config.loader import load_config
+from bbi_bucky.config.schema import BbiBuckyConfig, LLMProviderConfig, RAGConfig, AgentConfig
+from bbi_bucky.contracts.envelope import ApiResponseEnvelope, build_response_envelope
+from bbi_bucky.agent.context import ChatContext, ChatResult
+
+__version__ = "1.0.0"
+
+
+def create_chat_router(**kwargs):
+    """Lazy import to avoid requiring fastapi at module load time."""
+    from bbi_bucky.router.factory import create_chat_router as _create
+
+    return _create(**kwargs)
+
+
+def __getattr__(name: str):
+    if name == "UnifiedLLMService":
+        from bbi_bucky.llm.unified import UnifiedLLMService
+        return UnifiedLLMService
+    if name == "IRAGService":
+        from bbi_bucky.rag.interface import IRAGService
+        return IRAGService
+    if name == "create_rag_service":
+        from bbi_bucky.rag.factory import create_rag_service
+        return create_rag_service
+    if name == "ChatPipeline":
+        from bbi_bucky.agent.pipeline import ChatPipeline
+        return ChatPipeline
+    raise AttributeError(f"module 'bbi_bucky' has no attribute {name!r}")
+
+
+__all__ = [
+    "create_chat_router",
+    "load_config",
+    "BbiBuckyConfig",
+    "LLMProviderConfig",
+    "RAGConfig",
+    "AgentConfig",
+    "UnifiedLLMService",
+    "IRAGService",
+    "create_rag_service",
+    "ApiResponseEnvelope",
+    "build_response_envelope",
+    "ChatPipeline",
+    "ChatContext",
+    "ChatResult",
+]

bbi_bucky-1.0.0/bbi_bucky/agent/__init__.py

@@ -0,0 +1,2 @@
+from bbi_bucky.agent.pipeline import ChatPipeline
+from bbi_bucky.agent.context import ChatContext, ChatResult

bbi_bucky-1.0.0/bbi_bucky/agent/context.py

@@ -0,0 +1,30 @@
+"""Agent context and result data models."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ChatContext:
+    """Context sent with every chat message."""
+
+    session_id: str | None = None
+    user_id: str | None = None
+    current_page: str | None = None
+    current_tool: str | None = None
+    page_context: dict[str, Any] = field(default_factory=dict)
+    conversation_history: list[dict[str, str]] = field(default_factory=list)
+    system_context: str | None = None
+    uploaded_files: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ChatResult:
+    """Result of processing a chat message."""
+
+    response: str
+    suggestions: list[str] = field(default_factory=list)
+    sources: list[dict[str, Any]] = field(default_factory=list)
+    intent: str | None = None
+    confidence: float = 0.0
+    conversation_id: str | None = None

bbi_bucky-1.0.0/bbi_bucky/agent/nodes.py

@@ -0,0 +1,103 @@
+"""Agent pipeline node functions."""
+
+import json
+import logging
+from typing import Any
+
+from bbi_bucky.agent.context import ChatContext
+from bbi_bucky.agent.prompts import INTENT_DETECTION_PROMPT
+from bbi_bucky.llm.unified import UnifiedLLMService
+from bbi_bucky.rag.interface import IRAGService
+
+logger = logging.getLogger(__name__)
+
+
+async def classify_intent(
+    query: str,
+    context: ChatContext,
+    llm: UnifiedLLMService,
+) -> dict[str, Any]:
+    """Classify the user's intent using the LLM."""
+    history_str = ""
+    if context.conversation_history:
+        recent = context.conversation_history[-4:]
+        history_str = "\n".join(
+            f"{turn['role']}: {turn['content'][:200]}" for turn in recent
+        )
+
+    prompt = INTENT_DETECTION_PROMPT.format(query=query, history=history_str)
+
+    try:
+        raw = await llm.invoke(prompt, system_prompt="You are an intent classifier. Respond only with valid JSON.")
+        result = json.loads(raw.strip().strip("```json").strip("```"))
+        return {
+            "intent": result.get("intent", "general"),
+            "confidence": float(result.get("confidence", 0.5)),
+        }
+    except Exception as e:
+        logger.warning(f"Intent classification failed: {e}")
+        return {"intent": "general", "confidence": 0.5}
+
+
+def gather_context(
+    query: str,
+    context: ChatContext,
+    rag_results: dict[str, Any] | None = None,
+) -> str:
+    """Build the full context string for the LLM prompt."""
+    parts: list[str] = []
+
+    if context.current_page:
+        parts.append(f"Current page: {context.current_page}")
+    if context.current_tool:
+        parts.append(f"Current tool: {context.current_tool}")
+
+    if context.page_context:
+        page_ctx = json.dumps(context.page_context, default=str)
+        if len(page_ctx) > 2000:
+            page_ctx = page_ctx[:2000] + "..."
+        parts.append(f"Page context:\n{page_ctx}")
+
+    if context.system_context:
+        parts.append(f"System context:\n{context.system_context[:1000]}")
+
+    if context.conversation_history:
+        recent = context.conversation_history[-6:]
+        history_lines = [f"{t['role']}: {t['content'][:300]}" for t in recent]
+        parts.append(f"Conversation history:\n" + "\n".join(history_lines))
+
+    if rag_results and rag_results.get("results"):
+        rag_context = "\n\n".join(
+            f"[Source: {r.get('metadata', {}).get('source', 'unknown')}]\n{r['content'][:500]}"
+            for r in rag_results["results"][:3]
+        )
+        parts.append(f"Retrieved knowledge:\n{rag_context}")
+
+    return "\n\n---\n\n".join(parts) if parts else ""
+
+
+async def generate_response(
+    query: str,
+    context_str: str,
+    intent: dict[str, Any],
+    llm: UnifiedLLMService,
+    system_prompt: str,
+    mode_prompt: str,
+) -> str:
+    """Generate the final response using the LLM."""
+    full_prompt_parts = [
+        f"User question: {query}",
+    ]
+
+    if context_str:
+        full_prompt_parts.append(f"\nAvailable context:\n{context_str}")
+
+    full_prompt_parts.append(
+        "\nProvide a helpful, well-formatted response. "
+        "Include 3 relevant follow-up questions at the end."
+    )
+
+    full_system = f"{system_prompt}\n\n{mode_prompt}"
+    full_prompt = "\n".join(full_prompt_parts)
+
+    return await llm.invoke(full_prompt, system_prompt=full_system)

bbi_bucky-1.0.0/bbi_bucky/agent/pipeline.py

@@ -0,0 +1,193 @@
+"""Chat pipeline — linear agent that classifies intent, gathers context, retrieves from RAG, and generates a response."""
+
+import logging
+import uuid
+from typing import Any, AsyncGenerator
+
+from bbi_bucky.agent.context import ChatContext, ChatResult
+from bbi_bucky.agent.nodes import classify_intent, gather_context, generate_response
+from bbi_bucky.agent.prompts import MODE_PROMPTS, SYSTEM_PROMPT
+from bbi_bucky.config.schema import AgentConfig
+from bbi_bucky.contracts.sse_events import SSEEvent, SSEEventType
+from bbi_bucky.llm.unified import UnifiedLLMService
+from bbi_bucky.memory.interface import IConversationMemory
+from bbi_bucky.rag.interface import IRAGService
+
+logger = logging.getLogger(__name__)
+
+
+class ChatPipeline:
+    """Linear agent pipeline: intent → context → RAG → respond."""
+
+    def __init__(
+        self,
+        llm: UnifiedLLMService,
+        rag: IRAGService | None = None,
+        memory: IConversationMemory | None = None,
+        config: AgentConfig | None = None,
+    ):
+        self._llm = llm
+        self._rag = rag
+        self._memory = memory
+        self._config = config or AgentConfig()
+
+    async def process(
+        self,
+        query: str,
+        context: ChatContext,
+        mode: str | None = None,
+    ) -> ChatResult:
+        mode = mode or self._config.default_mode
+        conversation_id = context.session_id or str(uuid.uuid4())
+
+        # Load history from memory if available
+        if self._memory and context.session_id:
+            history = self._memory.get_history(context.session_id, self._config.max_history)
+            for turn in history:
+                context.conversation_history.append({"role": "user", "content": turn.user_message})
+                context.conversation_history.append({"role": "assistant", "content": turn.assistant_response})
+
+        # 1. Classify intent
+        intent = {"intent": "general", "confidence": 0.5}
+        if self._config.enable_intent_detection:
+            intent = await classify_intent(query, context, self._llm)
+
+        # 2. RAG retrieval
+        rag_results: dict[str, Any] | None = None
+        if self._rag:
+            rag_results = await self._rag.retrieve_with_sources(query, k=5)
+
+        # 3. Gather context
+        context_str = gather_context(query, context, rag_results)
+
+        # 4. Generate response
+        system_prompt = self._config.system_prompt_override or SYSTEM_PROMPT
+        mode_prompt = MODE_PROMPTS.get(mode, MODE_PROMPTS["conversational"])
+
+        response_text = await generate_response(
+            query=query,
+            context_str=context_str,
+            intent=intent,
+            llm=self._llm,
+            system_prompt=system_prompt,
+            mode_prompt=mode_prompt,
+        )
+
+        # Store in memory
+        if self._memory and context.session_id:
+            await self._memory.store(
+                session_id=context.session_id,
+                user_msg=query,
+                assistant_msg=response_text,
+                metadata={"intent": intent.get("intent"), "mode": mode},
+            )
+
+        sources = rag_results.get("sources", []) if rag_results else []
+
+        return ChatResult(
+            response=response_text,
+            suggestions=[],
+            sources=[{"source": s} for s in sources],
+            intent=intent.get("intent"),
+            confidence=intent.get("confidence", 0.0),
+            conversation_id=conversation_id,
+        )
+
+    async def process_streaming(
+        self,
+        query: str,
+        context: ChatContext,
+        mode: str | None = None,
+    ) -> AsyncGenerator[SSEEvent, None]:
+        mode = mode or self._config.default_mode
+        conversation_id = context.session_id or str(uuid.uuid4())
+
+        # Load history
+        if self._memory and context.session_id:
+            history = self._memory.get_history(context.session_id, self._config.max_history)
+            for turn in history:
+                context.conversation_history.append({"role": "user", "content": turn.user_message})
+                context.conversation_history.append({"role": "assistant", "content": turn.assistant_response})
+
+        yield SSEEvent(
+            event=SSEEventType.ACTIVITY_STARTED,
+            data={"step": "intent_detection", "label": "Understanding your question..."},
+        )
+
+        # 1. Classify intent
+        intent = {"intent": "general", "confidence": 0.5}
+        if self._config.enable_intent_detection:
+            intent = await classify_intent(query, context, self._llm)
+
+        yield SSEEvent(
+            event=SSEEventType.ACTIVITY_COMPLETED,
+            data={"step": "intent_detection", "intent": intent.get("intent")},
+        )
+
+        # 2. RAG retrieval
+        rag_results: dict[str, Any] | None = None
+        if self._rag:
+            yield SSEEvent(
+                event=SSEEventType.ACTIVITY_STARTED,
+                data={"step": "rag_retrieval", "label": "Searching knowledge base..."},
+            )
+            rag_results = await self._rag.retrieve_with_sources(query, k=5)
+            yield SSEEvent(
+                event=SSEEventType.ACTIVITY_COMPLETED,
+                data={
+                    "step": "rag_retrieval",
+                    "count": len(rag_results.get("results", [])),
+                },
+            )
+
+        # 3. Gather context
+        context_str = gather_context(query, context, rag_results)
+
+        yield SSEEvent(
+            event=SSEEventType.CONTEXT_RESOLVED,
+            data={"context_length": len(context_str)},
+        )
+
+        # 4. Stream response
+        system_prompt = self._config.system_prompt_override or SYSTEM_PROMPT
+        mode_prompt = MODE_PROMPTS.get(mode, MODE_PROMPTS["conversational"])
+        full_system = f"{system_prompt}\n\n{mode_prompt}"
+
+        prompt_parts = [f"User question: {query}"]
+        if context_str:
+            prompt_parts.append(f"\nAvailable context:\n{context_str}")
+        prompt_parts.append(
+            "\nProvide a helpful, well-formatted response. "
+            "Include 3 relevant follow-up questions at the end."
+        )
+        full_prompt = "\n".join(prompt_parts)
+
+        full_response: list[str] = []
+        async for token in self._llm.stream(full_prompt, system_prompt=full_system):
+            full_response.append(token)
+            yield SSEEvent(
+                event=SSEEventType.RESPONSE_TEXT_DELTA,
+                data={"delta": token},
+            )
+
+        response_text = "".join(full_response)
+
+        # Store in memory
+        if self._memory and context.session_id:
+            await self._memory.store(
+                session_id=context.session_id,
+                user_msg=query,
+                assistant_msg=response_text,
+                metadata={"intent": intent.get("intent"), "mode": mode},
+            )
+
+        sources = rag_results.get("sources", []) if rag_results else []
+
+        yield SSEEvent(
+            event=SSEEventType.RESPONSE_COMPLETED,
+            data={
+                "conversation_id": conversation_id,
+                "intent": intent.get("intent"),
+                "sources": sources,
+            },
+        )