Update README.md

README.md

@@ -1,132 +1,143 @@
-# 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
-
-## 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.
-
+# 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: {{title}}
+emoji: {{emoji}}
+colorFrom: {{colorFrom}}
+colorTo: {{colorTo}}
+sdk: {{sdk}}
+sdk_version: "{{sdkVersion}}"
+app_file: app.py
+pinned: false
+---
+
+## 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.
+