# Credit Risk Copilot

A natural-language interface to a credit risk database. A user asks a question in English. The
service returns a validated answer, a chart, and the SQL it ran.

The point of the project is not the SQL generation. The point is the boundary that decides which
SQL is allowed to run.

## Status

Scaffolded 2026-08-05. No agent yet. No database yet. The preflight check runs.

## Requirements

| Need | Version | State on this machine |
|---|---|---|
| Python | 3.12 | installed |
| Docker Desktop | any current | installed |
| Terraform | 1.x | **not installed** |
| AWS CLI | v2 | **not installed** |

Use Python 3.12, not 3.13. The 3.13 interpreter is ahead of the ML ecosystem, and a package that
ships compiled wheels can lag the interpreter by a year.

## How to run it

1. Create the virtual environment:
   ```
   py -3.12 -m venv .venv
   ```
2. Activate it:
   ```
   .venv\Scripts\activate.bat
   ```
   Use the `.bat` file. PowerShell blocks `Activate.ps1` under the default execution policy.
3. Copy the example environment file:
   ```
   copy .env.local.example .env.local
   ```
4. Open `.env.local` and set `DEEPSEEK_API_KEY`.
5. Run the preflight check:
   ```
   py -3.12 -m app.doctor
   ```
   The check imports only the standard library, so it runs before step 6.
6. Install the dependencies:
   ```
   pip install -r requirements.txt
   ```

## Environment variables

`.env.local` holds every secret. The file is gitignored. Never commit it. If a key reaches a
commit, rotate the key, because removal of the commit does not undo the exposure.

| Variable | Required | Purpose |
|---|---|---|
| `DEEPSEEK_API_KEY` | yes, for DeepSeek | The API key |
| `DEEPSEEK_MODEL` | no | Defaults to `deepseek-v4-flash` |
| `LLM_PROVIDER` | no | `deepseek` or `ollama`. Defaults to `deepseek` |
| `OLLAMA_BASE_URL` | no | The local fallback. Needs no key |
| `DATABASE_URL` | yes | The Postgres connection string |
| `LANGSMITH_API_KEY` | no | Tracing. The app runs without it |

**The model names changed.** DeepSeek retired `deepseek-chat` and `deepseek-reasoner` on
2026-07-24. Calls to those names no longer route anywhere. Use `deepseek-v4-flash` or
`deepseek-v4-pro`. Both `app/doctor.py` and `app/llm/client.py` refuse a retired name and say why.

## The architecture rule

`app/guardrails/sql_check.py` runs on the tool side of the MCP boundary. The agent never calls it.

The agent writes SQL. The MCP tool owns the database connection. The tool validates the SQL before
it executes anything. This order matters: a check inside the agent's own code path is skipped by
any input that redirects the agent, so such a check is a suggestion and not a control.

The full reasoning is in `brain/decisions/2026-08-05-sql-guardrails-live-behind-the-mcp-boundary.md`.

## What the guardrail refuses

| Rule | Reason |
|---|---|
| Anything except one `SELECT` | A write reaches the database only through a migration |
| A table absent from the allowlist | A new table is denied by default, not allowed by oversight |
| A column absent from the allowlist | Column-level control, not table-level |
| `SELECT *` | The caller must name the columns it needs |
| A missing or oversized `LIMIT` | One question cannot return the whole table |

## Layout

```
app\
  doctor.py          preflight check, standard library only
  llm\client.py      one factory for DeepSeek and Ollama
  guardrails\        SQL validation, called by the tool, never by the agent
```

## Cost

`deepseek-v4-flash` costs $0.14 per million input tokens on a cache miss. A cache hit costs
$0.0028 per million, which is a 98% discount.

The schema prompt is identical on every call. Put the schema at the front of the prompt and never
reorder it, so every call after the first is a cache hit.

## Related notes

- `brain/projects/credit-risk-copilot.md` - status, open questions, and the log
- `brain/decisions/2026-08-05-sql-guardrails-live-behind-the-mcp-boundary.md`
- `brain/decisions/2026-08-05-python-for-credit-risk-copilot.md`