# 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:
   ```powershell
   python -m venv .venv
   .venv\Scripts\Activate.ps1
   ```
   ```bash
   python -m venv .venv
   source .venv/bin/activate
   ```
3. Install dependencies (editable mode keeps imports pointing at `src/`):
   ```bash
   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:
   ```bash
   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:
```env
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:
```bash
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.