FairScore
AI-Powered Credit Scoring System with Bloomberg Terminal-Style TUI
FairScore is a fair, explainable, and inclusive credit scoring system that uses behavioral financial data instead of traditional credit bureau metrics. It features a Terminal User Interface (TUI) inspired by Bloomberg Terminal aesthetics.
Features
- 4 Specialized ML Models: Income Stability (LightGBM), Expense Discipline (Random Forest), Liquidity Buffer (Logistic Regression), Risk Detection (Isolation Forest)
- FAIR-SCORE Formula: Weighted ensemble producing 300-900 score range
- Explainability: SHAP-based explanations with waterfall visualizations
- Dual Input Modes: PDF parsing (Gemini AI) or manual data entry
- Bloomberg Terminal UI: Phosphor green on matte black aesthetic
Installation
# Clone or download, then:
pip install -e .
Quick Start
# Launch TUI
fairscore
# Train models (generates synthetic data first)
python -m fairscore.models.trainer
# Generate synthetic data only
python -c "from fairscore.data import DataGenerator; DataGenerator().generate_all()"
Keyboard Shortcuts
| Key | Action |
|---|---|
| F1 | Help screen |
| F5 | Refresh display |
| Ctrl+O | Upload PDF |
| Ctrl+M | Manual entry |
| Tab | Navigate fields |
| Q | Quit |
Score Categories
| Range | Category | Description |
|---|---|---|
| 750-900 | EXCELLENT | Best creditworthiness |
| 650-749 | GOOD | Above average |
| 500-649 | FAIR | Average |
| 300-499 | POOR | Below average |
Project Structure
fairscore/
__init__.py # Package initialization
app.py # Main TUI application
cli.py # CLI entry points
config.py # Configuration management
theme.py # Bloomberg Terminal theme
data/
generator.py # Synthetic data generation
features.py # Feature engineering
models/
income_stability.py # LightGBM model
expense_discipline.py # Random Forest model
liquidity_buffer.py # Logistic Regression model
risk_anomaly.py # Isolation Forest model
ensemble.py # FAIR-SCORE computation
trainer.py # Training pipeline
explainability/
shap_explainer.py # SHAP explanations
parser/
pdf_parser.py # Gemini AI PDF parsing
ui/
dashboard.py # Main dashboard
model_matrix.py # 4-panel model display
score_gauge.py # ASCII score gauge
input_mode.py # Input selection/forms
Configuration
Set environment variable for PDF parsing:
set GOOGLE_API_KEY=your_gemini_api_key
License
MIT License
Metadata
Release files for fairscore-ai 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fairscore_ai-1.0.0.tar.gz | 1.9 MB | Without provenance | Details for fairscore_ai-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fairscore_ai-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for fairscore_ai-1.0.0-py3-none-any.whl |
Total release size: 5.7 MB
Release files / fairscore_ai-1.0.0.tar.gz
| Download URL | fairscore_ai-1.0.0.tar.gz |
|---|---|
| Size | 1.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d54b310e0c138fcb2b731dd048242b9bb9b90f43cc9def4c07bcb03f62cde25d
|
|
BLAKE2b-256 checksum How to use checksums |
0a93bf34afd58b6c5222c387478feb92cfdb4f933c887180a34bec60dfe784c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Release files / fairscore_ai-1.0.0-py3-none-any.whl
| Download URL | fairscore_ai-1.0.0-py3-none-any.whl |
|---|---|
| Size | 3.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b2bb769b653a6b1ed622593af41f6f907418e9c9235ef698ce2deea1af8ba5b8
|
|
BLAKE2b-256 checksum How to use checksums |
716c5273938dca850a7e8f6ec35061ecf3bc2d80b387417389a212b9c69af7a2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Security for fairscore-ai 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.