Chatbot Framework

A production-grade Python framework for building embeddable AI chatbots with optional capabilities for SQL databases, web access, RAG (Retrieval-Augmented Generation), validation, and memory management.

Status: 232 tests passing | Type-safe (Pyright strict mode) | Production-ready

Quick Start

Prerequisites

• Python 3.9+

• pip or poetry

Installation

1. Clone the repository

   git clone <repo-url>
   
   cd chatbot-builder
   

2. Install dependencies

   # Using pip
   
   pip install -e .
   
   # Or using poetry
   
   poetry install
   

3. Verify installation

   pytest tests/ -q
   

Build & Run

Run all tests:

pytest tests/ -q

Run specific test suite:

pytest tests/unit/ -v

pytest tests/integration/ -v

Type checking:

pyright src/

Code formatting & linting:

ruff check src/

ruff format src/

Features

• Agentic Loop: Plan → Execute → Observe → Replan

• Multi-Capability: SQL, Web, RAG integration

• Quality Control: Built-in validators and reflection

• Memory Management: Conversation history and context

• Security: Credential filtering, authorization checks

• Observability: Structured event tracking

• Modular Design: Use only what you need

Project Structure

src/chatbot_framework/

├── core/              # Core chatbot engine

├── adapters/          # LLM, DB, and RAG providers

├── planning/          # Query planning engine

├── rag/               # Retrieval-Augmented Generation

├── sql/               # Database query handling

├── tools/             # Built-in tools

├── validation/        # Quality control

├── reflection/        # Self-evaluation

├── memory/            # Conversation memory

├── observability/     # Event tracking

└── web/               # Web capabilities

examples/              # Sample implementations

tests/                 # Test suites

Examples

See the examples/ directory for sample implementations:

• 01_minimal_chatbot.py - Basic setup

• 02_knowledge_chatbot.py - With RAG

• 03_enterprise_chatbot.py - Full features

• 06_sql_and_rag_chatbot.py - SQL + RAG

• 07_fastapi_integration.py - API integration

• 11_local_llm_ollama.py - Local LLM support

Configuration

Configure the framework via environment variables or config files:

• API keys for LLM providers

• Database connections

• Vector store settings

• Security policies

See SIMPLIFIED_API.md for detailed API documentation and INTEGRATION_GUIDE.md for integration examples.

Testing

The project includes comprehensive test coverage:

# All tests

pytest tests/

# Specific module

pytest tests/unit/test_config.py -v

# With coverage

pytest tests/ --cov=src/

Type Safety

The project uses Pyright strict mode for type safety:

pyright src/

Development

Install development dependencies:

pip install -e ".[dev]"

This includes:

• pytest & pytest plugins

• pyright

• ruff

• type stubs

• Modular design

• Composable capabilities

License

See LICENSE file for details.