sovereign-inference 0.1.0__tar.gz

sovereign_inference-0.1.0/.gitignore

@@ -0,0 +1,170 @@
+# ─── Build outputs ────────────────────────────────────────────────────────────
+build/
+build-*/
+cmake-build-*/
+out/
+dist/
+install/
+_install/
+
+# ─── CMake generated ──────────────────────────────────────────────────────────
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+CTestTestfile.cmake
+CPackConfig.cmake
+CPackSourceConfig.cmake
+install_manifest.txt
+compile_commands.json
+*.cmake
+!CMakeLists.txt
+!cmake/*.cmake
+
+# ─── SPIR-V compiled shaders ──────────────────────────────────────────────────
+shaders/*.spv
+*.spv
+!shaders/compiled/*.spv
+
+# ─── Python ───────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg
+*.egg-info/
+dist/
+.eggs/
+.Python
+pip-log.txt
+pip-delete-this-directory.txt
+.tox/
+.nox/
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+*.pyd
+*.so
+*.dylib
+venv/
+.venv/
+env/
+.env/
+ENV/
+
+# ─── Compiled C/C++ objects & binaries ────────────────────────────────────────
+*.o
+*.a
+*.la
+*.lo
+*.ko
+*.obj
+*.elf
+*.exe
+*.dll
+*.lib
+*.pdb
+*.ilk
+*.exp
+
+# ─── Model files (often large, not for VCS) ───────────────────────────────────
+*.sovereign
+*.gguf
+*.ggml
+*.safetensors
+*.bin
+*.pt
+*.pth
+*.ckpt
+
+# ─── Third-party fetched headers ──────────────────────────────────────────────
+# vk_mem_alloc.h is fetched by scripts/build.sh
+third_party/vk_mem_alloc.h
+
+# Keep the directory itself
+!third_party/.gitkeep
+
+# ─── Vulkan pipeline cache ────────────────────────────────────────────────────
+*.sovereign_pipeline_cache.bin
+.sovereign_pipeline_cache.bin
+
+# ─── IDE and editor files ─────────────────────────────────────────────────────
+# CLion / JetBrains
+.idea/
+*.iml
+
+# VS Code
+.vscode/
+!.vscode/extensions.json
+!.vscode/settings.json.example
+
+# Visual Studio
+*.sln
+*.vcxproj
+*.vcxproj.filters
+*.user
+*.suo
+*.ncb
+*.opensdf
+*.sdf
+x64/
+x86/
+Debug/
+Release/
+
+# Vim
+*.swp
+*.swo
+*~
+tags
+.tags
+
+# Emacs
+*#
+.#*
+\#*#
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+
+# Linux
+*~
+
+# Windows
+Thumbs.db
+Desktop.ini
+
+# ─── Logs and test artefacts ──────────────────────────────────────────────────
+*.log
+*.tmp
+/Testing/
+LastTest.log
+
+# ─── Profiling ────────────────────────────────────────────────────────────────
+gmon.out
+*.prof
+callgrind.*
+massif.*
+cachegrind.*
+perf.data
+perf.data.old
+
+# ─── ASAN / TSAN / UBSAN reports ─────────────────────────────────────────────
+*.asan.log
+*.tsan.log
+
+# ─── Calibration data (typically private) ────────────────────────────────────
+calibration/
+*.calib
+
+# ─── Documentation generated ─────────────────────────────────────────────────
+docs/html/
+docs/latex/
+docs/xml/
+Doxyfile.bak
+
+# ─── JavaScript/Shader Compiler Tooling ───────────────────────────────────────
+node_modules/
+

sovereign_inference-0.1.0/BUILDING.md

@@ -0,0 +1,213 @@
+# Building & Testing Sovereign Engine
+
+Ce guide couvre le cycle complet :
+1. Compiler la librairie C++ + le module Python
+2. Installer le module via `pip`
+3. Convertir un modèle `.safetensors` en `.sovereign`
+4. Tester le tout avec le script Python fourni
+
+---
+
+## Prérequis & Système de Build Sans Dépendance (SDK-Free)
+
+Grâce à notre intégration du méta-chargeur **Volk** pour le chargement dynamique de Vulkan à l'exécution et au téléchargement automatique des en-têtes via CMake (`FetchContent`), **le Vulkan SDK est totalement facultatif** pour compiler le projet.
+
+| Outil | Version | Obligatoire ? | Rôle |
+|---|---|---|---|
+| **CMake** | ≥ 3.25 | **Oui** | Orchestrateur de build principal |
+| **Compilateur C++20** | MSVC 2022 / GCC 12 / Clang 15 | **Oui** | Support C++20 complet exigé |
+| **Vulkan SDK** | ≥ 1.3 (inclut `glslc`) | **Non** | Utilisé uniquement si présent pour recompiler les shaders |
+| **Python** | ≥ 3.9 | **Optionnel** | Requis uniquement pour les liaisons Python (pybind11) |
+| **pip** | ≥ 21 | **Optionnel** | Installation des dépendances et du module local |
+
+### Gestion des Shaders (GLSL -> SPIR-V)
+Le projet contient un système de compilation double-mode intelligent :
+1. **Mode Standard (glslc présent)** : Si le compilateur de shaders `glslc` (fourni avec le SDK Vulkan) est détecté sur votre système, CMake recompile automatiquement tous les fichiers `.comp` du répertoire `shaders/` en fichiers `.spv`.
+2. **Mode Fallback (Pas de glslc)** : Si aucun compilateur n'est présent, le système utilise automatiquement et de manière totalement transparente les binaires SPIR-V précompilés inclus dans `shaders/compiled/`.
+
+### Outils de Compilation Shader JavaScript alternatifs (Optionnel)
+Si vous modifiez des shaders mais n'avez pas installé le SDK Vulkan, vous pouvez utiliser notre outil basé sur Node.js et WebGPU (`@webgpu/glslang`) :
+```bash
+# Installer les dépendances JS locales
+npm install
+
+# Lancer la compilation des shaders compute
+node scripts/compile_shaders.js
+```
+
+---
+
+## Option A — Build manuel (CMake)
+
+```powershell
+# 1. Configurer
+cmake -B build -S . `
+    -DSOVEREIGN_BUILD_PYTHON=ON `
+    -DSOVEREIGN_BUILD_TESTS=ON `
+    -DCMAKE_BUILD_TYPE=Release
+
+# 2. Compiler (tout : lib + shaders + bindings + tests + converter)
+cmake --build build --parallel
+
+# 3. Installer le module Python en mode éditable
+pip install -e build/
+
+# ─── Optionnel : compiler en Debug avec AddressSanitizer ───────────────
+cmake -B build-debug -S . `
+    -DSOVEREIGN_BUILD_TESTS=ON `
+    -DSOVEREIGN_ENABLE_ASAN=ON `
+    -DCMAKE_BUILD_TYPE=Debug
+cmake --build build-debug --parallel
+```
+
+---
+
+## Option B — Script helper (Linux / WSL / Git Bash)
+
+```bash
+# Release + tests + Python bindings
+bash scripts/build.sh
+
+# Debug avec ASAN
+bash scripts/build.sh --debug
+
+# Sans bindings Python
+bash scripts/build.sh --no-python
+
+# Clean build
+bash scripts/build.sh --clean
+```
+
+---
+
+## Option C — pip install (via scikit-build-core)
+
+```powershell
+# Installe scikit-build-core d'abord
+pip install scikit-build-core pybind11
+
+# Installer sovereign-inference depuis le repo local
+pip install .
+
+# Ou en mode éditable (rebuild automatique à chaque changement)
+pip install --no-build-isolation -e .
+```
+
+---
+
+## Lancer les tests unitaires C++
+
+```powershell
+cd build
+ctest --output-on-failure --parallel 4
+
+# Ou directement :
+.\test_format.exe    --success
+.\test_quantizer.exe --success
+.\test_kv_cache.exe  --success
+.\test_engine.exe    --success
+```
+
+---
+
+## Convertir un modèle SafeTensors → .sovereign
+
+```powershell
+# Depuis le dossier build/
+.\sovereign-convert.exe `
+    --input  C:\models\gemma-4b\ `
+    --output gemma-4b.sovereign `
+    --arch   gemma `
+    --quant  mixed `
+    --bpw    4.5 `
+    --verbose
+
+# Avec corpus de calibration (meilleure qualité) :
+.\sovereign-convert.exe `
+    --input  C:\models\gemma-4b\ `
+    --output gemma-4b-calibrated.sovereign `
+    --quant  mixed `
+    --bpw    4.5 `
+    --calib  calibration_corpus.txt
+```
+
+**Modes de quantisation disponibles :**
+
+| Mode | ~bpw | Description |
+|---|---|---|
+| `fp16` | 16 | Aucune quantisation |
+| `int8` | 8 | INT8 uniforme |
+| `q4k` | 4.5 | Q4_K blocks |
+| `q3k` | 3.5 | Q3_K blocks |
+| `q2k` | 2.6 | Q2_K agressif |
+| `mixed` | cible | Adaptatif par tenseur (recommandé) |
+
+---
+
+## Test pipeline complet en Python
+
+```powershell
+# ── Test API uniquement (sans GPU, sans modèle) ──────────────────────
+python examples/test_pipeline.py --self-test
+
+# ── Pipeline complet : convert + validate + inférence ────────────────
+python examples/test_pipeline.py `
+    --model-dir  C:\models\gemma-4b\ `
+    --output     gemma-4b.sovereign `
+    --arch       gemma `
+    --bpw        4.5 `
+    --prompt     "Explique brièvement l'intrication quantique :"
+
+# ── Charger un .sovereign existant directement ───────────────────────
+python examples/test_pipeline.py `
+    --sovereign  gemma-4b.sovereign `
+    --prompt     "Once upon a time" `
+    --max-tokens 256 `
+    --temperature 0.8
+
+# ── Générer en Python pur ────────────────────────────────────────────
+python examples/basic_generate.py `
+    --model  gemma-4b.sovereign `
+    --prompt "Explain transformers in ML:" `
+    --temperature 0.7 `
+    --max-tokens 512
+```
+
+---
+
+## Workflow de développement (push + versioning)
+
+```powershell
+# Après chaque modification :
+git add -A
+git commit -m "feat: description courte"
+
+# Nouvelle version mineure :
+git tag v0.2.0 -m "v0.2.0 - description"
+git push origin main --tags
+
+# Rebuildez le wheel Python après les tags :
+pip install .
+python -c "import sovereign_inference; print(sovereign_inference.version())"
+```
+
+---
+
+## Structure des sorties du build
+
+```
+build/
+├── sovereign-convert(.exe)     # CLI de conversion
+├── sovereign_inference(.pyd/.so)  # Module Python pybind11
+├── sovereign_core.lib/.a       # Librairie statique C++
+├── shaders/                    # SPIR-V compilés
+│   ├── rmsnorm.spv
+│   ├── matmul_int4.spv
+│   ├── attention_gqa.spv
+│   ├── silu_gate.spv
+│   └── sampler.spv
+├── test_format(.exe)           # Binaires de test
+├── test_quantizer(.exe)
+├── test_kv_cache(.exe)
+└── test_engine(.exe)
+```

sovereign_inference-0.1.0/CMakeLists.txt

@@ -0,0 +1,184 @@
+cmake_minimum_required(VERSION 3.25)
+project(sovereign-engine LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# ─── Options ──────────────────────────────────────────────────────────────────
+option(SOVEREIGN_BUILD_TESTS "Build tests" ON)
+option(SOVEREIGN_BUILD_PYTHON "Build Python bindings" ON)
+option(SOVEREIGN_ENABLE_AVX512 "Enable AVX-512 fallback kernels" ON)
+option(SOVEREIGN_ENABLE_ASAN "Enable AddressSanitizer" OFF)
+
+# ─── Compiler Flags & AddressSanitizer ────────────────────────────────────────
+if(MSVC)
+    add_compile_options(/W4)
+    if(SOVEREIGN_ENABLE_ASAN)
+        add_compile_options(/fsanitize=address)
+        add_link_options(/fsanitize=address)
+    endif()
+else()
+    add_compile_options(-Wall -Wextra -Wno-unused-parameter)
+    if(SOVEREIGN_ENABLE_ASAN)
+        add_compile_options(-fsanitize=address -fno-omit-frame-pointer)
+        add_link_options(-fsanitize=address)
+    endif()
+endif()
+
+# ─── Global Compile Definitions ───────────────────────────────────────────────
+add_compile_definitions(
+    SOVEREIGN_VERSION_MAJOR=0
+    SOVEREIGN_VERSION_MINOR=1
+    SOVEREIGN_VERSION_PATCH=0
+)
+
+if(WIN32)
+    add_compile_definitions(WIN32_LEAN_AND_MEAN NOMINMAX)
+endif()
+
+if(SOVEREIGN_ENABLE_AVX512)
+    add_compile_definitions(SOVEREIGN_ENABLE_AVX512=1)
+endif()
+
+# ─── Dependencies ─────────────────────────────────────────────────────────────
+find_package(Vulkan)
+
+include(FetchContent)
+
+if(NOT Vulkan_FOUND)
+    message(STATUS "Vulkan SDK not found. Setting up SDK-free build with Vulkan-Headers...")
+    FetchContent_Declare(
+        vulkan_headers
+        GIT_REPOSITORY https://github.com/KhronosGroup/Vulkan-Headers.git
+        GIT_TAG        v1.3.283
+        GIT_SHALLOW    ON
+    )
+    FetchContent_MakeAvailable(vulkan_headers)
+    
+    add_library(Vulkan::Vulkan INTERFACE IMPORTED)
+    target_link_libraries(Vulkan::Vulkan INTERFACE Vulkan::Headers)
+    if(UNIX AND NOT APPLE)
+        target_link_libraries(Vulkan::Vulkan INTERFACE ${CMAKE_DL_LIBS})
+    endif()
+endif()
+
+if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/third_party/vk_mem_alloc.h")
+    message(STATUS "vk_mem_alloc.h not found. Downloading from GPUOpen GitHub...")
+    file(DOWNLOAD
+        "https://raw.githubusercontent.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator/master/include/vk_mem_alloc.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/third_party/vk_mem_alloc.h"
+        SHOW_PROGRESS
+        STATUS download_status
+    )
+    list(GET download_status 0 status_code)
+    if(NOT status_code EQUAL 0)
+        message(FATAL_ERROR "Failed to download vk_mem_alloc.h: ${download_status}")
+    endif()
+endif()
+
+# ─── Shader Compilation (GLSL -> SPIR-V) ──────────────────────────────────────
+find_program(GLSLC_EXECUTABLE glslc)
+
+set(SHADER_SPV_DIR "${CMAKE_BINARY_DIR}/shaders")
+file(MAKE_DIRECTORY "${SHADER_SPV_DIR}")
+
+set(SHADER_SOURCES
+    shaders/rmsnorm.comp
+    shaders/matmul_int4.comp
+    shaders/attention_gqa.comp
+    shaders/silu_gate.comp
+    shaders/sampler.comp
+)
+
+if(GLSLC_EXECUTABLE)
+    message(STATUS "glslc compiler found at: ${GLSLC_EXECUTABLE}. Recompiling GLSL shaders...")
+    foreach(SHADER_SRC ${SHADER_SOURCES})
+        get_filename_component(SHADER_NAME ${SHADER_SRC} NAME_WE)
+        set(SPV_FILE "${SHADER_SPV_DIR}/${SHADER_NAME}.spv")
+        add_custom_command(
+            OUTPUT ${SPV_FILE}
+            COMMAND ${GLSLC_EXECUTABLE} -O ${CMAKE_CURRENT_SOURCE_DIR}/${SHADER_SRC} -o ${SPV_FILE}
+            DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${SHADER_SRC}
+            COMMENT "Compiling shader ${SHADER_SRC} to SPIR-V"
+        )
+        list(APPEND SHADER_SPV_FILES ${SPV_FILE})
+    endforeach()
+else()
+    message(STATUS "glslc compiler not found. Using precompiled SPIR-V shaders from shaders/compiled/ ...")
+    foreach(SHADER_SRC ${SHADER_SOURCES})
+        get_filename_component(SHADER_NAME ${SHADER_SRC} NAME_WE)
+        set(SPV_FILE "${SHADER_SPV_DIR}/${SHADER_NAME}.spv")
+        add_custom_command(
+            OUTPUT ${SPV_FILE}
+            COMMAND ${CMAKE_COMMAND} -E copy
+                    ${CMAKE_CURRENT_SOURCE_DIR}/shaders/compiled/${SHADER_NAME}.spv
+                    ${SPV_FILE}
+            DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/shaders/compiled/${SHADER_NAME}.spv
+            COMMENT "Copying precompiled shader ${SHADER_NAME}.spv"
+        )
+        list(APPEND SHADER_SPV_FILES ${SPV_FILE})
+    endforeach()
+endif()
+
+add_custom_target(compile_shaders DEPENDS ${SHADER_SPV_FILES})
+
+# ─── Sovereign Core Library ───────────────────────────────────────────────────
+add_library(sovereign_core STATIC
+    src/vulkan/vulkan_context.cpp
+    src/format/format.cpp
+    src/compute/kv_cache.cpp
+    src/inference/engine.cpp
+    src/quantizer/quantizer.cpp
+    src/memory/memory_manager.cpp
+    third_party/volk/volk.c
+)
+
+target_include_directories(sovereign_core PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+    ${CMAKE_CURRENT_SOURCE_DIR}/third_party
+)
+
+target_link_libraries(sovereign_core PUBLIC Vulkan::Vulkan)
+
+# Add dependencies for shader outputs
+add_dependencies(sovereign_core compile_shaders)
+
+# Define shader directory path macro (normalised for Windows/C++ path string compatibility)
+string(REPLACE "\\" "/" SHADER_SPV_DIR_NORM "${SHADER_SPV_DIR}")
+target_compile_definitions(sovereign_core PRIVATE SOVEREIGN_SHADER_DIR="${SHADER_SPV_DIR_NORM}")
+
+# ─── Converter CLI Tool ───────────────────────────────────────────────────────
+add_executable(sovereign-convert
+    tools/converter/main.cpp
+)
+target_link_libraries(sovereign-convert PRIVATE sovereign_core)
+
+# ─── Python Bindings ──────────────────────────────────────────────────────────
+if(SOVEREIGN_BUILD_PYTHON)
+    FetchContent_Declare(
+        pybind11
+        GIT_REPOSITORY https://github.com/pybind/pybind11.git
+        GIT_TAG        v2.11.1
+        GIT_SHALLOW    ON
+    )
+    FetchContent_MakeAvailable(pybind11)
+
+    pybind11_add_module(sovereign_inference bindings/python/sovereign_py.cpp)
+    target_link_libraries(sovereign_inference PRIVATE sovereign_core)
+    install(TARGETS sovereign_inference DESTINATION .)
+endif()
+
+# ─── Unit Tests ───────────────────────────────────────────────────────────────
+if(SOVEREIGN_BUILD_TESTS)
+    FetchContent_Declare(
+        doctest
+        GIT_REPOSITORY https://github.com/doctest/doctest.git
+        GIT_TAG        v2.4.11
+        GIT_SHALLOW    ON
+    )
+    FetchContent_MakeAvailable(doctest)
+
+    enable_testing()
+    add_subdirectory(tests)
+endif()