Klean - AI-Powered Financial Dashboard Analyzer

Klean is a web service that uses Vision Language Models (VLM) to automatically evaluate the quality of financial dashboards and reports. Upload a screenshot and receive expert recommendations on readability, visual hierarchy, and UX improvements.

Features

MVP (Phase 1) - Current Implementation

• Dashboard Analysis: Upload financial dashboard screenshots for AI-powered evaluation
• VLM Integration: Leverages GLM-4.5V / Qwen2.5-VL-72B via SiliconFlow API
• Comprehensive Scoring: Evaluates 6 key criteria with weighted scoring:
  • Visual Hierarchy (25%)
  • Readability (20%)
  • Chart Selection (20%)
  • Data Context (15%)
  • Color Scheme (10%)
  • Cognitive Load (10%)
• Actionable Recommendations: Prioritized, specific suggestions with expected impact
• User Authentication: JWT-based auth with user management
• Image Storage: S3-compatible storage (MinIO for local dev, AWS S3 for production)
• RESTful API: FastAPI backend with automatic OpenAPI documentation

Tech Stack

Backend

• Framework: FastAPI (Python 3.11+)
• Database: PostgreSQL 15+ with SQLAlchemy 2.0 (async)
• Authentication: JWT with passlib + bcrypt
• Image Processing: Pillow, OpenCV
• VLM API: SiliconFlow (GLM-4.5V, Qwen2.5-VL)
• Storage: S3 (AWS) / MinIO (local)
• Migrations: Alembic

Infrastructure

• Containerization: Docker + Docker Compose
• Cache/Queue: Redis (for future Celery integration)
• Development: Python virtual environments, uv package manager

Project Structure

klean/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   ├── v1/
│   │   │   │   ├── endpoints/
│   │   │   │   │   ├── auth.py          # Authentication endpoints
│   │   │   │   │   └── analysis.py      # Analysis endpoints
│   │   │   │   └── router.py
│   │   │   └── deps.py                  # API dependencies
│   │   ├── core/
│   │   │   ├── config.py                # Settings management
│   │   │   └── security.py              # JWT & password hashing
│   │   ├── db/
│   │   │   ├── base.py                  # Base models & mixins
│   │   │   └── session.py               # Database session
│   │   ├── models/
│   │   │   ├── user.py                  # User model
│   │   │   ├── analysis.py              # Analysis model
│   │   │   ├── training_example.py      # Training data model
│   │   │   └── feedback.py              # User feedback model
│   │   ├── schemas/
│   │   │   ├── user.py                  # User schemas
│   │   │   └── analysis.py              # Analysis schemas
│   │   ├── services/
│   │   │   ├── storage_service.py       # S3 image handling
│   │   │   ├── vlm_service.py           # VLM API integration
│   │   │   └── analysis_service.py      # Analysis orchestration
│   │   └── main.py                      # FastAPI app entry point
│   ├── alembic/                         # Database migrations
│   ├── tests/                           # Test suite
│   ├── pyproject.toml                   # Dependencies
│   ├── Dockerfile
│   └── .env.example
├── frontend/                            # React frontend (TBD)
├── admin/                               # Admin panel (TBD)
├── docker-compose.yml
└── README.md

Quick Start

Prerequisites

• Python 3.11+
• Docker & Docker Compose
• SiliconFlow API Key (get from siliconflow.cn)

1. Clone and Setup

cd /path/to/klean

2. Start Infrastructure (PostgreSQL, Redis, MinIO)

docker-compose up -d postgres redis minio minio-init

This starts:

• PostgreSQL on port 5432
• Redis on port 6379
• MinIO on ports 9000 (API) and 9001 (Console)

3. Configure Backend

cd backend
cp .env.example .env

Edit .env and set:

# Required
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-here
SILICONFLOW_API_KEY=your-siliconflow-api-key

# MinIO (for local dev)
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT_URL=http://localhost:9000
S3_BUCKET_NAME=klean-uploads

4. Install Dependencies

# Using uv (recommended)
pip install uv
uv pip install -e .

# Or using pip
pip install -e .

5. Run Migrations

alembic upgrade head

6. Start Backend

uvicorn app.main:app --reload --port 8000

API will be available at:

• API: http://localhost:8000
• Docs: http://localhost:8000/docs
• Health: http://localhost:8000/health

7. Test the API

Register a User

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "yourpassword",
    "full_name": "Test User"
  }'

Login

curl -X POST "http://localhost:8000/api/v1/auth/login?email=user@example.com&password=yourpassword"

Copy the access_token from the response.

Upload Dashboard for Analysis

curl -X POST http://localhost:8000/api/v1/analysis/analyze \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "image=@/path/to/dashboard.png" \
  -F "dashboard_type=revenue" \
  -F "target_audience=executive"

Get Analysis Results

curl http://localhost:8000/api/v1/analysis/analyze/{analysis_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

API Endpoints

Authentication

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - Login user
• GET /api/v1/auth/me - Get current user

Analysis

• POST /api/v1/analysis/analyze - Create analysis
  • Body: multipart/form-data
    • image: file (PNG, JPEG, PDF)
    • dashboard_type: optional (revenue, p&l, cash_flow, budget, custom)
    • context: optional string
    • target_audience: optional (executive, analyst, stakeholder)
• GET /api/v1/analysis/analyze/{id} - Get analysis by ID
• GET /api/v1/analysis/analyses?page=1&limit=20 - List user's analyses

Analysis Response Schema

{
  "analysis_id": "uuid",
  "status": "completed",
  "image_url": "https://...",
  "thumbnail_url": "https://...",
  "results": {
    "overall_score": 72,
    "category_scores": {
      "visual_hierarchy": 85,
      "readability": 65,
      "chart_selection": 70,
      "data_context": 60,
      "color_scheme": 90,
      "cognitive_load": 75
    },
    "recommendations": [
      {
        "priority": "high",
        "category": "visual_hierarchy",
        "issue": "Key KPIs not prominent",
        "suggestion": "Place Total Revenue and Net Profit at top with 24-30px font",
        "reasoning": "Users need to understand key metrics within 3 seconds",
        "impact": "Improves data comprehension by 40%"
      }
    ],
    "overall_assessment": "Dashboard has strong visual design but lacks clear hierarchy..."
  },
  "processing_time_ms": 2340,
  "model_version": "Pro/Qwen/Qwen2-VL-72B-Instruct"
}

Development

Run Tests

cd backend
pytest
pytest --cov=app tests/

Code Quality

# Linting
ruff check .

# Formatting
ruff format .

# Type checking
mypy .

Database Migrations

# Create new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1

Access MinIO Console

Open http://localhost:9001

• Username: minioadmin
• Password: minioadmin

Roadmap

Phase 2: Enhanced Training (Planned)

• Admin panel for training data management
• Fine-tuning workflow for custom models
• MLflow experiment tracking
• A/B testing for model versions

Phase 3: Advanced Features (Planned)

• Vector database for similarity search
• React frontend with beautiful UI
• Export recommendations to PDF/Figma
• Before/after comparison
• Team workspaces
• Subscription plans

Phase 4: Scale & Monetization (Future)

• Multi-language support
• Industry-specific models
• BI tool integrations (Tableau, Power BI)
• Mobile app

Environment Variables

See .env.example for all available configuration options.

Required Variables

• SECRET_KEY - App secret key
• JWT_SECRET_KEY - JWT signing key
• DATABASE_URL - PostgreSQL connection string
• SILICONFLOW_API_KEY - VLM API key

Storage Configuration

For local development (MinIO):

S3_ENDPOINT_URL=http://localhost:9000
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
S3_BUCKET_NAME=klean-uploads

For production (AWS S3):

S3_ENDPOINT_URL=  # Leave empty for AWS
AWS_ACCESS_KEY_ID=your-aws-key
AWS_SECRET_ACCESS_KEY=your-aws-secret
AWS_REGION=us-east-1
S3_BUCKET_NAME=your-bucket-name

Troubleshooting

Database connection errors

# Check PostgreSQL is running
docker-compose ps postgres

# Check logs
docker-compose logs postgres

MinIO bucket not found

# Re-run bucket initialization
docker-compose up minio-init

VLM API errors

• Verify SILICONFLOW_API_KEY is set correctly
• Check API quota at siliconflow.cn
• Try fallback model in VLM_MODEL setting

Contributing

This project follows standard FastAPI best practices:

• Type hints everywhere
• Pydantic for validation
• Async/await for I/O operations
• Repository pattern (coming in Phase 2)

License

[To be determined]

Contact

For questions or feedback, please open an issue on GitHub.

---

Built with FastAPI, PostgreSQL, and Vision AI