Developer & Contribution Guide

This guide provides the technical setup, testing procedures, and architectural overview for developers, researchers, and maintainers contributing to the APEX codebase.

1. Local Environment Setup

APEX requires Python 3.10+ (tested across Python 3.10, 3.11, 3.12, and 3.15).

Clone Repository

git clone https://github.com/Nikhil-Kumar-Shah/APEX.git
cd APEX

Virtual Environment & Dependencies

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows PowerShell:
.\venv\Scripts\Activate.ps1

# Install core runtime dependencies
pip install -r requirements.txt

2. Running the Test Suite

APEX maintains a comprehensive automated test suite covering API routing, inference pipelines, UI logic, authentication, and file processing: 

# Run complete test suite
python -m pytest -v

# Run specific test modules
python -m pytest tests/test_notebook_redesign.py -v
python -m pytest tests/test_phase4_integration.py -v

Code Style & Whitespace Check

# Verify zero whitespace or carriage-return issues
git diff --check

3. Repository Subsystems

Directory Subsystem Role
notebook/ Holds APEX.ipynb, the clean 2-section runtime entry point.
runtime/api/ FastAPI routing, OpenAI-compatible schemas, streaming SSE, and web chat interface.
runtime/ui/ The APEXLauncher widget, scoped log buffer, and hardware detection card.
runtime/model/ Hugging Face model downloader, cache integrity manager, and VRAM weight loader.
runtime/engine/ Inference engine abstractions and Transformers adapter.
bootstrap/ Dependency installer, diagnostics, and environment verification.
docs/ GitHub Pages static documentation website.
tests/ Pytest test suite (124 automated tests).

4. Pull Request Workflow

  1. Fork the repository and create a feature branch (git checkout -b feature/your-feature).
  2. Implement your changes following existing Python conventions and type annotations.
  3. Ensure all 124 tests pass without regression (python -m pytest -v).
  4. Check that no extraneous files or credentials are tracked (git status).
  5. Submit a pull request to the main branch with a descriptive explanation of your changes.

5. Security & Vulnerability Disclosure

APEX enforces strict security boundaries:

  • Least Privilege Discovery: Unauthenticated endpoints (/health, /runtime, /version) never leak internal file paths, hostnames, or model weights.
  • Document Ingestion Protection: /v1/files sanitizes file names, strictly blocks path traversal attempts (../), rejects file sizes exceeding 25 MB, and enforces strict extension whitelists.
  • Vulnerability Reporting: If you discover a security vulnerability, please report it privately via GitHub Security Advisories or contact the maintainer directly. Do not open public issues for sensitive vulnerabilities.
Previous ← Troubleshooting
Back to Top Overview ↑