CreditAI

Deterministic credit decisioning. AI only writes the narrative.

On-prem pipeline with versioned scoring, F1–F5 compliance gates, CRC/CIRBE, immutable audit, and grounded local-LLM explanations — never an LLM score.

AI-driven credit decision platform with layered architecture, immutable audit trail, and F1–F5 regulatory compliance.

Key Features

Automated Pipeline — 5–15 second decisions with 11 parallel integrations
6 AI Agents — Specialized collection and normalization (Behavioral, Financial, Income, etc.)
ML Scoring — Segment-based models (Consumer/SME/Corporate) with SHAP explainability
OCR + AI Parsing — Document upload → automated data extraction (Tesseract + OpenAI-compatible LLM)
Robust Manual Entry — Fallback when APIs fail + dynamic UI forms
F1–F5 Compliance — Regulatory gates + mandatory human review
Immutable Audit Log — SHA-256 hash chain, complete traceability
Iberian Expansion — Support for Portugal (CRC) and Spain (CIRBE)
Early Warning System — Automated post-disbursement monitoring
Model Risk Management — Registry, backtesting, drift monitoring (PSI)
On-Premise LLM — OpenAI-compatible /v1 or ContextMemory; local OCR (Tesseract)
Multi-tenant — PostgreSQL RLS + EF Core tenant filter

Documentation

Complete Architecture — System overview, components and tech stack
Detailed Pipeline — Complete phase-by-phase flow
Visual Diagram (Mermaid) — Visual pipeline flow
Integrations — Data provider configuration (CRC, CIRBE, APIs)
Document Processing (OCR + AI) — Upload and automated data extraction
License & support — AGPL-3.0 terms and contribution pointers
Contributing — Local setup and PR guidelines

Quick Start

Requirements

.NET SDK 9.0
PostgreSQL 9.0+ (or Docker Desktop)
OpenAI-compatible LLM (optional, for AI narratives) or ContextMemory gateway
Tesseract OCR (optional, for document processing)

Local Startup

Prepare environment variables:
```
cp .env.example .env
```

Start PostgreSQL:

docker compose up -d
docker compose ps  # Validate status

Optional ContextMemory gateway (GHCR):

docker compose -f docker-compose.yml -f docker-compose.contextmemory.yml up -d
# then set CONTEXT_MEMORY_API_KEY in .env (see .env.example)

Run applications (two terminals):

Terminal 1 - API:

cd src/CreditAI.API
dotnet run
# → https://localhost:7257
# → Docs: https://localhost:7257/redoc

Terminal 2 - Web:

cd src/CreditAI.Web
dotnet run
# → http://localhost:5188

Initial login:
- URL: http://localhost:5188
- Email: admin@creditai.local
- Password: ChangeMe@1234

Migrations are applied automatically on startup.

🔧 Configuration

Connection String (PostgreSQL)

Default (development):

Host=localhost;Port=5432;Database=creditai;Username=creditai;Password=CHANGE_ME;

Customize via environment variable:

export ConnectionStrings__CreditAiDatabase="Host=localhost;..."

LLM — OpenAI-compatible ou ContextMemory

Por defeito a narrativa e o parsing usam qualquer endpoint OpenAI-compatible (POST /v1/chat/completions) via Llm:* / LLM_* (qualquer host OpenAI-compatible via Llm:BaseUrl).

"Llm": {
  "Enabled": true,
  "BaseUrl": "http://localhost:8000",
  "Model": "qwen3.5:9b"
}

BaseUrl é o host sem /v1 (o cliente acrescenta v1/chat/completions).

Para passar pelo gateway ContextMemory:

"ContextMemory": {
  "BaseUrl": "http://localhost:5100",
  "AppId": "creditai",
  "ApiKey": "cm_creditai_local_key"
}

Com ContextMemory BaseUrl + ApiKey: gateway.
Sem ApiKey: LLM directo OpenAI-compatible (Llm:Enabled / LLM_BASE_URL).
Self-host CM: repositório acima, ou docker-compose.contextmemory.yml neste repo.

Integrations (Stub vs Production)

By default, all integrations are in Stub mode (development):

Integrations__Crc__Mode=Stub
Integrations__Yapily__Mode=Stub
Integrations__Citius__Mode=Manual  # Manual entry only
# ... etc

To enable real integrations, see docs/integrations.md.

🏗️ High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│  CREDIT DECISION PIPELINE (5-15 seconds)                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. INTAKE → Validation and request creation                │
│  2. REGULATORY → CRC (PT) or CIRBE (ES)                     │
│  3. EXTERNAL DATA → 11 parallel data providers              │
│  4. AI AGENTS → 6 agents normalize (50+ features)           │
│  5. ML SCORING → PD + Rating + SHAP values                  │
│  6. SOLVENCY RULES → Gates F1-F5 (compliance)               │
│  7. NARRATIVE AI → OpenAI-compatible /v1 (or ContextMemory) │
│  8. DECISION SNAPSHOT → Consolidation                       │
│  9. AUDIT LOG → Immutable hash chain                        │
│ 10. HUMAN REVIEW → Supervisor approves/rejects             │
│ 11. MONITORING → Early Warning System (continuous)          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Robust fallback: If any API fails → manual data entry (UI forms or document upload with OCR).

On-premise LLM: OpenAI-compatible /v1 or ContextMemory + Tesseract OCR. Zero cloud SaaS LLM by default.

See details in docs/ARCHITECTURE.md.

📄 Document Processing (OCR + AI) - NEW!

Upload PDFs/images → automated data extraction:

POST /api/documents/{requestId}/process
  - file: document.pdf
  - sourceKey: "Citius"  # or CRC, WorldCheck, etc.
  - segment: "Sme"

Flow:

OCR (Tesseract) → extracts text
AI Parsing (OpenAI-compatible LLM) → identifies fields
Validation → analyst reviews
Submission → integrates with manual entry

Supported formats: PDF, PNG, JPG, JPEG, TIFF, BMP (max 10 MB)

See complete guide in docs/document-processing.md.

📡 Main Endpoints

Health: GET /health
Decision: GET /api/credit-decisions/{requestId}
Request intake:
- POST /api/credit-requests
- GET /api/credit-requests
- GET /api/credit-requests/{requestId}
Human review:
- GET /api/human-review/queue
- POST /api/human-review/queue
- POST /api/human-review/decisions
- POST /api/human-review/decisions/batch
- GET /api/human-review/history
Audit:
- GET /api/audit-log
- GET /api/audit-log/export/csv
- GET /api/audit-log/export/json

Authentication and RBAC

Two modes supported via Authentication:Mode:

Mode	Use	API	Web
`Development`	Local without Entra (Identity, like KYC)	Signed Bearer token or `dev`	`/Identity/Account/Login`
`Entra`	Production (Microsoft Entra ID)	JWT Bearer	Cookie + OIDC

Development Mode (local)

Web: email/password login at /Identity/Account/Login (seed user: Auth:AdminEmail / Auth:AdminPassword, default admin@creditai.local / ChangeMe@1234)
API: Web propagates signed access_token after login; tests can use Authorization: Bearer dev
Roles: Analyst, Supervisor, Auditor, RiskValidator, AmlOfficer, Admin

Entra Mode (production)

Register two app registrations in Entra ID:
- API — expose scope access_as_user, app roles Analyst, Supervisor, Auditor
- Web (Blazor) — redirect URI https://{host}/signin-oidc, permission to API scope
Configure variables (API and Web):

Authentication__Mode=Entra
Authentication__Authority=https://login.microsoftonline.com/{tenant-id}/v2.0
Authentication__Audience=api://creditai
Authentication__ClientId={web-client-id}
Authentication__ClientSecret={web-client-secret}
Authentication__ApiScope=api://creditai/access_as_user

Assign app roles to users/groups in Entra ID.

RBAC Policies:

CreditRead: Analyst, Supervisor, Auditor
CreditWrite: Analyst, Supervisor
HumanReviewRead: Analyst, Supervisor, Auditor
HumanReviewWrite: Analyst, Supervisor
AuditRead: Auditor, Supervisor

Web Routes:

Login: /account/login
Logout: /account/logout

Web propagates the OIDC access_token to the API (Authorization: Bearer).

Useful Commands

Build: dotnet build CreditAI.sln
MRM Gate: dotnet run --project tools/CreditAI.MrmGate
Unit tests: dotnet test tests/CreditAI.UnitTests
Tests (fast, no Docker): dotnet test tests/CreditAI.IntegrationTests --filter "Category!=Postgres"
Architecture tests: dotnet test tests/CreditAI.ArchitectureTests
PostgreSQL tests (requires Docker): dotnet test tests/CreditAI.IntegrationTests --filter "Category=Postgres"
Stop local database: docker compose down
Stop and remove volume: docker compose down -v

Institutional Homologation

Complete documentation in docs/README.md.

# Generate evidence dossier (tests + MRM + API exports)
.\scripts\generate-homologation-evidence.ps1 -StartApp

# UI screenshots (Playwright) + docx
.\scripts\run-homologation-full.ps1

Document	Description
`docs/HOMOLOGATION_CHECKLIST.md`	F1–F5 regulatory checklist
`docs/E2E_HOMOLOGATION.md`	12 E2E scenarios + execution log
`docs/dossier/`	Evidence files (.trx, JSON, logs)
`docs/OPERATIONS_AND_HOMOLOGATION.md`	Deploy + runbooks

Compliance (F1–F5)

Phase	Status	Reference
F1 — Compliant core (GDPR, Art. 22, human review, CRC in pipeline)	100% logic	`docs/F1-completion-checklist.md`
F2 — Model Risk (registry, MRM gate, model cards, ONNX)	100% repo	`docs/F2-completion-checklist.md`
F3 — AML + solvency (sanctions, PEP/EDD, DSTI/LTI, FIU/goAML, CRC reporting)	100% repo	`docs/F3-completion-checklist.md`
F4 — Multi-segment + narrative (grounding, OpenAI-compatible LLM, open banking)	100% repo	`docs/F4-completion-checklist.md`
F5 — Competitive (EWI, watchlist, supervisor/CIRBE export, risk dashboard)	100% repo	`docs/F5-completion-checklist.md`

Documentation: docs/compliance/, docs/architecture/ADR-001-llm-scoring-separation.md.

Local MRM gate: dotnet run --project tools/CreditAI.MrmGate

CI

GitHub Actions

dotnet-tests.yml — build, MRM gate, unit/architecture/integration tests
release-please.yml — version bumps + release PRs from conventional commits
announce-release.yml — LinkedIn + dev.to on published releases

Current version: see version.txt.

Azure Pipelines

Pipeline is defined in azure-pipelines.yml (entry) and infra/azure-pipelines.yml (template).

Stages:

Build + MRM gate — validates ml/model_cards/*.md via CreditAI.MrmGate
Unit + architecture tests — promotion gate, LLM/scoring/CRC boundary
Integration tests — in-memory and stubs (no Docker)
PostgreSQL regulatory gates — Testcontainers validates append-only audit_log triggers

To connect in Azure DevOps: create pipeline pointing to azure-pipelines.yml in the repository root.

E2E Tests (Playwright)

Project: tests/CreditAI.E2ETests

Requirements: Docker (PostgreSQL via Testcontainers) + Playwright browsers.

dotnet build tests/CreditAI.E2ETests
pwsh tests/CreditAI.E2ETests/bin/Debug/net9.0/playwright.ps1 install chromium
dotnet test tests/CreditAI.E2ETests --filter "Category=E2E"

Covered scenarios:

Identity login (/Identity/Account/Login) and dashboard
Request submission with human review escalation
Approval in human review queue

Licensing

AGPL-3.0 for this open-source core (same as KYC / ContextMemory). Commercial / hosted offerings: kortexio.io. See docs/license-and-support.md.

Discoverability

GitHub topics (apply with pwsh ./scripts/set-github-topics.ps1 after gh auth login): credit-risk, credit-scoring, fintech, csharp, dotnet, blazor, postgresql, contextmemory, self-hosted, agpl, open-source, model-risk, open-banking, explainable-ai, crc.

Navigation Menu

Repository files navigation

CreditAI

Key Features

Documentation

Quick Start

Requirements

Local Startup

🔧 Configuration

Connection String (PostgreSQL)

LLM — OpenAI-compatible ou ContextMemory

Integrations (Stub vs Production)

🏗️ High-Level Architecture

📄 Document Processing (OCR + AI) - NEW!

📡 Main Endpoints

Authentication and RBAC

Development Mode (local)

Entra Mode (production)

Useful Commands

Institutional Homologation

Compliance (F1–F5)

CI

GitHub Actions

Azure Pipelines

E2E Tests (Playwright)

Licensing

Discoverability

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
artifacts/onnx		artifacts/onnx
docs		docs
infra		infra
ml		ml
scripts		scripts
src		src
tests		tests
tools		tools
.cursorrules		.cursorrules
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
CreditAI.sln		CreditAI.sln
LICENSE		LICENSE
NuGet.config		NuGet.config
README.md		README.md
azure-pipelines.yml		azure-pipelines.yml
create-test-request.ps1		create-test-request.ps1
docker-compose.contextmemory.yml		docker-compose.contextmemory.yml
docker-compose.yml		docker-compose.yml
llms.txt		llms.txt
payload-sample-duplicates.json		payload-sample-duplicates.json
version.txt		version.txt

Latest commit

History

Folders and files

Repository files navigation

CreditAI

Key Features

Documentation

Quick Start

Requirements

Local Startup

🔧 Configuration

Connection String (PostgreSQL)

LLM — OpenAI-compatible ou ContextMemory

Integrations (Stub vs Production)

🏗️ High-Level Architecture

📄 Document Processing (OCR + AI) - NEW!

📡 Main Endpoints

Authentication and RBAC

Development Mode (local)

Entra Mode (production)

Useful Commands

Institutional Homologation

Compliance (F1–F5)

CI

GitHub Actions

Azure Pipelines

E2E Tests (Playwright)

Licensing

Discoverability

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages