kolokwa_connect

# Kolokwa Connect

Kolokwa Connect is a web platform that makes the Kolokwa language accessible, learnable, and discoverable. Built with Django and modern NLP tools, the platform offers a dynamic Kolokwa–English dictionary, gamified learning, community contributions, and Model Context Protocol (MCPs) designed to power natural language features such as translation and semantic search.

Table of Contents

• Introduction
• Features
• Architecture
• Technology Stack
• Getting Started
• Running MCP Servers
• Deployment
• API Documentation
• Contributing
• License
• Contact

Introduction

We believe language is culture, identity, and connection. Most language technology favors high-resource languages; Kolokwa Connect is our blueprint for how communities and AI can work together to digitally empower low-resource languages. Our goal is to make Kolokwa visible online — to help preserve vocabulary, enable translation, and open learning pathways for speakers and learners alike.

Features

Kolokwa ↔ English Dictionary

• Browse, search, and contribute entries.
• Rich entry pages: definitions, example sentences, optional audio pronunciations.
• Community moderation, voting, and a review queue for pending entries.

User Accounts & Profiles

• Email/password registration and social auth via django-allauth.
• Optional enterprise SSO via WorkOS.
• Profiles show user contributions and gamification stats.

Gamification

• Leaderboards for top contributors.
• Achievements / badges for milestones.
• Daily challenges and progress stats.

Natural Language Interaction (NLI)

• Integration with OpenAI and Anthropic APIs.
• Retrieval-Augmented Generation (RAG) for semantic search.
• Translation helpers (Kolokwa ↔ English).

Model Context Protocol (MCPs)

• Dedicated MCPs for dictionary lookups and translation logic — lightweight services that integrate into the MCP Hackathon ecosystem.

RESTful API

• API endpoints for core features implemented with Django REST Framework (DRF).
• JWT token support and auto-generated docs (drf-spectacular / Swagger UI).

Media & Async

• Cloudinary for media (avatars, audio).
• Celery + Redis for background tasks (embeddings, notifications).

Responsive UI

• Modern, mobile-friendly pages built with Django templates, Bootstrap, and plain JS.

Architecture

We split work into:

• Web application (Django): Core website, front-end UI, authentication, contribution workflows, and API.
• Dictionary MCP: Handles lookup, candidate ranking, and RAG pipelines.
• Translator MCP: Dedicated translator microservice (Kolokwa ↔ English).

Each MCP is designed to run independently and communicate over HTTP/gRPC to allow easy submission to MCP platforms.

Technology Stack

Backend

• Python 3.x, Django, Django REST Framework
• django-allauth, WorkOS (SSO)
• Celery, Redis
• Cloudinary (media)
• OpenAI API, Anthropic API
• drf-spectacular (Swagger)

Frontend

• HTML5, CSS3 (SCSS, Bootstrap), JavaScript
• Django templates

Database & Deployment

• SQLite (development), PostgreSQL (production-ready via environment variables)
• Docker & Docker Compose (deployment patterns)
• Nginx (recommended for production)

Getting Started

Quick commands to get the app running locally.

Clone Repository

git clone https://github.com/E-ditital1000/Kolokwa_connect.git
cd Kolokwa_connect

Create and Activate Virtual Environment

python -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate         # Windows

Install Dependencies

pip install -r requirements.txt

Configure Environment Variables

Create a .env file in the project root and add the required variables:

SECRET_KEY=your_django_secret_key
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
WORKOS_API_KEY=your_workos_api_key
WORKOS_CLIENT_ID=your_workos_client_id
CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_api_secret
REDIS_URL=redis://localhost:6379/0
DATABASE_ENGINE=django.db.backends.sqlite3
DATABASE_NAME=db.sqlite3

Run Database Migrations

python manage.py migrate

Create a Superuser (Optional)

python manage.py createsuperuser

Collect Static Files

python manage.py collectstatic

Start the Development Server

python manage.py runserver
# Open http://127.0.0.1:8000/

Running MCP Servers

Two example MCP servers are included for the hackathon demo:

Dictionary MCP

python kolokwa/src/kolokwa_mcp/run_dictionary_server.py

Translator MCP

python kolokwa/src/kolokwa_mcp/run_translator_server.py

Each MCP script spins up a lightweight HTTP server that accepts requests from the main app or client. See the kolokwa/src/kolokwa_mcp folder for configuration and endpoints.

Deployment

We include Dockerfile.web, Dockerfile.mcp, and a docker-compose.yml to support containerized development and deployment.

Typical deployment flow:

docker-compose build
docker-compose up -d
docker-compose exec web python manage.py migrate

For production, configure environment variables securely, use PostgreSQL, and set DEBUG=False and proper ALLOWED_HOSTS.

API Documentation

When the server runs, API documentation is available at:

http://127.0.0.1:8000/api/docs/

(Uses drf-spectacular / Swagger UI if enabled)

Contributing

We welcome contributions from anyone interested in language tech, localization, and community data collection. If you want to contribute:

• Fork the repository.
• Create a feature branch.
• Open a Pull Request (PR) describing the change.
• Add tests where appropriate.
• Please follow our code style and include test coverage for critical NLP logic.

License

This project is licensed under the MIT License.

Contact

Team: NextGen Creators Facebook: https://web.facebook.com/profile.php?id=61575351715515 Repository: https://github.com/E-ditital1000/Kolokwa_connect