lightning-core 0.1.2__tar.gz

lightning_core-0.1.2/.github/workflows/python-wheel-publish.yml

@@ -0,0 +1,97 @@
+name: Build and Publish Python Wheel
+
+on:
+  pull_request:
+    branches: [ main, master ]
+  push:
+    branches: [ main, master ]
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      publish_target:
+        description: "Publish target for manual run"
+        required: true
+        default: "none"
+        type: choice
+        options:
+          - none
+          - testpypi
+
+jobs:
+  build-macos-wheel:
+    name: Build macOS wheel
+    runs-on: macos-14
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/*
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [build-macos-wheel]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.publish_target == 'testpypi'
+    needs: [build-macos-wheel]
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Publish package distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true

lightning_core-0.1.2/.gitignore

@@ -0,0 +1,17 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Python cache
+__pycache__/
+*.pyc
+
+# macOS
+.DS_Store
+
+# Runtime/benchmark local caches
+.cudajun_*.csv
+
+# VS Code
+.vscode/

lightning_core-0.1.2/CMakeLists.txt

@@ -0,0 +1,173 @@
+cmake_minimum_required(VERSION 3.23)
+project(LightningCore VERSION 0.1.1 LANGUAGES CXX)
+
+if(NOT APPLE)
+  message(FATAL_ERROR "Lightning Core currently supports macOS only.")
+endif()
+
+# CMake의 언어 감지 유틸을 끌어온다.
+# 여기서 CUDA 감지할 때 쓰는데, 있으면 행복하고 없으면 CPU로 우회하면 그만임 ㅋ
+include(CheckLanguage)
+
+# 옵션들은 "오늘 어디까지 빌드할래?" 스위치들이다.
+set(CJ_ENABLE_CUDA OFF CACHE BOOL "Enable native NVIDIA CUDA runtime path" FORCE)
+set(CJ_ENABLE_METAL ON CACHE BOOL "Enable native Apple Metal runtime path" FORCE)
+if(DEFINED SKBUILD)
+  option(CJ_BUILD_TESTS "Build unit tests" OFF)
+  option(CJ_BUILD_BENCHMARKS "Build benchmark binaries" OFF)
+  option(CJ_BUILD_PYTHON "Build Python bindings (pybind11)" ON)
+  option(CJ_BUILD_EXAMPLES "Build C/C++ examples" OFF)
+else()
+  option(CJ_BUILD_TESTS "Build unit tests" ON)
+  option(CJ_BUILD_BENCHMARKS "Build benchmark binaries" ON)
+  option(CJ_BUILD_PYTHON "Build Python bindings (pybind11)" ON)
+  option(CJ_BUILD_EXAMPLES "Build C/C++ examples" ON)
+endif()
+
+# C++17로 통일해서 플랫폼별 컴파일러 성격 차이를 줄인다.
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
+endif()
+
+# 기본은 보수적으로 OFF, 감지 성공하면 ON으로 전환한다.
+set(CJ_HAS_CUDA OFF)
+set(CJ_HAS_METAL OFF)
+if(CJ_ENABLE_CUDA)
+  # CUDA 컴파일러가 있는지 먼저 살핀다.
+  check_language(CUDA)
+  if(CMAKE_CUDA_COMPILER)
+    # 여기 들어오면 .cu도 진짜로 빌드 가능한 상태다.
+    enable_language(CUDA)
+    set(CJ_HAS_CUDA ON)
+    message(STATUS "CUDA compiler detected: ${CMAKE_CUDA_COMPILER}")
+  else()
+    # macOS 같은 환경에서 자주 보게 되는 경고. 정상 동작이며 CPU 폴백으로 간다.
+    message(WARNING "CUDA compiler not found. Building CPU-only path.")
+  endif()
+endif()
+
+if(APPLE AND CJ_ENABLE_METAL)
+  check_language(OBJCXX)
+  if(CMAKE_OBJCXX_COMPILER)
+    enable_language(OBJCXX)
+    set(CJ_HAS_METAL ON)
+    message(STATUS "Metal backend enabled with Objective-C++ compiler: ${CMAKE_OBJCXX_COMPILER}")
+  else()
+    message(WARNING "Objective-C++ compiler not found. Metal backend disabled.")
+  endif()
+endif()
+
+# 공통 소스: 런타임, 텐서, 디스패치, CPU 구현.
+set(CJ_SOURCES
+  src/runtime.cpp
+  src/lightning_core_c_api.cpp
+  src/attention.cpp
+  src/attention_cpu.cpp
+  src/ops/matmul_cpu.cpp
+  src/ops/matrix_elemwise.cpp
+  src/ops/vector_add_cpu.cpp
+)
+
+if(APPLE)
+  list(APPEND CJ_SOURCES src/apple_ml.mm)
+else()
+  list(APPEND CJ_SOURCES src/apple_ml_stub.cpp)
+endif()
+
+if(CJ_HAS_CUDA)
+  # CUDA 가능 시 커널 파일 포함.
+  list(APPEND CJ_SOURCES src/ops/vector_add_cuda.cu)
+else()
+  # CUDA 미지원 시 링커 에러 안 나게 스텁 구현 포함.
+  list(APPEND CJ_SOURCES src/ops/vector_add_stub.cpp)
+endif()
+
+if(CJ_HAS_METAL)
+  list(APPEND CJ_SOURCES src/attention_metal.mm)
+  list(APPEND CJ_SOURCES src/ops/matmul_metal.mm)
+  list(APPEND CJ_SOURCES src/ops/matrix_elemwise_metal.mm)
+  list(APPEND CJ_SOURCES src/ops/vector_add_metal.mm)
+else()
+  list(APPEND CJ_SOURCES src/attention_metal.mm)
+  list(APPEND CJ_SOURCES src/ops/matmul_metal.mm)
+  list(APPEND CJ_SOURCES src/ops/matrix_elemwise_metal.mm)
+  list(APPEND CJ_SOURCES src/ops/vector_add_metal_stub.cpp)
+endif()
+
+# 코어 라이브러리 타깃과 네임스페이스 별칭.
+add_library(lightning_core_core STATIC ${CJ_SOURCES})
+add_library(lightning_core::lightning_core ALIAS lightning_core_core)
+add_library(cudajun::cudajun ALIAS lightning_core_core)
+set_target_properties(lightning_core_core PROPERTIES OUTPUT_NAME lightning_core)
+
+target_compile_options(lightning_core_core PRIVATE
+  $<$<CONFIG:Release>:-O3 -ffast-math -funroll-loops>
+)
+
+# 공개 헤더 경로를 내보내서 외부 타깃에서도 include 가능하게 한다.
+target_include_directories(lightning_core_core
+  PUBLIC
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+if(CJ_HAS_CUDA)
+  # 코드에서 #if CJ_HAS_CUDA로 분기할 수 있도록 매크로 주입.
+  target_compile_definitions(lightning_core_core PUBLIC CJ_HAS_CUDA=1)
+  set_target_properties(lightning_core_core PROPERTIES
+    # CUDA separable compilation: 커널/호스트 코드를 파일 단위로 나눠도 링크 가능.
+    CUDA_SEPARABLE_COMPILATION ON
+    CUDA_STANDARD 17
+    CUDA_STANDARD_REQUIRED ON
+  )
+  if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+    # 아키텍처 미지정이면 로컬에 맞춰 자동 추정.
+    set_target_properties(lightning_core_core PROPERTIES CUDA_ARCHITECTURES "native")
+  endif()
+  # CUDA 런타임(cudart) 링크.
+  target_link_libraries(lightning_core_core PUBLIC CUDA::cudart)
+else()
+  # CPU 빌드에서도 코드 경로가 명확히 갈리도록 0을 박아둔다.
+  target_compile_definitions(lightning_core_core PUBLIC CJ_HAS_CUDA=0)
+endif()
+
+if(CJ_HAS_METAL)
+  target_compile_definitions(lightning_core_core PUBLIC CJ_HAS_METAL=1)
+  target_link_libraries(lightning_core_core PUBLIC "-framework Metal" "-framework Foundation")
+else()
+  target_compile_definitions(lightning_core_core PUBLIC CJ_HAS_METAL=0)
+endif()
+
+if(APPLE)
+  target_link_libraries(lightning_core_core PUBLIC "-framework CoreML" "-framework MetalPerformanceShaders" "-framework MetalPerformanceShadersGraph")
+endif()
+
+# 플랫폼 식별 매크로: OS별 조건 컴파일용.
+if(WIN32)
+  target_compile_definitions(lightning_core_core PUBLIC CJ_PLATFORM_WINDOWS=1)
+elseif(APPLE)
+  target_compile_definitions(lightning_core_core PUBLIC CJ_PLATFORM_MACOS=1)
+elseif(UNIX)
+  target_compile_definitions(lightning_core_core PUBLIC CJ_PLATFORM_LINUX=1)
+endif()
+
+# 선택 옵션에 따라 하위 모듈들을 순차적으로 연결한다.
+if(CJ_BUILD_TESTS)
+  enable_testing()
+  add_subdirectory(tests)
+endif()
+
+if(CJ_BUILD_BENCHMARKS)
+  add_subdirectory(benchmarks)
+endif()
+
+if(CJ_BUILD_PYTHON)
+  add_subdirectory(python)
+endif()
+
+if(CJ_BUILD_EXAMPLES)
+  add_subdirectory(examples)
+endif()

lightning_core-0.1.2/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.2
+Name: lightning-core
+Version: 0.1.2
+Summary: Lightning Core: macOS-first CUDA-style runtime with Metal backend
+Keywords: metal,macos,gpu,runtime,cuda-style,pybind11
+Author: Lightning Core Team
+Maintainer: Lightning Core Team
+License: Proprietary
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Operating System :: MacOS :: MacOS X
+Project-URL: Homepage, https://github.com/wnsgus00114-droid/lightining-core
+Project-URL: Repository, https://github.com/wnsgus00114-droid/lightining-core
+Project-URL: Issues, https://github.com/wnsgus00114-droid/lightining-core/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Lightning Core
+
+Lightning Core is a macOS-first CUDA-style runtime focused on custom attention training/inference paths.
+
+## Quick Start (Beginner)
+
+Documentation entrypoint:
+
+- docs/index.md
+
+Use this path first:
+
+1. Install and import-check
+2. Build and run one C API example
+3. Run tests
+
+```bash
+python3 -m pip install .
+python -c "import lightning_core; print(lightning_core.backend_name())"
+
+cmake -S . -B build -DCJ_ENABLE_METAL=ON -DCJ_BUILD_TESTS=ON -DCJ_BUILD_PYTHON=ON -DCJ_BUILD_EXAMPLES=ON
+cmake --build build -j
+
+cmake --build build --target lightning_core_c_api_example -j
+./build/lightning_core_c_api_example
+
+ctest --test-dir build --output-on-failure
+```
+
+Detailed beginner guide:
+
+- docs/quickstart.md
+
+## Scope (Current)
+
+This project is an optimization-focused runtime prototype, not a full deep learning framework.
+
+- Core focus: runtime, attention path, selected matrix/vector ops
+- Model-family wrappers are advanced policy/fastpath helpers, not full model implementations
+- API and internals are still actively evolving
+
+## Identity and Naming
+
+- Public package/module: lightning-core / lightning_core
+- Public C++ include path/namespace: lightning_core/* and lightning_core::...
+- Internal canonical headers: include/lightning_core/core/*
+- Legacy include/cudajun/* remains as compatibility shim
+
+## Advanced Topics
+
+For advanced usage and operations, see:
+
+- docs/advanced.md
+
+For contributor workflow and coding conventions, see:
+
+- docs/contributor.md
+
+Includes:
+
+- benchmark sweeps and generated artifacts
+- resident session and policy tuning
+- model-family wrapper examples and caveats
+- runtime profile/env tuning
+- release and publishing workflow notes
+- repository rename transition operations
+
+## Build Targets
+
+Useful targets:
+
+- library: lightning_core::lightning_core
+- python module: lightning_core
+- c api example: lightning_core_c_api_example
+
+## Repository Rename Status
+
+Current GitHub live URL may still be lightining-core until rename is completed.
+
+Use helper script after rename:
+
+```bash
+./scripts/sync_remote_after_repo_rename.sh --dry-run
+./scripts/sync_remote_after_repo_rename.sh
+```
+
+The script automatically checks target repository availability and skips safely when rename is not ready.
+
+## Project Layout
+
+- include/lightning_core: public wrappers
+- include/lightning_core/core: canonical internal headers
+- include/cudajun: compatibility shims for legacy integrations
+- src: runtime + tensor + ops implementation
+- tests: C++ unit tests
+- benchmarks: benchmark binaries and sweep scripts
+- python: pybind11 bindings
+- docs: split docs (index/quickstart/advanced/contributor)

lightning_core-0.1.2/README.md

@@ -0,0 +1,98 @@
+# Lightning Core
+
+Lightning Core is a macOS-first CUDA-style runtime focused on custom attention training/inference paths.
+
+## Quick Start (Beginner)
+
+Documentation entrypoint:
+
+- docs/index.md
+
+Use this path first:
+
+1. Install and import-check
+2. Build and run one C API example
+3. Run tests
+
+```bash
+python3 -m pip install .
+python -c "import lightning_core; print(lightning_core.backend_name())"
+
+cmake -S . -B build -DCJ_ENABLE_METAL=ON -DCJ_BUILD_TESTS=ON -DCJ_BUILD_PYTHON=ON -DCJ_BUILD_EXAMPLES=ON
+cmake --build build -j
+
+cmake --build build --target lightning_core_c_api_example -j
+./build/lightning_core_c_api_example
+
+ctest --test-dir build --output-on-failure
+```
+
+Detailed beginner guide:
+
+- docs/quickstart.md
+
+## Scope (Current)
+
+This project is an optimization-focused runtime prototype, not a full deep learning framework.
+
+- Core focus: runtime, attention path, selected matrix/vector ops
+- Model-family wrappers are advanced policy/fastpath helpers, not full model implementations
+- API and internals are still actively evolving
+
+## Identity and Naming
+
+- Public package/module: lightning-core / lightning_core
+- Public C++ include path/namespace: lightning_core/* and lightning_core::...
+- Internal canonical headers: include/lightning_core/core/*
+- Legacy include/cudajun/* remains as compatibility shim
+
+## Advanced Topics
+
+For advanced usage and operations, see:
+
+- docs/advanced.md
+
+For contributor workflow and coding conventions, see:
+
+- docs/contributor.md
+
+Includes:
+
+- benchmark sweeps and generated artifacts
+- resident session and policy tuning
+- model-family wrapper examples and caveats
+- runtime profile/env tuning
+- release and publishing workflow notes
+- repository rename transition operations
+
+## Build Targets
+
+Useful targets:
+
+- library: lightning_core::lightning_core
+- python module: lightning_core
+- c api example: lightning_core_c_api_example
+
+## Repository Rename Status
+
+Current GitHub live URL may still be lightining-core until rename is completed.
+
+Use helper script after rename:
+
+```bash
+./scripts/sync_remote_after_repo_rename.sh --dry-run
+./scripts/sync_remote_after_repo_rename.sh
+```
+
+The script automatically checks target repository availability and skips safely when rename is not ready.
+
+## Project Layout
+
+- include/lightning_core: public wrappers
+- include/lightning_core/core: canonical internal headers
+- include/cudajun: compatibility shims for legacy integrations
+- src: runtime + tensor + ops implementation
+- tests: C++ unit tests
+- benchmarks: benchmark binaries and sweep scripts
+- python: pybind11 bindings
+- docs: split docs (index/quickstart/advanced/contributor)

lightning_core-0.1.2/ROADMAP.md

@@ -0,0 +1,58 @@
+# Lightning Core Roadmap
+
+This roadmap tracks known architecture gaps and compatibility work.
+
+## P0: Branding and Surface Consistency
+
+- Unify public naming across package, docs, targets, and namespaces.
+- Keep compatibility wrappers for existing `cudajun` users during migration.
+- Ensure metadata and repository URLs always match the canonical repo.
+
+## P1: Documentation and Expectation Management
+
+- Keep README scope explicit: optimization runtime prototype, not full framework.
+- Separate "implemented now" vs "planned" in docs.
+- Standardize comment/doc tone for external contributors.
+
+## P1: Backend Abstraction Cleanup
+
+- Remove CUDA-centric internal identifiers where backend-neutral semantics are intended.
+- Clarify memory model contracts for each backend.
+- Reduce hidden backend-specific behavior under generic runtime names.
+- Gradually migrate internal namespace naming from `cudajun` to canonical core naming while preserving compatibility.
+
+## P2: Tensor Core Expansion
+
+- Add dtype/layout/stride metadata.
+- Add contiguous and view/slice semantics.
+- Add stricter shape/lifetime validation and richer error paths.
+- Split responsibilities over time: storage, metadata, view rules, and reshape/slice validation layers.
+
+## P2: Ops Layer Modularization
+
+- Split monolithic ops surfaces into:
+  - `ops/vector`
+  - `ops/matrix`
+  - `ops/policy`
+  - `ops/session`
+- Preserve high-level helper APIs while reducing header bloat.
+
+## P2: Python API Expansion
+
+- Expose attention and selected matmul/session APIs.
+- Expose policy controls with safe defaults.
+- Keep minimal onboarding path for first-time users.
+- Keep bindings modular (`bind_tensor`, `bind_ops`, `bind_attention`, `bind_runtime`) for maintainability.
+- Improve numpy/buffer-oriented in-place paths for resident sessions.
+
+## P2: Test Depth
+
+- Add resident-loop stability tests.
+- Add fuzz/edge-case shape tests.
+- Add policy-combination and memory-lifetime regression tests.
+
+## P3: Build Matrix Evolution
+
+- Current mode is macOS-first by design.
+- Add optional CPU-only CI profiles for Linux/Windows to prevent accidental lock-in.
+- Keep platform expansion behind explicit build options.

lightning_core-0.1.2/benchmarks/CMakeLists.txt

@@ -0,0 +1,28 @@
+# vector add 마이크로 벤치 바이너리.
+add_executable(bench_vector_add bench_vector_add.cpp)
+target_link_libraries(bench_vector_add PRIVATE lightning_core::lightning_core)
+
+# attention 전용 벤치 바이너리.
+add_executable(bench_attention bench_attention.cpp)
+target_link_libraries(bench_attention PRIVATE lightning_core::lightning_core)
+
+# 기본 행렬곱 벤치 바이너리.
+add_executable(bench_matmul bench_matmul.cpp)
+target_link_libraries(bench_matmul PRIVATE lightning_core::lightning_core)
+
+# 행렬 원소별 뺄셈/나눗셈 벤치 바이너리.
+add_executable(bench_matrix_ops bench_matrix_ops.cpp)
+target_link_libraries(bench_matrix_ops PRIVATE lightning_core::lightning_core)
+
+# 모델 단위 벤치 바이너리.
+add_executable(bench_transformer bench_transformer.cpp)
+target_link_libraries(bench_transformer PRIVATE lightning_core::lightning_core)
+
+add_executable(bench_lstm_rnn bench_lstm_rnn.cpp)
+target_link_libraries(bench_lstm_rnn PRIVATE lightning_core::lightning_core)
+
+add_executable(bench_cnn_dnn bench_cnn_dnn.cpp)
+target_link_libraries(bench_cnn_dnn PRIVATE lightning_core::lightning_core)
+
+add_executable(bench_vlm bench_vlm.cpp)
+target_link_libraries(bench_vlm PRIVATE lightning_core::lightning_core)