README.md

KaLLaM - Motivational-Therapeutic Advisor

KaLLaM is a bilingual (Thai/English) multi-agent assistant designed for physical and mental-health conversations. It orchestrates specialized agents (Supervisor, Doctor, Psychologist, Translator, Summarizer), persists state in SQLite, and exposes Gradio front-ends alongside data and can use evaluation tooling for model psychological skill benchmark. Finalist in PAN-SEA AI DEVELOPER CHALLENGE 2025 Round 2: Develop Deployable Solutions & Pitch

---

title: KaLLaM Demo emoji: 🐠 colorFrom: yellow colorTo: yellow sdk: gradio sdk_version: 5.46.0 app_file: app.py pinned: false license: apache-2.0 short_description: 'PAN-SEA AI DEVELOPER CHALLENGE 2025 Round 2: Develop Deploya'

Highlights

• Multi-agent orchestration that routes requests to domain specialists.
• Thai/English support backed by SEA-Lion translation services.
• Conversation persistence with export utilities for downstream analysis.
• Ready-to-run Gradio demo and developer interfaces.
• Evaluation scripts for MISC/BiMISC-style coding pipelines.

Requirements

• Python 3.10 or newer (3.11+ recommended; Docker/App Runner images use 3.11).
• pip, virtualenv (or equivalent), and Git for local development.
• Access tokens for the external models you plan to call (SEA-Lion, Google Gemini, optional OpenAI or AWS Bedrock).

Quick Start (Local)

1. Clone the repository and switch into it.
2. Create and activate a virtual environment:

   python -m venv .venv
   .venv\Scripts\Activate.ps1
   

   python -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies (editable mode keeps imports pointing at src/):

   python -m pip install --upgrade pip setuptools wheel
   pip install -e .[dev]
   

4. Create a .env file at the project root (see the next section) and populate the keys you have access to.
5. Launch one of the Gradio apps:

   python gui/chatbot_demo.py      # bilingual demo UI
   python gui/chatbot_dev_app.py   # Thai-first developer UI
   

The Gradio server binds to http://127.0.0.1:7860 by default; override via GRADIO_SERVER_NAME and GRADIO_SERVER_PORT.

Environment Configuration

Configuration is loaded with python-dotenv, so any variables in .env are available at runtime. Define only the secrets relevant to the agents you intend to use.

Core

• SEA_LION_API_KEY or (SEA_LION_GATEWAY_URL + SEA_LION_GATEWAY_TOKEN) for SEA-Lion access.
• SEA_LION_BASE_URL (optional; defaults to https://api.sea-lion.ai/v1).
• SEA_LION_MODEL_ID to override the default SEA-Lion model.
• GEMINI_API_KEY for Doctor/Psychologist English responses.

Optional integrations

• OPENAI_API_KEY if you enable any OpenAI-backed tooling via strands-agents.
• AWS_REGION (and optionally AWS_DEFAULT_REGION) plus temporary credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) when running Bedrock-backed flows.
• AWS_ROLE_ARN if you assume roles for Bedrock access.
• NGROK_AUTHTOKEN when tunnelling Gradio externally.
• TAVILY_API_KEY if you wire in search or retrieval plugins.

Example scaffold:

SEA_LION_API_KEY=your-sea-lion-token
SEA_LION_MODEL_ID=aisingapore/Gemma-SEA-LION-v4-27B-IT
GEMINI_API_KEY=your-gemini-key
OPENAI_API_KEY=sk-your-openai-key
AWS_REGION=ap-southeast-2
# AWS_ACCESS_KEY_ID=...
# AWS_SECRET_ACCESS_KEY=...
# AWS_SESSION_TOKEN=...

Keep .env out of version control and rotate credentials regularly. You can validate temporary AWS credentials with python test_credentials.py.

Running and Persistence

• Conversations, summaries, and metadata persist to chatbot_data.db (SQLite). The schema is created automatically on first run.
• Export session transcripts with ChatbotManager.export_session_json(); JSON files land in exported_sessions/.
• Logs are emitted per agent into logs/ (daily files) and to stdout.

Docker

Build and run the containerised Gradio app:

docker build -t kallam .
docker run --rm -p 8080:8080 --env-file .env kallam

Environment variables are read at runtime; use --env-file or -e flags to provide the required keys. Override the entry script with APP_FILE, for example -e APP_FILE=gui/chatbot_dev_app.py.

AWS App Runner

The repo ships with apprunner.yaml for AWS App Runner's managed Python 3.11 runtime.

1. Push the code to a connected repository (GitHub or CodeCommit) or supply an archive.
2. In the App Runner console choose Source code -> Managed runtime and upload/select apprunner.yaml.
3. Configure AWS Secrets Manager references for the environment variables listed under run.env (SEA-Lion, Gemini, OpenAI, Ngrok, etc.).
4. Deploy. App Runner exposes the Gradio UI on the service URL and honours the $PORT variable (defaults to 8080).

For fully containerised deployments on App Runner, ECS, or EKS, build the Docker image and supply the same environment variables.

Project Layout

project-root/
|-- src/kallam/
|   |-- app/                # ChatbotManager facade
|   |-- domain/agents/      # Supervisor, Doctor, Psychologist, Translator, Summarizer, Orchestrator
|   |-- infra/              # SQLite stores, exporter, token counter
|   `-- infrastructure/     # Shared SEA-Lion configuration helpers
|-- gui/                    # Gradio demo and developer apps
|-- scripts/                # Data prep and evaluation utilities
|-- data/                   # Sample datasets (gemini, human, orchestrated, SEA-Lion)
|-- exported_sessions/      # JSON exports created at runtime
|-- logs/                   # Runtime logs (generated)
|-- Dockerfile
|-- apprunner.yaml
|-- test_credentials.py
`-- README.md

Development Tooling

• Run tests: pytest -q
• Lint: ruff check src
• Type-check: mypy src
• Token usage: see src/kallam/infra/token_counter.py
• Supervisor/translator fallbacks log warnings if credentials are missing.

Scripts and Evaluation

The scripts/ directory includes:

• eng_silver_misc_coder.py and thai_silver_misc_coder.py for SEA-Lion powered coding pipelines.
• model_evaluator.py plus preprocessing and visualisation helpers (ex_data_preprocessor.py, in_data_preprocessor.py, visualizer.ipynb).

Note:

Proporsal

Refer to KaLLaM Proporsal.pdf for more information of the project

Citation

See Citation.md for references and datasets.

License

Apache License 2.0. Refer to LICENSE for full terms.