AEVIX Studio

AEVIX Studio is a self-hosted, full-stack platform for running the whole model-lifecycle workflow of a small in-house model team from one place: bring in and merge datasets, train a tokenizer, design and pretrain a transformer from scratch (or fine-tune/LoRA/QLoRA an existing one), benchmark it, compare it against previous generations, and prepare it for export/deployment.

It's a FastAPI + SQLAlchemy backend and a React + TypeScript + Vite frontend, built to run real work locally (real tokenizer training, real Hugging Face fine-tuning when the optional ML stack is installed, real benchmark execution) rather than mock/demo the workflow.

For a full guided tour of every feature, how the pieces connect, and where to look when extending something, see docs/STUDIO_GUIDE.md. For production configuration, migrations, sandboxing, serving, promotion, remote-worker operation, cloud/GPU deployment, and multi-GPU training, see docs/OPERATIONS.md. Have zero budget and a GPU-hungry model to train? docs/CLOUD_GPU_FREE_TIER.md runs the real backend on a free Kaggle/Colab GPU, tunneled to your frontend. This README covers setup and a quick orientation only.

Monorepo layout

studio1/
├── backend/           FastAPI service (clean-architecture layout)
│   ├── app/
│   │   ├── api/v1/routers/    one file per feature area (24 routers)
│   │   ├── domain/            business logic, entities, trainers, analysis
│   │   ├── infrastructure/    DB session/bootstrap, storage, security
│   │   ├── workers/           background job orchestrator + scheduler
│   │   └── core/              settings, logging, error_log
│   ├── requirements.txt       core deps (always installed)
│   ├── requirements-ml.txt    optional heavy ML stack (torch/transformers/...)
│   └── data/                  uploads, tokenizers, checkpoints, logs (gitignored)
├── frontend/           React + TypeScript + Vite UI
│   └── src/
│       ├── pages/             one page per feature area (19 pages)
│       ├── services/api.ts    typed API client, one function per endpoint
│       ├── components/        shared UI (shell/nav, charts, state helpers)
│       └── hooks/useResource.ts   shared data-fetching hook
├── shared/contracts/   cross-cutting API/domain contracts
├── tests/backend/      pytest suite (one file per feature area)
├── docker/             backend/frontend Dockerfiles + compose
├── docs/               STUDIO_GUIDE.md (detailed) + architecture notes
└── scripts/            developer automation scripts

Quick start

Backend

cd backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

The API is now at http://localhost:8000, docs at http://localhost:8000/docs. On first startup it creates backend/aevix.db (SQLite) and a bootstrap admin user — see Default credentials below.

Real training/fine-tuning needs the optional ML stack:

pip install -r requirements-ml.txt

Without it, the app still runs fully — dataset tools, tokenizer training, the architecture designer, dashboards, and the dependency-free simulated trainer all work. Real Hugging Face training methods (finetune, pretrain, pretrain_scratch, lora, qlora) will fail with a clear, actionable error (not a stack trace) telling you to install requirements-ml.txt, and that failure is recorded in the Error Log so you can see it without watching the terminal.

Frontend

cd frontend
npm ci
npm run dev

UI is now at http://localhost:5173.

Full stack with Docker

docker compose up --build

Backend: http://localhost:8000 · Frontend: http://localhost:5173

Running tests

cd backend
pip install -r requirements.txt pytest httpx
python -m pytest ../tests/backend -q

Each test run uses its own throwaway SQLite database (see tests/backend/conftest.py) — it never touches backend/aevix.db, so running the suite is safe to do repeatedly and won't collide with data from local development or a previous run.

Error Log — where failures go

Every unhandled request failure, training-job crash, dataset-download failure, and dependency-install failure is:

1. Logged through the normal logging module (console + backend/data/logs/app.log, with warnings/errors also mirrored to backend/data/logs/errors.log), and
2. Persisted to the error_logs table with a full traceback and structured context (job id, request path, etc.), browsable at Error Log in the sidebar or via GET /api/v1/errors.

See backend/app/core/error_log.py (the writer) and backend/app/api/v1/routers/errors.py (the reader) — and docs/STUDIO_GUIDE.md for the full design rationale.

Default credentials (change these!)

The bootstrap admin account is admin / admin12345 (backend/app/core/config.py), and the frontend logs in as this user automatically in development. This is fine for a single trusted local machine; it is not safe to expose beyond that without setting real credentials (AEVIX_BOOTSTRAP_ADMIN_USERNAME / AEVIX_BOOTSTRAP_ADMIN_PASSWORD env vars) and reviewing the other known hardening gaps listed in docs/STUDIO_GUIDE.md.

Known gaps

This is an actively developed internal tool, not a hardened multi-tenant product. The current known gaps (auth on the OpenAI-compatible inference API, SSRF protection on dataset downloads, sandboxing for benchmark code execution, and others) are tracked with the reasoning behind each in docs/STUDIO_GUIDE.md.