BasicChat: Your Intelligent Local AI Assistant

🔒 Privacy-First • 🧠 Advanced Reasoning • 🔬 Deep Research • ⚡ High Performance

An intelligent, private AI assistant that runs entirely on your local machine

---

🎥 Demo

Real-time reasoning and document analysis with local AI models

---

🚀 Quick Start

🟢 TL;DR:

1. Install Ollama and Python 3.11+
2. Clone this repo: git clone ... && cd basic-chat
3. Create venv: python -m venv venv && source venv/bin/activate
4. Install deps: pip install -r requirements.txt
5. Pull models: ollama pull mistral and ollama pull nomic-embed-text
6. Start app: ./start_basicchat.sh (recommended) or ./start_dev.sh
7. Visit: http://localhost:8501 (or your chosen port)

Prerequisites

• Ollama (local LLM server)
• Python 3.11+
• Redis (optional, for background tasks)
• Git

Install Required Models

ollama pull mistral              # Reasoning model
ollama pull nomic-embed-text     # Embedding model for RAG
ollama pull llava                # (Optional) Vision model for images

Clone & Setup

git clone https://github.com/khaosans/basic-chat-template.git
cd basic-chat-template
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Start the Application

# Start Ollama (if not running)
ollama serve &

# Start app with all services (recommended)
./start_basicchat.sh
# or for dev mode
./start_dev.sh

App URLs:

• Main App: http://localhost:8501
• Task Monitor (Flower): http://localhost:5555
• Redis: localhost:6379
• Ollama: localhost:11434

---

🏆 Best Practices & Pro Tips

• 🟢 Always use local code for E2E and dev (not Docker)
• 🟢 Run health checks before E2E: poetry run python scripts/e2e_health_check.py
• 🟢 Use .env.local for secrets and config (never commit keys)
• 🟢 Use streaming for best UX
• 🟢 Monitor logs and Flower for background tasks
• 🟢 Stop all Docker containers before local dev/E2E
• 🟢 Ensure backwards compatibility for stored data
• 🟢 Store all important keys in .env.local
• 🟢 Use bunx for TypeScript, poetry for Python
• 🟢 Prefer 0.0.0.0 over localhost for server hosts
• 🟢 Check progress.md for always-up-to-date tips

---

🛠️ Development & Testing

• Run all tests: pytest -n auto
• E2E tests: bunx playwright test --reporter=list
• Coverage: pytest --cov=app --cov-report=html
• Pre-commit hooks: pre-commit run --all-files
• Type checking: mypy . --strict
• CI/CD: Always starts from source, not Docker

---

🤖 LLM Judge Quality Assurance

BasicChat includes an intelligent LLM Judge that evaluates code quality, test coverage, documentation, architecture, security, and performance.

Quick Start

# Automatic setup
./scripts/setup_local_llm_judge.sh

# Quick evaluation (smart backend selection)
make llm-judge-quick

# Full evaluation (smart backend selection)
make llm-judge

Features

• Smart Backend Selection: Automatically chooses Ollama (local) or OpenAI (remote/CI)
• Comprehensive Evaluation: 6 categories with weighted scoring
• Actionable Reports: Prioritized improvement plans
• Multiple Backends: Ollama (local) and OpenAI (cloud) with automatic fallback
• CI/CD Integration: Automated quality gates with OpenAI for remote environments
• Deterministic Results: Consistent evaluation standards

Generated Reports

• llm_judge_action_items.md - Prioritized action plan
• llm_judge_improvement_tips.md - Specific improvement tips
• llm_judge_results.json - Detailed evaluation data

📖 Full Documentation: Local LLM Judge Setup

🧩 Troubleshooting

• Redis not running?: brew services start redis or sudo systemctl start redis
• Ollama not running?: ollama serve
• Port in use?: lsof -i :8501 then kill -9 <PID>
• Permission issues?: chmod +x *.sh
• Check logs: tail -f basicchat.log
• Health check: poetry run python scripts/e2e_health_check.py
• LLM Judge issues?: See Local LLM Judge Setup

---

🏗️ Architecture Overview

+-------------------+      +-------------------+      +-------------------+
|   User Interface  | ---> |  Reasoning Engine | ---> |   Ollama/Tools    |
+-------------------+      +-------------------+      +-------------------+
        |                        |                            |
        v                        v                            v
+-------------------+      +-------------------+      +-------------------+
| Document Uploads  | ---> | Document Processor| ---> |  ChromaDB/Vector  |
+-------------------+      +-------------------+      +-------------------+

Mermaid: System Architecture

graph TB
    subgraph "🎨 User Interface"
        UI[Web Interface]
        AUDIO[Audio Processing]
    end
    subgraph "🧠 Core Logic"
        RE[Reasoning Engine]
        DP[Document Processor]
        TR[Tool Registry]
    end
    subgraph "⚡ Services"
        AO[Ollama Client]
        VS[Vector Store]
        CS[Cache Service]
        WS[Web Search]
    end
    subgraph "🗄️ Storage"
        CHROMA[Vector Database]
        CACHE[Memory Cache]
        FILES[File Storage]
    end
    subgraph "🌐 External"
        OLLAMA[LLM Server]
        DDG[Search Engine]
    end
    UI --> RE
    UI --> DP
    AUDIO --> RE
    RE --> AO
    RE --> VS
    RE --> TR
    DP --> VS
    TR --> WS
    AO --> OLLAMA
    VS --> CHROMA
    CS --> CACHE
    WS --> DDG
    CHROMA --> FILES
    CACHE --> FILES

Loading

---

📚 Documentation & Further Reading

• Startup Guide
• Development Guide
• Features Overview
• System Architecture
• Technical Overview
• Planning & Roadmap
• Evaluators & LLM Judge
• Local LLM Judge Setup
• progress.md — always up-to-date best practices

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ using modern Python, async/await, and best practices for production-ready AI applications.