# 🤖 Banko AI Assistant - RAG Demo
A modern AI-powered expense analysis application with Retrieval-Augmented Generation (RAG) capabilities, built with CockroachDB vector search and multiple AI provider support.
## ✨ Features
- **🔍 Advanced Vector Search**: Enhanced expense search using CockroachDB vector indexes
- **🤖 Multi-AI Provider Support**: OpenAI, AWS Bedrock, IBM Watsonx, Google Gemini
- **🔄 Dynamic Model Switching**: Switch between models without restarting the app
- **👤 User-Specific Indexing**: User-based vector indexes with regional partitioning
- **📊 Data Enrichment**: Contextual expense descriptions for better search accuracy
- **💾 Intelligent Caching**: Multi-layer caching system for optimal performance
- **🌐 Modern Web Interface**: Clean, responsive UI with real-time chat
- **📈 Analytics Dashboard**: Comprehensive expense analysis and insights
- **📦 PyPI Package**: Easy installation with `pip install banko-ai-assistant`
- **🎯 Enhanced Context**: Merchant and amount information included in search context
- **⚡ Performance Optimized**: User-specific vector indexes for faster queries
## 🚀 Quick Start
### Prerequisites
- **Python 3.8+**
- **CockroachDB v25.2.4+** (recommended: [v25.3.1](https://www.cockroachlabs.com/docs/releases/v25.3#v25-3-1))
- **Vector Index Feature Enabled** (required for vector search)
- **AI Provider API Key** (OpenAI, AWS, IBM Watsonx, or Google Gemini)
#### CockroachDB Setup
1. **Download and Install CockroachDB**:
```bash
# Download CockroachDB v25.3.1 (recommended)
# Visit: https://www.cockroachlabs.com/docs/releases/v25.3#v25-3-1
# Or install via package manager
brew install cockroachdb/tap/cockroach # macOS
```
2. **Start CockroachDB Single Node**:
```bash
# Start a single-node cluster (for development)
cockroach start-single-node \
--insecure \
--store=./cockroach-data \
--listen-addr=localhost:26257 \
--http-addr=localhost:8080 \
--background
```
3. **Enable Vector Index Feature**:
```sql
-- Connect to the database
cockroach sql --url="cockroachdb://root@localhost:26257/defaultdb?sslmode=disable"
-- Enable vector index feature (required for vector search)
SET CLUSTER SETTING feature.vector_index.enabled = true;
```
4. **Verify Setup**:
```sql
-- Check if vector index is enabled
SHOW CLUSTER SETTING feature.vector_index.enabled;
-- Should return: true
```
### Installation
#### Option 1: PyPI Installation (Recommended)
```bash
# Install from PyPI
pip install banko-ai-assistant
# Set up environment variables
export WATSONX_API_KEY="your_watsonx_api_key_here"
export WATSONX_PROJECT_ID="your_watsonx_project_id_here"
export WATSONX_MODEL_ID="openai/gpt-oss-120b"
export DATABASE_URL="cockroachdb://root@localhost:26257/defaultdb?sslmode=disable"
# Run the application
python -m banko-ai
```
#### Option 2: Development Installation
```bash
# Clone the repository
git clone https://github.com/cockroachlabs-field/banko-ai-assistant-rag-demo
cd banko-ai-assistant-rag-demo
# Install the package in development mode
pip install -e .
# Run the application
banko-ai run
```
#### Option 3: Direct Dependencies
```bash
# Install dependencies directly
pip install -r requirements.txt
# Run the original app.py (legacy method)
python app.py
```
### Configuration
Set up your environment variables:
```bash
# Required: Database connection
export DATABASE_URL="cockroachdb://root@localhost:26257/defaultdb?sslmode=disable"
# Required: AI Service (choose one)
export AI_SERVICE="watsonx" # or "openai", "aws", "gemini"
# AI Provider Configuration (choose based on AI_SERVICE)
# For IBM Watsonx:
export WATSONX_API_KEY="your_api_key_here"
export WATSONX_PROJECT_ID="your_project_id_here"
export WATSONX_MODEL="meta-llama/llama-2-70b-chat"
# For OpenAI:
export OPENAI_API_KEY="your_api_key_here"
export OPENAI_MODEL="gpt-3.5-turbo"
# For AWS Bedrock:
export AWS_ACCESS_KEY_ID="your_access_key"
export AWS_SECRET_ACCESS_KEY="your_secret_key"
export AWS_REGION="us-east-1"
export AWS_MODEL="anthropic.claude-3-sonnet-20240229-v1:0"
# For Google Gemini:
export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"
export GOOGLE_MODEL="gemini-1.5-pro"
```
### Running the Application
The application automatically creates database tables and loads sample data (5000 records by default):
```bash
# Start with default settings (5000 sample records)
banko-ai run
# Start with custom data amount
banko-ai run --generate-data 10000
# Start without generating data
banko-ai run --no-data
# Start with debug mode
banko-ai run --debug
```
## 🎯 What Happens on Startup
1. **Database Connection**: Connects to CockroachDB and creates necessary tables
2. **Table Creation**: Creates `expenses` table with vector indexes and cache tables
3. **Data Generation**: Automatically generates 5000 sample expense records with enriched descriptions
4. **AI Provider Setup**: Initializes the selected AI provider and loads available models
5. **Web Server**: Starts the Flask application on http://localhost:5000
## 📊 Sample Data Features
The generated sample data includes:
- **Rich Descriptions**: "Bought food delivery at McDonald's for $56.68 fast significant purchase restaurant and service paid with debit card this month"
- **Merchant Information**: Realistic merchant names and categories
- **Amount Context**: Expense amounts with contextual descriptions
- **Temporal Context**: Recent, this week, this month, etc.
- **Payment Methods**: Bank Transfer, Debit Card, Credit Card, Cash, Check
- **User-Specific Data**: Multiple user IDs for testing user-specific search
## 🌐 Web Interface
Access the application at http://localhost:5000
### Main Features
- **🏠 Home**: Overview dashboard with expense statistics
- **💬 Chat**: AI-powered expense analysis and Q&A
- **🔍 Search**: Vector-based expense search
- **⚙️ Settings**: AI provider and model configuration
- **📊 Analytics**: Detailed expense analysis and insights
## 🔧 CLI Commands
```bash
# Run the application
banko-ai run [OPTIONS]
# Generate sample data
banko-ai generate-data --count 2000
# Clear all data
banko-ai clear-data
# Check application status
banko-ai status
# Search expenses
banko-ai search "food delivery" --limit 10
# Show help
banko-ai help
```
## 🔌 API Endpoints
| Endpoint | Method | Description |
|---------------------|--------|---------------------------------------|
| `/` | GET | Web interface |
| `/api/health` | GET | System health check |
| `/api/ai-providers` | GET | Available AI providers |
| `/api/models` | GET | Available models for current provider |
| `/api/search` | POST | Vector search expenses |
| `/api/rag` | POST | RAG-based Q&A |
### API Examples
```bash
# Health check
curl http://localhost:5000/api/health
# Search expenses
curl -X POST http://localhost:5000/api/search \
-H "Content-Type: application/json" \
-d '{"query": "food delivery", "limit": 5}'
# RAG query
curl -X POST http://localhost:5000/api/rag \
-H "Content-Type: application/json" \
-d '{"query": "What are my biggest expenses this month?", "limit": 5}'
```
## 🏗️ Architecture
### Database Schema
- **expenses**: Main expense table with vector embeddings
- **query_cache**: Cached search results
- **embedding_cache**: Cached embeddings
- **insights_cache**: Cached AI insights
- **vector_search_cache**: Cached vector search results
- **cache_stats**: Cache performance statistics
### Vector Indexes
```sql
-- User-specific vector index for personalized search
CREATE INDEX idx_expenses_user_embedding ON expenses
USING cspann (user_id, embedding vector_l2_ops);
-- General vector index for global search
CREATE INDEX idx_expenses_embedding ON expenses
USING cspann (embedding vector_l2_ops);
-- Note: Regional partitioning syntax may vary by CockroachDB version
-- CREATE INDEX idx_expenses_regional ON expenses
-- USING cspann (user_id, embedding vector_l2_ops)
-- LOCALITY REGIONAL BY ROW AS region;
```
**Benefits:**
- **User-specific queries**: Faster search within user's data
- **Contextual results**: Enhanced merchant and amount information
- **Scalable performance**: Optimized for large datasets
- **Multi-tenant support**: Isolated user data with shared infrastructure
## 🔄 AI Provider Switching
Switch between AI providers and models dynamically:
1. Go to **Settings** in the web interface
2. Select your preferred AI provider
3. Choose from available models
4. Changes take effect immediately
### Supported Providers
- **OpenAI**: GPT-3.5, GPT-4, GPT-4 Turbo
- **AWS Bedrock**: Claude 3 Sonnet, Claude 3 Haiku, Llama 2
- **IBM Watsonx**: Granite models, Llama 2, Mistral
- **Google Gemini**: Gemini 1.5 Pro, Gemini 1.5 Flash
## 📈 Performance Features
### Caching System
- **Query Caching**: Caches search results for faster responses
- **Embedding Caching**: Caches vector embeddings to avoid recomputation
- **Insights Caching**: Caches AI-generated insights
- **Multi-layer Optimization**: Intelligent cache invalidation and refresh
### Vector Search Optimization
- **User-Specific Indexes**: Faster search for individual users
- **Regional Partitioning**: Optimized for multi-region deployments
- **Data Enrichment**: Enhanced descriptions improve search accuracy
- **Batch Processing**: Efficient data loading and processing
### Advanced Vector Features
For detailed demonstrations of vector indexing and search capabilities:
📖 **[Vector Index Demo Guide](docs/VECTOR_INDEX_DEMO_GUIDE.md)** - Comprehensive guide covering:
- User-specific vector indexing
- Regional partitioning with multi-region CockroachDB
- Performance benchmarking
- Advanced search queries
- RAG with user context
- Troubleshooting and best practices
## 🛠️ Development
### Project Structure
```
banko_ai/
├── ai_providers/ # AI provider implementations
├── config/ # Configuration management
├── static/ # Web assets and images
├── templates/ # HTML templates
├── utils/ # Database and cache utilities
├── vector_search/ # Vector search and data generation
└── web/ # Flask web application
```
### Adding New AI Providers
1. Create a new provider class in `ai_providers/`
2. Extend the `BaseAIProvider` class
3. Implement required methods
4. Add to the factory in `ai_providers/factory.py`
## 🐛 Troubleshooting
### Common Issues
**CockroachDB Version Issues**
```bash
# Check CockroachDB version (must be v25.2.4+)
cockroach version
# If version is too old, download v25.3.1:
# https://www.cockroachlabs.com/docs/releases/v25.3#v25-3-1
```
**Vector Index Feature Not Enabled**
```bash
# Connect to database and enable vector index feature
cockroach sql --url="cockroachdb://root@localhost:26257/defaultdb?sslmode=disable"
# Enable vector index feature
SET CLUSTER SETTING feature.vector_index.enabled = true;
# Verify it's enabled
SHOW CLUSTER SETTING feature.vector_index.enabled;
```
**Database Connection Error**
```bash
# Start CockroachDB single node
cockroach start-single-node \
--insecure \
--store=./cockroach-data \
--listen-addr=localhost:26257 \
--http-addr=localhost:8080 \
--background
# Verify database exists
cockroach sql --url="cockroachdb://root@localhost:26257/defaultdb?sslmode=disable" --execute "SHOW TABLES;"
```
**AI Provider Disconnected**
- Verify API keys are set correctly
- Check network connectivity
- Ensure the selected model is available
**No Search Results**
- Ensure sample data is loaded: `banko-ai generate-data --count 1000`
- Check vector indexes are created
- Verify search query format
### Debug Mode
```bash
# Run with debug logging
banko-ai run --debug
# Check application status
banko-ai status
```
## 📝 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## 📞 Support
For issues and questions:
- Check the [troubleshooting section](#-troubleshooting)
- Review the [API documentation](#-api-endpoints)
- See the [Vector Index Demo Guide](docs/VECTOR_INDEX_DEMO_GUIDE.md) for advanced features
- Open an issue on GitHub
---
**Built with ❤️ using CockroachDB, Flask, and modern AI technologies such as **
Raw data
{
"_id": null,
"home_page": null,
"name": "banko-ai-assistant",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, rag, vector-search, cockroachdb, expense-analysis, financial-ai",
"author": null,
"author_email": "Virag Tripathi <virag.tripathi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e4/81/477474ae43e8bb402359c7292efe92e26666dd6e62893a0419e8ec763ea3/banko_ai_assistant-1.0.18.tar.gz",
"platform": null,
"description": "# \ud83e\udd16 Banko AI Assistant - RAG Demo\n\nA modern AI-powered expense analysis application with Retrieval-Augmented Generation (RAG) capabilities, built with CockroachDB vector search and multiple AI provider support.\n\n\n\n## \u2728 Features\n\n- **\ud83d\udd0d Advanced Vector Search**: Enhanced expense search using CockroachDB vector indexes\n- **\ud83e\udd16 Multi-AI Provider Support**: OpenAI, AWS Bedrock, IBM Watsonx, Google Gemini\n- **\ud83d\udd04 Dynamic Model Switching**: Switch between models without restarting the app\n- **\ud83d\udc64 User-Specific Indexing**: User-based vector indexes with regional partitioning\n- **\ud83d\udcca Data Enrichment**: Contextual expense descriptions for better search accuracy\n- **\ud83d\udcbe Intelligent Caching**: Multi-layer caching system for optimal performance\n- **\ud83c\udf10 Modern Web Interface**: Clean, responsive UI with real-time chat\n- **\ud83d\udcc8 Analytics Dashboard**: Comprehensive expense analysis and insights\n- **\ud83d\udce6 PyPI Package**: Easy installation with `pip install banko-ai-assistant`\n- **\ud83c\udfaf Enhanced Context**: Merchant and amount information included in search context\n- **\u26a1 Performance Optimized**: User-specific vector indexes for faster queries\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\n- **Python 3.8+**\n- **CockroachDB v25.2.4+** (recommended: [v25.3.1](https://www.cockroachlabs.com/docs/releases/v25.3#v25-3-1))\n- **Vector Index Feature Enabled** (required for vector search)\n- **AI Provider API Key** (OpenAI, AWS, IBM Watsonx, or Google Gemini)\n\n#### CockroachDB Setup\n\n1. **Download and Install CockroachDB**:\n ```bash\n # Download CockroachDB v25.3.1 (recommended)\n # Visit: https://www.cockroachlabs.com/docs/releases/v25.3#v25-3-1\n \n # Or install via package manager\n brew install cockroachdb/tap/cockroach # macOS\n ```\n\n2. **Start CockroachDB Single Node**:\n ```bash\n # Start a single-node cluster (for development)\n cockroach start-single-node \\\n --insecure \\\n --store=./cockroach-data \\\n --listen-addr=localhost:26257 \\\n --http-addr=localhost:8080 \\\n --background\n ```\n\n3. **Enable Vector Index Feature**:\n ```sql\n -- Connect to the database\n cockroach sql --url=\"cockroachdb://root@localhost:26257/defaultdb?sslmode=disable\"\n \n -- Enable vector index feature (required for vector search)\n SET CLUSTER SETTING feature.vector_index.enabled = true;\n ```\n\n4. **Verify Setup**:\n ```sql\n -- Check if vector index is enabled\n SHOW CLUSTER SETTING feature.vector_index.enabled;\n -- Should return: true\n ```\n\n### Installation\n\n#### Option 1: PyPI Installation (Recommended)\n```bash\n# Install from PyPI\npip install banko-ai-assistant\n\n# Set up environment variables\nexport WATSONX_API_KEY=\"your_watsonx_api_key_here\"\nexport WATSONX_PROJECT_ID=\"your_watsonx_project_id_here\"\nexport WATSONX_MODEL_ID=\"openai/gpt-oss-120b\"\nexport DATABASE_URL=\"cockroachdb://root@localhost:26257/defaultdb?sslmode=disable\"\n\n# Run the application\npython -m banko-ai\n```\n\n#### Option 2: Development Installation\n```bash\n# Clone the repository\ngit clone https://github.com/cockroachlabs-field/banko-ai-assistant-rag-demo\ncd banko-ai-assistant-rag-demo\n\n# Install the package in development mode\npip install -e .\n\n# Run the application\nbanko-ai run\n```\n\n#### Option 3: Direct Dependencies\n```bash\n# Install dependencies directly\npip install -r requirements.txt\n\n# Run the original app.py (legacy method)\npython app.py\n```\n\n### Configuration\n\nSet up your environment variables:\n\n```bash\n# Required: Database connection\nexport DATABASE_URL=\"cockroachdb://root@localhost:26257/defaultdb?sslmode=disable\"\n\n# Required: AI Service (choose one)\nexport AI_SERVICE=\"watsonx\" # or \"openai\", \"aws\", \"gemini\"\n\n# AI Provider Configuration (choose based on AI_SERVICE)\n# For IBM Watsonx:\nexport WATSONX_API_KEY=\"your_api_key_here\"\nexport WATSONX_PROJECT_ID=\"your_project_id_here\"\nexport WATSONX_MODEL=\"meta-llama/llama-2-70b-chat\"\n\n# For OpenAI:\nexport OPENAI_API_KEY=\"your_api_key_here\"\nexport OPENAI_MODEL=\"gpt-3.5-turbo\"\n\n# For AWS Bedrock:\nexport AWS_ACCESS_KEY_ID=\"your_access_key\"\nexport AWS_SECRET_ACCESS_KEY=\"your_secret_key\"\nexport AWS_REGION=\"us-east-1\"\nexport AWS_MODEL=\"anthropic.claude-3-sonnet-20240229-v1:0\"\n\n# For Google Gemini:\nexport GOOGLE_APPLICATION_CREDENTIALS=\"path/to/service-account.json\"\nexport GOOGLE_MODEL=\"gemini-1.5-pro\"\n```\n\n### Running the Application\n\nThe application automatically creates database tables and loads sample data (5000 records by default):\n\n```bash\n# Start with default settings (5000 sample records)\nbanko-ai run\n\n# Start with custom data amount\nbanko-ai run --generate-data 10000\n\n# Start without generating data\nbanko-ai run --no-data\n\n# Start with debug mode\nbanko-ai run --debug\n```\n\n\n\n## \ud83c\udfaf What Happens on Startup\n\n1. **Database Connection**: Connects to CockroachDB and creates necessary tables\n2. **Table Creation**: Creates `expenses` table with vector indexes and cache tables\n3. **Data Generation**: Automatically generates 5000 sample expense records with enriched descriptions\n4. **AI Provider Setup**: Initializes the selected AI provider and loads available models\n5. **Web Server**: Starts the Flask application on http://localhost:5000\n\n## \ud83d\udcca Sample Data Features\n\nThe generated sample data includes:\n\n- **Rich Descriptions**: \"Bought food delivery at McDonald's for $56.68 fast significant purchase restaurant and service paid with debit card this month\"\n- **Merchant Information**: Realistic merchant names and categories\n- **Amount Context**: Expense amounts with contextual descriptions\n- **Temporal Context**: Recent, this week, this month, etc.\n- **Payment Methods**: Bank Transfer, Debit Card, Credit Card, Cash, Check\n- **User-Specific Data**: Multiple user IDs for testing user-specific search\n\n\n\n## \ud83c\udf10 Web Interface\n\nAccess the application at http://localhost:5000\n\n### Main Features\n\n- **\ud83c\udfe0 Home**: Overview dashboard with expense statistics\n- **\ud83d\udcac Chat**: AI-powered expense analysis and Q&A\n- **\ud83d\udd0d Search**: Vector-based expense search\n- **\u2699\ufe0f Settings**: AI provider and model configuration\n- **\ud83d\udcca Analytics**: Detailed expense analysis and insights\n\n\n\n## \ud83d\udd27 CLI Commands\n\n```bash\n# Run the application\nbanko-ai run [OPTIONS]\n\n# Generate sample data\nbanko-ai generate-data --count 2000\n\n# Clear all data\nbanko-ai clear-data\n\n# Check application status\nbanko-ai status\n\n# Search expenses\nbanko-ai search \"food delivery\" --limit 10\n\n# Show help\nbanko-ai help\n```\n\n## \ud83d\udd0c API Endpoints\n\n| Endpoint | Method | Description |\n|---------------------|--------|---------------------------------------|\n| `/` | GET | Web interface |\n| `/api/health` | GET | System health check |\n| `/api/ai-providers` | GET | Available AI providers |\n| `/api/models` | GET | Available models for current provider |\n| `/api/search` | POST | Vector search expenses |\n| `/api/rag` | POST | RAG-based Q&A |\n\n### API Examples\n\n```bash\n# Health check\ncurl http://localhost:5000/api/health\n\n# Search expenses\ncurl -X POST http://localhost:5000/api/search \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"food delivery\", \"limit\": 5}'\n\n# RAG query\ncurl -X POST http://localhost:5000/api/rag \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"What are my biggest expenses this month?\", \"limit\": 5}'\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Database Schema\n\n- **expenses**: Main expense table with vector embeddings\n- **query_cache**: Cached search results\n- **embedding_cache**: Cached embeddings\n- **insights_cache**: Cached AI insights\n- **vector_search_cache**: Cached vector search results\n- **cache_stats**: Cache performance statistics\n\n### Vector Indexes\n\n```sql\n-- User-specific vector index for personalized search\nCREATE INDEX idx_expenses_user_embedding ON expenses \nUSING cspann (user_id, embedding vector_l2_ops);\n\n-- General vector index for global search\nCREATE INDEX idx_expenses_embedding ON expenses \nUSING cspann (embedding vector_l2_ops);\n\n-- Note: Regional partitioning syntax may vary by CockroachDB version\n-- CREATE INDEX idx_expenses_regional ON expenses \n-- USING cspann (user_id, embedding vector_l2_ops) \n-- LOCALITY REGIONAL BY ROW AS region;\n```\n\n**Benefits:**\n- **User-specific queries**: Faster search within user's data\n- **Contextual results**: Enhanced merchant and amount information\n- **Scalable performance**: Optimized for large datasets\n- **Multi-tenant support**: Isolated user data with shared infrastructure\n\n\n\n## \ud83d\udd04 AI Provider Switching\n\nSwitch between AI providers and models dynamically:\n\n1. Go to **Settings** in the web interface\n2. Select your preferred AI provider\n3. Choose from available models\n4. Changes take effect immediately\n\n### Supported Providers\n\n- **OpenAI**: GPT-3.5, GPT-4, GPT-4 Turbo\n- **AWS Bedrock**: Claude 3 Sonnet, Claude 3 Haiku, Llama 2\n- **IBM Watsonx**: Granite models, Llama 2, Mistral\n- **Google Gemini**: Gemini 1.5 Pro, Gemini 1.5 Flash\n\n\n\n## \ud83d\udcc8 Performance Features\n\n### Caching System\n\n- **Query Caching**: Caches search results for faster responses\n- **Embedding Caching**: Caches vector embeddings to avoid recomputation\n- **Insights Caching**: Caches AI-generated insights\n- **Multi-layer Optimization**: Intelligent cache invalidation and refresh\n\n### Vector Search Optimization\n\n- **User-Specific Indexes**: Faster search for individual users\n- **Regional Partitioning**: Optimized for multi-region deployments\n- **Data Enrichment**: Enhanced descriptions improve search accuracy\n- **Batch Processing**: Efficient data loading and processing\n\n### Advanced Vector Features\n\nFor detailed demonstrations of vector indexing and search capabilities:\n\n\ud83d\udcd6 **[Vector Index Demo Guide](docs/VECTOR_INDEX_DEMO_GUIDE.md)** - Comprehensive guide covering:\n- User-specific vector indexing\n- Regional partitioning with multi-region CockroachDB\n- Performance benchmarking\n- Advanced search queries\n- RAG with user context\n- Troubleshooting and best practices\n\n\n\n## \ud83d\udee0\ufe0f Development\n\n### Project Structure\n\n```\nbanko_ai/\n\u251c\u2500\u2500 ai_providers/ # AI provider implementations\n\u251c\u2500\u2500 config/ # Configuration management\n\u251c\u2500\u2500 static/ # Web assets and images\n\u251c\u2500\u2500 templates/ # HTML templates\n\u251c\u2500\u2500 utils/ # Database and cache utilities\n\u251c\u2500\u2500 vector_search/ # Vector search and data generation\n\u2514\u2500\u2500 web/ # Flask web application\n```\n\n### Adding New AI Providers\n\n1. Create a new provider class in `ai_providers/`\n2. Extend the `BaseAIProvider` class\n3. Implement required methods\n4. Add to the factory in `ai_providers/factory.py`\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n**CockroachDB Version Issues**\n```bash\n# Check CockroachDB version (must be v25.2.4+)\ncockroach version\n\n# If version is too old, download v25.3.1:\n# https://www.cockroachlabs.com/docs/releases/v25.3#v25-3-1\n```\n\n**Vector Index Feature Not Enabled**\n```bash\n# Connect to database and enable vector index feature\ncockroach sql --url=\"cockroachdb://root@localhost:26257/defaultdb?sslmode=disable\"\n\n# Enable vector index feature\nSET CLUSTER SETTING feature.vector_index.enabled = true;\n\n# Verify it's enabled\nSHOW CLUSTER SETTING feature.vector_index.enabled;\n```\n\n**Database Connection Error**\n```bash\n# Start CockroachDB single node\ncockroach start-single-node \\\n --insecure \\\n --store=./cockroach-data \\\n --listen-addr=localhost:26257 \\\n --http-addr=localhost:8080 \\\n --background\n\n# Verify database exists\ncockroach sql --url=\"cockroachdb://root@localhost:26257/defaultdb?sslmode=disable\" --execute \"SHOW TABLES;\"\n```\n\n**AI Provider Disconnected**\n- Verify API keys are set correctly\n- Check network connectivity\n- Ensure the selected model is available\n\n**No Search Results**\n- Ensure sample data is loaded: `banko-ai generate-data --count 1000`\n- Check vector indexes are created\n- Verify search query format\n\n### Debug Mode\n\n```bash\n# Run with debug logging\nbanko-ai run --debug\n\n# Check application status\nbanko-ai status\n```\n\n## \ud83d\udcdd License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## \ud83d\udcde Support\n\nFor issues and questions:\n- Check the [troubleshooting section](#-troubleshooting)\n- Review the [API documentation](#-api-endpoints)\n- See the [Vector Index Demo Guide](docs/VECTOR_INDEX_DEMO_GUIDE.md) for advanced features\n- Open an issue on GitHub\n\n---\n\n**Built with \u2764\ufe0f using CockroachDB, Flask, and modern AI technologies such as **\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-powered expense analysis and RAG system with CockroachDB vector search and multi-provider AI support",
"version": "1.0.18",
"project_urls": {
"Bug Tracker": "https://github.com/cockroachlabs-field/banko-ai-assistant-rag-demo/issues",
"Documentation": "https://github.com/cockroachlabs-field/banko-ai-assistant-rag-demo#readme",
"Homepage": "https://github.com/cockroachlabs-field/banko-ai-assistant-rag-demo",
"Repository": "https://github.com/cockroachlabs-field/banko-ai-assistant-rag-demo"
},
"split_keywords": [
"ai",
" rag",
" vector-search",
" cockroachdb",
" expense-analysis",
" financial-ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2ca9ebd4dc166640a72497f8f9bbdae742d1d2b034269c33b5c147d389aaf887",
"md5": "5b06d33cc64e696953d8ae061487995f",
"sha256": "47f9ea4601e8269625f56e629bb61cacbf466af757cb09a91acabd318d4d666a"
},
"downloads": -1,
"filename": "banko_ai_assistant-1.0.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b06d33cc64e696953d8ae061487995f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8914549,
"upload_time": "2025-09-09T01:50:59",
"upload_time_iso_8601": "2025-09-09T01:50:59.315942Z",
"url": "https://files.pythonhosted.org/packages/2c/a9/ebd4dc166640a72497f8f9bbdae742d1d2b034269c33b5c147d389aaf887/banko_ai_assistant-1.0.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e481477474ae43e8bb402359c7292efe92e26666dd6e62893a0419e8ec763ea3",
"md5": "a0113194c8da60e02956c1b52c8fce26",
"sha256": "0e0379f35c65a5938e63e7fe01f5aef77c9c567ae745ba2ffa5010e31d96e9ab"
},
"downloads": -1,
"filename": "banko_ai_assistant-1.0.18.tar.gz",
"has_sig": false,
"md5_digest": "a0113194c8da60e02956c1b52c8fce26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8862558,
"upload_time": "2025-09-09T01:51:02",
"upload_time_iso_8601": "2025-09-09T01:51:02.307217Z",
"url": "https://files.pythonhosted.org/packages/e4/81/477474ae43e8bb402359c7292efe92e26666dd6e62893a0419e8ec763ea3/banko_ai_assistant-1.0.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 01:51:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cockroachlabs-field",
"github_project": "banko-ai-assistant-rag-demo",
"github_not_found": true,
"lcname": "banko-ai-assistant"
}
JSON
