Credit Risk Copilot

A natural-language interface to a credit risk database. A user asks a question in English. Theservice 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 whichSQL 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 thatships compiled wheels can lag the interpreter by a year.

How to run it

Create the virtual environment:
```
py -3.12 -m venv .venv
```
Activate it:
```
.venv\Scripts\activate.bat
```
Use the .bat file. PowerShell blocks Activate.ps1 under the default execution policy.
Copy the example environment file:
```
copy .env.local.example .env.local
```
Open .env.local and set DEEPSEEK_API_KEY.
Run the preflight check:
```
py -3.12 -m app.doctor
```
The check imports only the standard library, so it runs before step 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 acommit, 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 on2026-07-24. Calls to those names no longer route anywhere. Use deepseek-v4-flash ordeepseek-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 beforeit executes anything. This order matters: a check inside the agent's own code path is skipped byany 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 neverreorder 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

Credit Risk Copilot