API Platform

Typed Python monorepo for ML training, NLP, media services, and quant-ML risk modeling. Strict mypy (no Any, no cast, no type: ignore), 100% statement + branch test coverage, FastAPI + RQ + Redis + Kafka architecture.

Start here

Doing research, auditing an experiment, or reproducing a number? Read docs/RESEARCH.md first. It is the index of every body of work on this machine that produces numbers someone compares — including the two that live outside this repository — and says for each one what provenance it carries and what it does not.

The three parts of this repo worth reading first:

1. libs/cleargbm/ + libs/cleargbm_rs/ — From-scratch interpretable gradient boosting: numpy Python orchestration with a Rust core (histogram building, tree construction, prediction pipeline) exposed via PyO3 bindings.
2. services/covenant-radar-api/ + libs/covenant_ml/ + libs/covenant_nn/ — Multi-model risk prediction: pluggable ML backends (XGBoost, LightGBM, ClearGBM, LogReg, RF) and PyTorch NN backends (MLP, LSTM), Optuna optimization, Kafka streaming.
3. libs/monorepo_guards/ — Custom static-analysis framework: architecture-enforcement rules (Python + Rust) that lint invariants CI-time.

The smaller services (grandma-api, github-stats-api, procart-api) are side projects.

Services

Clients

Shared Libraries

Quick Start

# Start shared infrastructure (Redis + PostgreSQL + Kafka + Traefik)
make infra

# Start a specific service
make up-databank      # data-bank-api
make up-trainer       # Model-Trainer (GPU)
make up-art-trainer   # Art-Trainer (GPU)
make up-handwriting   # handwriting-ai
make up-qr            # qr-api
make up-transcript    # transcript-api
make up-turkic        # turkic-api
make up-music         # music-wrapped-api
make up-covenant      # covenant-radar-api
make up-grandma       # grandma-api
make up-github-stats  # github-stats-api
make up-opportunity   # opportunity-radar-api
make up-discord       # DiscordBot

# Start all services
make up-all

# Stop everything
make down

# Stop all services and prune Docker volumes
make clean

# Run checks across all libs/services
make check
make lint
make test

# View running containers
make status

# Stream logs
make logs

Architecture

                              +--------------+
                              | Traefik (80) |
                              +------+-------+
                                     |
                         +-----------+-----------+
                         |                       |
                   +-----v-----+           +-----v-----+
                   | Discord   |           |  Services |
                   |   Bot     |           | (FastAPI) |
                   +-----+-----+           +-----+-----+
                         |                       |
           +-------------+-------------+---------+
           |             |             |
     +-----v-----+ +-----v-----+ +-----v-----+
     |   Redis   | | PostgreSQL| | data-bank |
     | (pub/sub) | | (covenant)| | (storage) |
     +-----+-----+ +-----------+ +-----------+
           |
     +-----v-----+
     | RQ Workers|
     +-----------+

All services share:

• platform-network (Docker bridge)
• platform-redis (job queue + pub/sub for async services)
• platform-postgres (covenant-radar persistence)
• Structured JSON logging
• Health endpoints (/healthz, /readyz)

Infrastructure

Development

# Install dependencies for a service
cd services/Model-Trainer
poetry install --with dev

# Run checks
make check

# Run just lint or test
make lint
make test

See docs/ for detailed documentation.

Code Standards

• Type Safety: mypy strict mode, zero Any types, zero cast, zero type: ignore
• Test Coverage: 100% statement + branch coverage enforced
• Linting: Ruff formatting and linting
• Architecture: Protocol-based dependency injection, _test_hooks.py pattern

Requirements

• Python 3.11+
• Docker + Docker Compose
• Poetry
• Make (via PowerShell on Windows)
• NVIDIA GPU + CUDA 12.4 (for Model-Trainer, Art-Trainer)

License

MIT