skaner

RAG tool for "talking with" mortgage offers from different banks.

Features

• Document upload via HTTP
• Processing using llama-index
• Vector database storage
• AI-powered querying via pydantic-ai
• Find best suited offers for customers
• Help prepare mortgage paperwork

Requirements

• Python 3.14+
• uv
• just (optional, recommended task runner)
• PostgreSQL (for task status storage)
• Redis (for task queue)

Installing Just

Just is a command runner that simplifies running project tasks. Install it via:

# macOS (Homebrew)
brew install just

# macOS (MacPorts)
port install just

# Linux (most distros)
# Download from https://github.com/casey/just/releases

# Or via cargo
cargo install just

For other installation methods, see the official documentation.

Setup

Quick Setup with Just

# Complete development setup (install deps + start services + create test db)
just setup

# Or step by step
just install        # Install dependencies
just services-up    # Start PostgreSQL and Redis
just test-setup     # Create test database

Manual Setup

# Install dependencies
uv sync --group dev

Running

The application consists of two components: the FastAPI server and an arq background worker.

Prerequisites

The application requires PostgreSQL and Redis:

• PostgreSQL: Task status storage
• Redis: Background task queue (arq)

Using Docker Compose (Recommended)

With Just:

# Start all services
just services-up

# View logs
just logs-postgres  # PostgreSQL only
just logs-redis     # Redis only
just logs          # All services

# Stop all services
just services-down

Without Just:

# Start all services (PostgreSQL + Redis)
docker compose up -d

# View logs
docker compose logs -f postgres
docker compose logs -f redis

# Stop all services
docker compose down

Services will be available at:

• PostgreSQL: localhost:5432 (database: skaner, user: skaner, password: skaner)
• Redis: localhost:6379

Alternative: Local Installation

Alternatively, install PostgreSQL and Redis locally:

• PostgreSQL installation guide
• Redis installation guide

Configure connection settings via environment variables (see Configuration section).

Start the API server

With Just:

just server

Without Just:

uv run fastapi run skaner/main.py

The API will be available at http://127.0.0.1:8000. Interactive docs at /docs.

Start the background worker

In a separate terminal:

With Just:

just worker

Without Just:

uv run arq skaner.worker.WorkerSettings --watch /dev/null

The worker processes document uploads asynchronously via Redis queue.

Note: The --watch /dev/null flag is required for Python 3.14+ due to changes in asyncio event loop handling. It wraps execution in asyncio.run() which properly establishes the event loop.

Configuration

The application can be configured via environment variables or a .env file:

# Application
APP_NAME=skaner
DEBUG=false
STORAGE_PATH=./data/documents
MAX_UPLOAD_SIZE_MB=50

# Redis (task queue)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# PostgreSQL (task status)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=skaner
POSTGRES_USER=skaner
POSTGRES_PASSWORD=skaner
POSTGRES_POOL_SIZE=5
POSTGRES_MAX_OVERFLOW=10

Development

With Just

# View all available commands
just

# Code quality
just format      # Format code
just lint        # Lint code
just fix         # Lint and auto-fix issues
just typecheck   # Type check
just check       # Run all checks (format + lint + typecheck)

# Testing
just test        # Run tests
just test-cov    # Run tests with coverage
just test-setup  # Create test database (first-time only)

# Utilities
just clean       # Clean up generated files

Without Just

# Format code
uv run ruff format

# Lint
uv run ruff check
uv run ruff check --fix  # auto-fix

# Type check
uv run ty check

# Run tests (requires PostgreSQL)
# First-time setup: create test database
./scripts/create_test_db.sh

# Run tests
uv run pytest tests -v