Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
ZINC-Fusion-V15 is an institutional-grade quantitative forecasting system designed for soybean oil procurement. The project follows a dual-stack architecture consisting of a Python-based machine learning pipeline at the root and a Next.js frontend application within the frontend/ directory.
The installation process involves configuring a cloud-hosted Prisma Postgres database, setting up a Python 3.11+ environment using the uv package manager, and initializing the Next.js dashboard. System integrity is maintained through a preflight validation script that verifies database connectivity, environment variables, and essential dependencies.
Sources: README.md:1-15, AGENTS.md:10-25
Prerequisites & Environment Boundaries
The repository is logically divided into two distinct environments. The root directory manages the ML pipeline, while the frontend/ directory contains the dashboard. Note that there is intentionally no package.json in the root; Prisma CLI dependencies are managed within config/package.json.
| Requirement | Specification |
|---|---|
| Python Version | 3.11 - 3.14 (3.11 recommended) |
| Node.js Version | 22.x |
| Package Managers | uv (Python), npm (Frontend/Prisma) |
| Database | Prisma Postgres (Cloud-hosted) |
Sources: README.md:165-170, frontend/package.json:6-10, CLAUDE.md:15-20
Environment Variables
A .env file must be created at the root to store sensitive credentials. The following variables are mandatory for system operation:
DATABASE_URL: Connection string for the Prisma Postgres instance.FRED_API_KEY: API key for accessing Federal Reserve Economic Data.ANTHROPIC_API_KEY: Required for AI-powered intelligence modules.
Sources: README.md:210-220, scripts/preflight_check.py:80-90
Core Installation Steps
The setup process requires cloning the repository and installing dependencies for both the backend and frontend stacks.
1. Python Environment Setup
It is recommended to use the uv package manager for fast, reliable dependency resolution.
# Clone the repository
git clone https://github.com/zincdigitalofmiami/ZINC-Fusion-V15.git
cd ZINC-Fusion-V15
# Install uv if necessary
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install core and dev dependencies
uv pip install -e ".[dev]"
Sources: README.md:172-185
2. Frontend & Database Initialization
Prisma handles schema management and migrations, while the Next.js app provides the user interface.
# Setup database schema
npx prisma db pull
npx prisma generate
# Install frontend dependencies
cd frontend
npm install
Sources: README.md:190-200, CLAUDE.md:25-30
Architecture & Data Flow
The following diagram illustrates the installation and runtime relationship between the ML pipeline, the database, and the frontend dashboard.
The diagram shows how both the Python ML pipeline and the Next.js frontend share the authoritative Prisma Postgres database via environment variable configurations. Sources: AGENTS.md:15-30, README.md:202-208
Preflight Verification
Before initiating model training or starting the API, the scripts/preflight_check.py utility must be executed to ensure the environment is correctly configured. This script performs structural checks, environment variable validation, and database connectivity tests.
Validation Categories
The script organizes its checks into several critical modules:
- Project Structure: Verifies existence of
AGENTS.md,prisma/schema.prisma, and core source directories. - Environment: Checks for the
.envfile and required keys likeDATABASE_URL. - Python Imports: Validates that critical libraries (e.g.,
psycopg2,pandas,autogluon) are resolvable. - Database Connectivity: Attempts a live connection to the Postgres instance and counts tables in schemas like
mktandtraining.
# Run all verification checks
python3 scripts/preflight_check.py --all
Sources: scripts/preflight_check.py:15-150
Model Training & API Deployment
Once setup is verified, the system is ready for operation. The ML stack utilizes 19 models organized into hierarchical layers (L0 Core, L0 Specialists, L1 Meta).
Starting the API
The backend utilizes FastAPI and Uvicorn for serving forecasts.
python -m uvicorn fusion.api.server:app --host 0.0.0.0 --port 8000
Sources: README.md:187-189
Initiating Training
Core training involves AutoGluon TimeSeriesPredictors for four specific horizons (5d, 21d, 63d, 126d).
python -m fusion.core_training.run_pipeline --skip-matrix --horizons 5
Sources: README.md:240-245
Summary
Installation of ZINC-Fusion-V15 requires a carefully synchronized setup of Python and Node.js environments. By utilizing uv for the ML pipeline and npx prisma for database management, developers can ensure a consistent foundation for the system's 19-model ensemble. The inclusion of the preflight_check.py script provides a mandatory gate to prevent configuration errors from propagating into the forecasting engine.