Apppublic

hanbit-church/hanbit-knowledge-base

sourceHugging Faceupdated 1y agoView on Hugging Face

0likes

App README

Hanbit Church Knowledge Base Assistant

A comprehensive church information system powered by AI, providing up-to-date information about Hanbit Church ministries, events, and community through an intelligent assistant with multilingual RAG (Retrieval-Augmented Generation) capabilities.

Features

🏛️ Church-Focused AI Assistant

—Hanbit Church Information: Specialized assistant providing current information about church ministries, events, and community
—Multilingual Support: Full Korean and English conversation support
—Knowledge Base Priority: Uses church documents as primary source, supplements with general Christian knowledge
—Source Attribution: Always cites church documents when providing information

🤖 Advanced AI Capabilities

—Real-time Streaming: Live response streaming for responsive user experience
—RAG Integration: Retrieval-Augmented Generation with multilingual embeddings
—Conversation History: Persistent conversation tracking across sessions
—Dual LLM Support: Ollama (local) and OpenAI (production) integration

📚 Knowledge Management

—Document Upload: Support for PDF, Word, and Markdown documents
—Vector Database: Qdrant-powered semantic search with multilingual embeddings
—Smart Chunking: Intelligent document processing with overlap for better context
—Multilingual Embeddings: Using intfloat/multilingual-e5-large for 100+ language support

🖥️ User Interfaces

—Web Interface: Modern Gradio-based UI with optional drag-and-drop file upload
—Terminal Interface: Command-line chat with streaming responses
—File Management: Upload, search, and manage church documents (when enabled)
—Chat History: Clear conversation history and restore initial greeting
—Configurable UI: File upload can be disabled via environment variable for deployment flexibility

Prerequisites

—Python 3.10+
—Ollama installed and running locally (for local development)
—Qdrant vector database (local or cloud)
—OpenAI API key (for production deployment)

Setup Options

Local Development Setup

bash

# Install Ollama (macOS)
brew install ollama

# Start Ollama service
ollama serve

# Pull the qwen2.5-coder model
ollama pull qwen2.5-coder

# Install and start Qdrant
docker run -p 6333:6333 qdrant/qdrant

Production Setup

—OpenAI API account and key
—Qdrant Cloud instance or self-hosted Qdrant
—Environment variables configured for production

Installation

1.Clone the repository

bash

git clone <repository-url>
cd hanbit-knowledge-base

1.Install dependencies using uv (recommended) or pip

bash

# Using uv (recommended)
uv install

# Or using pip
pip install -r requirements.txt

1.Configure environment variables

bash

cp .env.example .env
# Edit .env file with your configuration:
# - LLM_PROVIDER (ollama/openai)
# - LLM_MODEL (optional)
# - EMBEDDING_MODEL (optional)
# - OPENAI_API_KEY (if using OpenAI)
# - QDRANT_URL and QDRANT_API_KEY (if using Qdrant Cloud)

Usage

Running the Applications

Web Interface (Recommended)

bash

uv run python app.py

Open your browser and go to http://localhost:7860 for the modern Hanbit Church assistant interface with:

—Real-time streaming chat
—Document upload and management
—Multilingual support (Korean/English)
—Initial greeting explaining church assistant capabilities

Terminal Interface

bash

uv run python main.py

Interactive command-line chat with streaming responses and church-focused greeting.

Using the Church Assistant

Church Information Queries

python

from src.agents.chat_agent import ChatAgent
from src.rag.knowledge_base import KnowledgeBase
from src.llm.factory import create_llm_provider

# Initialize the Hanbit Church assistant
llm_provider = create_llm_provider()
knowledge_base = KnowledgeBase()
agent = ChatAgent(llm_provider=llm_provider, knowledge_base=knowledge_base)

# Get initial greeting
print(agent.get_initial_greeting())

# Ask about church services
response = agent.chat("한국어 예배 시간이 언제인가요?")  # Korean
print(response)

# Ask about ministries
response = agent.chat("What ministries are available for children?")  # English
print(response)

# Streaming responses
for chunk in agent.chat_stream("Tell me about upcoming events"):
    print(chunk, end="", flush=True)

Document Management

python

# Add church documents to knowledge base
success = knowledge_base.add_document(
    content="Church service times and information...",
    filename="service_schedule.pdf",
    file_type="pdf"
)

# Search for similar content
results = knowledge_base.search_similar("service times", limit=5)
print(results)

Available Methods

ChatAgent Methods

—get_initial_greeting() -> str: Get church-focused welcome message
—chat(message: str) -> str: Send message and get complete response
—chat_stream(message: str) -> Generator[str, None, None]: Stream response chunks in real-time
—clear_history(): Clear conversation history
—get_history() -> List[Dict[str, str]]: Get conversation history
—set_temperature(temperature: float): Adjust response creativity (0.0-1.0)
—set_rag_enabled(enabled: bool): Enable/disable knowledge base retrieval

KnowledgeBase Methods

—add_document(content, filename, file_type, metadata): Add document to knowledge base
—search_similar(query, limit): Semantic search for relevant content
—list_files(): List all uploaded documents
—delete_file(filename): Remove document from knowledge base

Environment Configuration

Create a .env file based on .env.example:

bash

# LLM Provider Configuration
LLM_PROVIDER=ollama  # Options: "ollama" or "openai"
LLM_MODEL=qwen2.5-coder  # Optional, uses provider defaults

# OpenAI Configuration (if using OpenAI)
OPENAI_API_KEY=your-openai-api-key

# Qdrant Configuration (optional, uses local by default)
QDRANT_URL=https://your-qdrant-instance.com:6333
QDRANT_API_KEY=your-api-key

# Embedding Model Configuration
EMBEDDING_MODEL=intfloat/multilingual-e5-large  # Default multilingual model

# Admin Configuration
IS_ADMIN=true  # Control admin features like file upload in web UI ("true" or "false")

# Logging Configuration
LOG_LEVEL=INFO
LOG_FORMAT=structured

Supported Models

—LLM Models: Any Ollama model or OpenAI model
—Embedding Models:
—intfloat/multilingual-e5-large (default, 1024 dims)
—intfloat/multilingual-e5-base (768 dims)
—intfloat/multilingual-e5-small (384 dims)
—all-MiniLM-L6-v2 (384 dims, English-only)

Development

Running Tests

bash

# Run all tests
PYTHONPATH=. uv run pytest tests/ -v

# Run specific test file
PYTHONPATH=. uv run pytest tests/agents/test_chat_agent.py -v

Project Structure

src/
 agents/
    chat_agent.py       # Main ChatAgent implementation
tests/
 agents/
    test_chat_agent.py  # Unit tests for ChatAgent
CLAUDE.md                   # Development instructions
README.md                   # This file
main.py                     # Terminal chat interface
app.py                      # Gradio web interface
.env.example               # Sample environment configuration
pyproject.toml             # Project configuration

Deployment Options

Local Development

—Uses Ollama for LLM inference
—Local Qdrant instance via Docker
—Multilingual embeddings for semantic search

Production Deployment

—OpenAI API for LLM inference
—Qdrant Cloud for vector database
—Environment variables for configuration

Hugging Face Spaces

Ready for deployment on Hugging Face Spaces with Gradio SDK.

Configuration for Different Deployments

—Admin Mode: Set IS_ADMIN=true for complete functionality with file upload
—User Mode: Set IS_ADMIN=false for simplified interface without admin features
—Restricted Environments: Disable admin features for security-sensitive deployments

Church-Specific Features

Multilingual Support

—Korean: Full conversation support in Korean
—English: Complete English language support
—Auto-detection: Responds in the language of the user's question

Knowledge Base Management

—Upload church documents (PDF, Word, Markdown)
—Semantic search across all uploaded content
—Source attribution for all church information
—Document versioning and management

Ministry Information

—Service schedules and locations
—Ministry programs and contacts
—Event announcements and details
—Community resources and support

Contributing

1.Follow TDD practices (write tests first)
2.Run tests after every change: PYTHONPATH=. uv run pytest tests/ -v
3.Update documentation as needed
4.Follow the existing code style and patterns
5.Ensure Hanbit Church focus in all features

License

[Add your license here]

Key Capabilities Summary

✅ Church-Focused AI Assistant - Specialized for Hanbit Church information and community ✅ Multilingual Support - Korean and English conversation capabilities ✅ RAG Technology - Retrieval-Augmented Generation with semantic search ✅ Document Management - Upload, process, and search church documents ✅ Multiple Interfaces - Web UI and terminal-based chat ✅ Flexible Deployment - Local development and production-ready ✅ Source Attribution - Always cites church documents ✅ Christian Knowledge - Supplements with general Christian guidance when appropriate

Hanbit Church Knowledge Base Assistant - Connecting our community through intelligent, multilingual information access. 🏛️