docs/COMMANDS.md

# 📋 Commands Guide: Animetix (SOTA 2026)

This guide lists all the commands needed to run, maintain, evaluate, test, and deploy the Animetix platform.

• For Python commands (Backend, Pipeline, MLOps, Scripts), ensure you are in the project root directory (Double_scenario_Project/) with your virtual environment active (.venv).
• For Node/Vite commands (Frontend), navigate to the frontend/ directory first (cd frontend).

---

🚀 1. Deployment & Infrastructure (Docker)

Manages the global production/staging infrastructure, including PostgreSQL (pgvector), Neo4j, Redis, and inference containers.

Command	Directory	Description
python scripts/verify/pre_flight_check.py	Root	(CRITICAL) Runs production check (Environment variables, database connections). Must be executed before any deployment.
docker-compose -f deploy/docker-compose.yml up -d --build	Root	Starts the entire infrastructure stack (Databases, Cache, Workers) in the background with image rebuild.
docker-compose -f deploy/docker-compose.yml stop	Root	Safely stops all containers without destroying persistent volumes.
docker-compose -f deploy/docker-compose.yml down	Root	Stops and removes containers and their associated networks.
docker-compose -f deploy/docker-compose.yml logs -f web	Root	Follows Django application logs in real-time.
docker-compose -f deploy/docker-compose.yml exec db psql -U postgres	Root	Opens an interactive PostgreSQL shell in the database container.

---

🌐 2. Django Backend (Headless API & Administration)

Commands to manage the headless API server, apply migrations, and seed the catalog databases.

Command	Directory	Description
cd backend/api && daphne animetix_project.asgi:application	backend/api	Launches the local ASGI development server with Django Channels (port 8000). Note: daphne does not auto-reload — restart it after backend edits.
python backend/api/manage.py makemigrations	Root	Prepares new migration files following database model changes.
python backend/api/manage.py migrate	Root	Applies migrations to PostgreSQL (including creating HNSW vector indexes).
python backend/api/manage.py createsuperuser	Root	Creates a superuser account for the Django Admin dashboard (/admin).
python backend/api/manage.py seed_achievements	Root	Populates the database with default game achievements and challenge milestones.
python backend/api/manage.py sync_catalog	Root	Synchronizes media catalogs, importing metadata from external APIs (TMDB, IGDB).
python backend/api/manage.py show_urls	Root	Lists all exposed API routes (requires django-extensions).
python backend/api/manage.py shell	Root	Launches an interactive Python shell with the Django context loaded.
python backend/api/manage.py export_rlhf_data	Root	Exports RLHF data for model fine-tuning.
python backend/api/manage.py restore_brain_service	Root	Restores the brain service from a backup.
python backend/api/manage.py run_red_teaming	Root	Executes red teaming exercises against the AI models.
python backend/api/manage.py run_scheduled_task	Root	Manually triggers a specific scheduled background task.
python backend/api/manage.py run_scheduled_task manga-updates-check	Root	Checks favorited mangas for new chapters (via Suwayomi) and pushes WebSocket notifications. In prod this runs every 6 h via the animetix-manga-updates Cloud Run Job + Scheduler (see scripts/deploy/deploy_jobs.py).
python backend/api/manage.py sync_bigquery_recommendations	Root	Synchronizes recommendations with BigQuery.
python backend/api/manage.py check	Root	Checks the entire Django project for potential problems.
python backend/api/manage.py dumpdata	Root	Dumps database contents to a fixture file (e.g., JSON).
python backend/api/manage.py loaddata	Root	Loads data from a fixture file into the database.
python backend/api/manage.py test	Root	Runs all tests for the installed applications.
python backend/api/manage.py spectacular --file schema.yaml	Root	Generates the OpenAPI schema (YAML) for the API.
python scripts/sync_api.py	Root	One-shot cross-platform sync: exports the OpenAPI schema then regenerates the frontend api.d.ts typings (replaces the old sync-api.bat).
python backend/api/manage.py compilemessages	Root	Compiles .po files into .mo files for internationalization.

---

💻 3. React SPA Frontend (Vite, TypeScript & Storybook)

Commands for the development cycle of the React 19 SPA client application.

All commands below must be executed from within the frontend directory: cd frontend

Command	Directory	Description
npm install	frontend/	Installs required Node.js packages and dependencies.
npm run dev	frontend/	Starts the local Vite development server (port 5173). Vite proxies /api and /ws to Django (port 8000).
npm run build	frontend/	Compiles the React application, generating the optimized production bundle under dist/.
npm run preview	frontend/	Runs a local server to preview the production bundle compiled by Vite.
npm run lint	frontend/	Lints the codebase using ESLint to check for style or accessibility violations.
npm run check-types	frontend/	Validates TypeScript types across the codebase without building (tsc --noEmit).
npm run generate:api	frontend/	Generates TypeScript API typings (src/types/api.d.ts) from the OpenAPI schema.yaml.
npm run storybook	frontend/	Starts Storybook in development mode (port 6006) to build and test isolated UI components.
npm run build-storybook	frontend/	Compiles Storybook into a static site under storybook-static/ for deployment.

---

🕸️ 4. Data Ingestion & Knowledge Graph (Sync & Graph)

ETL pipelines, multimodal indexing, and Neo4j graph synchronizations.

Command	Directory	Description
python backend/pipeline/neo4j_sync.py	Root	Runs the entity and relationship synchronization from PostgreSQL to the Neo4j Knowledge Graph.
python backend/pipeline/anime/vectorize_anime.py	Root	Triggers document vectorization (text via Jina-v3 and images via SigLIP) and updates the vector search index and graph.

---

🧠 5. Artificial Intelligence, RAG & MLOps

Model training, distillation, agent alignment (RLHF/DPO), and benchmarks.

RAG Evaluation & Alignment (DPO / RL)

Command	Directory	Description
python backend/api/manage.py run_rag_ablation --source curated	Root	Runs the RAG pipeline with cognitive boosters ON vs OFF over a query set and reports RAGAS deltas (faithfulness / relevancy / context precision). Use --source gold for the Gold Dataset questions. Requires a live judge LLM.
python backend/scripts/mlops_rag_eval.py	Root	Runs automated Ragas evaluations (Faithfulness, Answer Relevance) on samples to check for regressions.
python backend/pipeline/mlops/evaluation_metrics.py	Root	Calculates global evaluation metrics (Hit Rate, MRR) against the "Gold Dataset".
python backend/pipeline/mlops/dpo_feedback_loop.py	Root	Collects user interactions and corrections to compile a local DPO dataset.
python scripts/curation/curate_dpo_dataset.py	Root	Filters and cleans the interaction database to export formatted DPO fine-tuning datasets.
python backend/scripts/run_self_play_debate.py	Root	Simulates multi-agent debates to generate high-quality synthetic "Gold" data.
python backend/scripts/train_akinetix_rl.py	Root	Trains the Akinetix RL agent inside its custom simulated environment.

Fine-Tuning, Distillation & Embeddings

Command	Directory	Description
python backend/scripts/finetune_clip_lora.py	Root	Runs LoRA fine-tuning on a vision encoder (CLIP/SigLIP) to better capture anime tropes.
python backend/scripts/seed_face_embeddings.py	Root	Computes and saves reference facial embeddings of characters for multimodal queries.

Quality & Latency Benchmarks

Command	Directory	Description
python scripts/benchmark/benchmark_latency.py	Root	Measures response latencies across inference adapters (local Ollama, Cloud BrainAPI).
python scripts/benchmark/benchmark_quality_v2.py	Root	Evaluates structured generation and search qualities.
python backend/scripts/benchmark_long_context.py	Root	Measures retrieval accuracy on extremely long contexts (needle-in-a-haystack test).

---

🧪 6. Testing & Quality Assurance (QA)

Unit tests, integration tests, visual regression tests, and end-to-end suites.

Command	Directory	Description
pytest	Root	Runs the backend Django test suite and domain logic validations.
npm run test:e2e	frontend/	Runs the Playwright end-to-end user-journey tests (mocked backend API) against the Vite app.
npm run test	frontend/	Runs Vitest unit and component tests for the React application.
npm run test:vrt	frontend/	Runs Visual Regression Testing (VRT) using Playwright screenshots.
npm run test:vrt:update	frontend/	Updates baseline reference screenshots for VRT.

---

🧹 7. Maintenance, Diagnostics & Workers

Maintenance scripts, database reconciliation, and background worker pools.

Command	Directory	Description
pip install -r requirements.txt	Root	Installs the union runtime lock (dev/CI). The Docker images ship their own subset locks: requirements-web.txt (web + Cloud Run jobs, CPU torch), requirements-brain.txt (GPU serving, no Django), requirements-dataflow.txt (web stack + Beam).
pip install -r requirements.txt -r requirements-dev.txt	Root	Full dev/test env — adds pytest, the Playwright stack and other dev-only tooling (kept out of the prod lock).
python backend/api/manage.py reconcile_db	Root	(CRITICAL) Analyzes and resolves sync discrepancies between PostgreSQL and Neo4j (bulk-loaded, no N+1).
python backend/api/manage.py check_db_status	Root	Unified diagnostics: pgvector document counts, physical table statuses, and migration state on the target database.
python backend/api/manage.py generate_offline_db	Root	Compiles a lightweight SQLite database for offline catalog search capability.
python scripts/detect_embedding_drift.py	Root	Detects vector semantic shifts following embedding model updates.
python scripts/verify/verify_brain_adapter.py	Root	Performs a smoke test on the primary cloud inference adapter.
python scripts/verify/rag_smoke_test.py	Root	Runs a basic verification check on the RAG pipeline (Vector Search -> Rerank).
python scripts/curation/vision_quest_worker.py	Root	Starts the background worker processing vision queue tasks.
gcloud run jobs execute <job-name> --region europe-west9	Anywhere	Manually triggers one of the 8 scheduled Cloud Run Jobs (catalog sync, drift baselines, MLOps loops) — Celery was fully replaced by Cloud Run Jobs + Scheduler.