> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference applications

> Run two complete Python applications built on the MKA1 API: ticket triage and CSV analyst.

Two runnable reference applications show what you can build with the MKA1 API. Each is a small Python web app with a browser interface, fictional sample data, and its own tests. The source is in the public [mka1-reference-apps](https://github.com/MeetKai/mka1-reference-apps) repository under the Apache License 2.0.

| Application | What it does | MKA1 features |
| - | - | - |
| [Ticket triage](#ticket-triage) | Turns a customer-support ticket into a suggested team, priority, rationale, and next action | Responses with structured output |
| [CSV analyst](#csv-analyst) | Analyzes an uploaded CSV in a sandbox and returns an HTML report | Responses with the `shell` tool, and sandbox sessions and files |

Both apps use the MKA1 Python SDK. Each app directory is self-contained, so you can copy it into your own repository.

## Before you start

You need:

* Python 3.12 or later and [uv](https://docs.astral.sh/uv/getting-started/installation/).
* An MKA1 [API key](https://docs.mka1.com/docs/authentication.md) and a [model](https://docs.mka1.com/docs/models.md) enabled in your organization.
* For CSV analyst, sandbox capacity on your cluster.

Clone the repository:

```bash theme={null}
git clone https://github.com/MeetKai/mka1-reference-apps.git
cd mka1-reference-apps
```

The apps call the live API, so their requests use your organization's models and, for CSV analyst, its sandbox resources. The API key stays in the Python server; the browser never receives it. Each request uses a new demo end-user identity in `X-On-Behalf-Of`, and each Responses request sets `store` to `false`.

## Ticket triage

Source: [`apps/ticket-triage`](https://github.com/MeetKai/mka1-reference-apps/tree/main/apps/ticket-triage)

Paste a telecom support ticket or choose a fictional example. The app suggests a team (billing, technical support, or account services), a priority from P1 to P3, a summary, a rationale, and a next action for a human reviewer. It doesn't submit tickets, change accounts, or send messages.

The app demonstrates:

* A Responses request with routing instructions and a strict JSON schema in `text.format`, so the model returns a structured decision.
* Validation of that decision before it's shown. The app rejects incomplete responses, refusals, invalid JSON, unknown team or priority values, and extra fields.

It needs a model that supports structured output. The example configuration names `openai:gpt-4.1-mini`; availability depends on your organization.

To run it, install the dependencies and create the configuration file:

```bash theme={null}
cd apps/ticket-triage
uv sync --locked
cp .env.example .env
```

Edit `.env`. Set `MKA1_API_KEY` to your API key, `MKA1_SERVER_URL` to your cluster's gateway URL, and `MKA1_MODEL` to an enabled model that supports structured output. Then start the app:

```bash theme={null}
uv run uvicorn app:app --host 127.0.0.1 --port 8001
```

Open `http://127.0.0.1:8001`, choose **Business connectivity outage**, and submit the ticket. Expect `technical_support` and `P1`. Wording can vary between model runs.

## CSV analyst

Source: [`apps/csv-analyst`](https://github.com/MeetKai/mka1-reference-apps/tree/main/apps/csv-analyst)

Upload a CSV, ask a question, and download an HTML report with computed findings, tables, methods, and limitations. Each analysis runs in its own sandbox.

The app demonstrates:

* The sandbox session lifecycle: it creates a session with the Python feature and a ten-minute lifetime, uploads the CSV, downloads the report, and terminates the session when the analysis ends, including after a failure.
* A Responses request with a `shell` tool attached to that session. The model uses Python in the sandbox to analyze the file and write the report.
* Validation and sanitization of the generated report before the browser receives it.

It needs a model that can use shell tools and sandbox capacity on your cluster. The example configuration names `openai:gpt-4.1`; availability depends on your organization.

To run it, install the dependencies and create the configuration file:

```bash theme={null}
cd apps/csv-analyst
uv sync --locked
cp .env.example .env
```

Edit `.env` with your API key, gateway URL, and model, using the same variables as ticket triage. Then start the app:

```bash theme={null}
uv run uvicorn app:app --host 127.0.0.1 --port 8002
```

Open `http://127.0.0.1:8002`, click **Use example data**, keep the default question, and click **Generate report**. Download the report when it finishes. In the sample data, monthly revenue totals are $61,000 for July, $64,950 for August, and \$69,000 for September; use them to check the report.

The app accepts a CSV of up to 1 MB, 20,000 data rows, and 50 columns, and runs one analysis at a time per server process. Review each report before you rely on it: a completed response doesn't prove that every calculation is correct.

## Before you host an app for other users

Both apps are meant to run locally: they bind to localhost and reject cross-origin browser submissions. Before you host one for other users:

* Add application authentication, and map authenticated users to authorized end-user identities.
* Enforce per-user quotas.
* Configure your reverse proxy and allowed hosts.
* Keep API keys on the server.
* For CSV analyst, enforce any network and filesystem restrictions you need through your sandbox infrastructure. Model instructions aren't an isolation boundary.

## Related guides

* [Generate a response](https://docs.mka1.com/docs/generate-a-response.md)
* [Code execution](https://docs.mka1.com/docs/code-execution.md)
* [Sandbox](https://docs.mka1.com/docs/sandbox.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.