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.

Related MCP server: Claims Data MCP Server

Requirements

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.

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

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