Spaces:
Runtime error
Runtime error
| # 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. | |