fix(ci): robust setup.py for dependency submission and docs update

Author: quantDIY

.agent/skills/python_packaging/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: python_packaging
+description: Guidelines for creating robust Python extension setup.py files that survive CI environments.
+---
+# Python Packaging in QuanuX
+
+When creating or modifying `setup.py` files for Python extensions (especially those using Cython, PyBind11, or Numpy), you must ensure they are robust against missing build-time dependencies.
+
+## The Problem
+CI/CD systems (like GitHub's Dependency Submission Action) often run in environments where build dependencies like `Cython` or `numpy` are NOT installed. If `setup.py` unconditionally imports them, the dependency graph generation fails.
+
+## The Solution: Robust Setup Pattern
+Always wrap build-time imports in `try-except` blocks. If they are missing, the script should still run successfully but yield an empty list of extensions.
+
+### Template
+
+```python
+import os
+from setuptools import setup, Extension
+
+# 1. Wrap build dependencies
+try:
+    from Cython.Build import cythonize
+    import numpy 
+except ImportError:
+    cythonize = None
+    numpy = None
+
+ext_modules = []
+
+# 2. Conditional Build Logic
+if cythonize and numpy:
+    # Define extensions here
+    extensions = [
+        Extension(
+            "my_extension",
+            sources=["src/my_extension.pyx"],
+            include_dirs=[numpy.get_include()],
+            # ...
+        )
+    ]
+    ext_modules = cythonize(extensions, language_level=3)
+else:
+    print("Build dependencies (Cython/Numpy) not found. Skipping extension build.")
+    # This print is important for debugging but allows the script to exit with code 0
+
+# 3. Setup Call
+setup(
+    name="my_package",
+    ext_modules=ext_modules, # Will be empty if deps missing
+    # ... standard metadata ...
+)
+```
+
+## Checklist
+- [ ] Import `Cython.Build.cythonize` inside `try-except ImportError`.
+- [ ] Import `numpy` inside `try-except ImportError` (if used).
+- [ ] Check for existence of required directories (e.g. `_deps`, `sdk`) before adding them to `include_dirs`.
+- [ ] Ensure `python setup.py --name` runs successfully in a bare environment.

benchmarks/cython_vs_pybind/setup.py

@@ -1,27 +1,37 @@
-from setuptools import setup, Extension
-from Cython.Build import cythonize
 import os
+from setuptools import setup, Extension
+try:
+    from Cython.Build import cythonize
+except ImportError:
+    cythonize = None
 
 # Adjust path to where pybind11 headers are
 pybind_include = os.path.abspath("../../server/indicators/build/_deps/pybind11-src/include")
 
-print(f"Using pybind11 include: {pybind_include}")
+ext_modules = []
 
-pybind_ext = Extension(
-    "bench_pybind",
-    ["benchmark_pybind.cpp"],
-    include_dirs=[pybind_include],
-    language="c++",
-    extra_compile_args=["-std=c++17", "-O3", "-undefined", "dynamic_lookup"] # Mac specific linking
-)
+if cythonize:
+    print(f"Using pybind11 include: {pybind_include}")
 
-cython_ext = Extension(
-    "bench_cython",
-    ["benchmark_cython.pyx"],
-    extra_compile_args=["-O3"]
-)
+    pybind_ext = Extension(
+        "bench_pybind",
+        ["benchmark_pybind.cpp"],
+        include_dirs=[pybind_include],
+        language="c++",
+        extra_compile_args=["-std=c++17", "-O3", "-undefined", "dynamic_lookup"] # Mac specific linking
+    )
+
+    cython_ext = Extension(
+        "bench_cython",
+        ["benchmark_cython.pyx"],
+        extra_compile_args=["-O3"]
+    )
+    
+    ext_modules = cythonize([cython_ext], compiler_directives={'language_level': "3"}) + [pybind_ext]
+else:
+    print("Cython not found, skipping extension build")
 
 setup(
     name="benchmarks",
-    ext_modules=cythonize([cython_ext], compiler_directives={'language_level': "3"}) + [pybind_ext],
+    ext_modules=ext_modules,
 )

docs/DEVELOPMENT.md

@@ -115,3 +115,35 @@ Ensure you are running `quanuxctl` with `PYTHONPATH=.` from the project root, or
 
 ### CMake "Missing header"
 If headers like `nats.h` are missing, ensure the `FetchContent_MakeAvailable(cnats)` step succeeded in the CMake output. Try clearing the `build/` directory and re-running `cmake ..`.
+
+---
+
+## Python Extension Guidelines
+
+### Robust Packaging (CI/CD)
+When writing `setup.py` files for extensions (Cython/PyBind11), you **must** handle missing build dependencies gracefully. CI environments often run dependency checks without installing build tools like Cython or Numpy.
+
+**Requirements:**
+1. Wrap `Cython` and `numpy` imports in `try-except ImportError` blocks.
+2. Only define `Extension` objects if dependencies are present.
+3. Ensure `python setup.py --name` succeeds in a bare environment.
+
+**Example Pattern:**
+```python
+try:
+    from Cython.Build import cythonize
+    import numpy
+except ImportError:
+    cythonize = None
+
+ext_modules = []
+if cythonize:
+    # Define extensions
+    ext_modules = cythonize([...])
+
+setup(
+    name="my_extension",
+    ext_modules=ext_modules
+)
+```
+For more details, see the agent skill `python_packaging`.

docs/man/QUANUX_DEV.7

@@ -0,0 +1,59 @@
+.\" Manpage for quanux_dev
+.TH QUANUX_DEV 7 "February 2026" "1.0" "QuanuX HFT Suite"
+.SH NAME
+quanux_dev \- QuanuX Development Guidelines and Standards
+.SH DESCRIPTION
+This manual page outlines the development standards, coding conventions, and architectural guidelines for the QuanuX High-Frequency Trading platform.
+
+.SH C++ STANDARDS
+.B Version:
+C++20 is the required standard for all core components (`execution-node`, `server/indicators`).
+.PP
+.B Compiler Flags:
+- `-O3`: Maximum optimization for HFT hot paths.
+- `-march=native`: Target the specific CPU architecture (AVX2/AVX-512).
+- `-fno-rtti`, `-fno-exceptions`: Disabled in hot paths to minimize runtime overhead.
+
+.SH PYTHON EXTENSIONS
+QuanuX relies heavily on Python extensions (Cython/PyBind11) for strategy logic and data analysis.
+.PP
+.B robust-packaging:
+To ensure compatibility with CI/CD environments (like GitHub Dependency Submission), all `setup.py` files must:
+.RS
+1. Wrap build-time imports (`Cython`, `numpy`) in `try-except ImportError` blocks.
+2. Only define `Extension` objects if dependencies are present.
+3. Exit successfully (code 0) even if dependencies are missing (building nothing).
+.RE
+.PP
+Example:
+.RS
+.nf
+try:
+    from Cython.Build import cythonize
+except ImportError:
+    cythonize = None
+
+ext_modules = []
+if cythonize:
+    ext_modules = cythonize([...])
+
+setup(..., ext_modules=ext_modules)
+.fi
+.RE
+
+.SH DIRECTORY STRUCTURE
+.TP
+.B execution-node/
+Core C++ trading engine and adapter interfaces.
+.TP
+.B server/strategies/
+Python-based trading strategies.
+.TP
+.B extensions/
+Vendor-specific integrations (Rithmic, Databento, etc.).
+
+.SH SEE ALSO
+quanux_stats(8), quanuxctl(1)
+
+.SH AUTHOR
+QuanuX Development Team

execution-node/cython/setup.py

@@ -1,35 +1,45 @@
 from setuptools import setup, Extension
-from Cython.Build import cythonize
-import numpy
+try:
+    from Cython.Build import cythonize
+    import numpy
+except ImportError:
+    cythonize = None
+    numpy = None
 
-extensions = [
-    Extension(
-        "adapter", 
-        sources=["src/adapter.pyx"],
-        language="c++",
-        include_dirs=[numpy.get_include()]
-    ),
-    Extension(
-        "core",
-        sources=["src/core.pyx"],
-        language="c++",
-        include_dirs=[numpy.get_include()]
-    ),
-    Extension(
-        "direct_adapter",
-        sources=["src/direct_adapter.pyx"],
-        language="c++",
-        include_dirs=[numpy.get_include()]
-    ),
-    Extension(
-        "nats_adapter",
-        sources=["src/nats_adapter.pyx"],
-        language="c++",
-        include_dirs=[numpy.get_include()]
-    )
-]
+ext_modules = []
+
+if cythonize and numpy:
+    extensions = [
+        Extension(
+            "adapter", 
+            sources=["src/adapter.pyx"],
+            language="c++",
+            include_dirs=[numpy.get_include()]
+        ),
+        Extension(
+            "core",
+            sources=["src/core.pyx"],
+            language="c++",
+            include_dirs=[numpy.get_include()]
+        ),
+        Extension(
+            "direct_adapter",
+            sources=["src/direct_adapter.pyx"],
+            language="c++",
+            include_dirs=[numpy.get_include()]
+        ),
+        Extension(
+            "nats_adapter",
+            sources=["src/nats_adapter.pyx"],
+            language="c++",
+            include_dirs=[numpy.get_include()]
+        )
+    ]
+    ext_modules = cythonize(extensions, language_level=3)
+else:
+    print("Cython or Numpy not found, skipping extension build")
 
 setup(
     name="quanux_node",
-    ext_modules=cythonize(extensions, language_level=3)
+    ext_modules=ext_modules
 )

extensions/cpp/databento/cython/setup.py

@@ -1,33 +1,45 @@
 import os
 import sys
 from setuptools import setup, Extension
-from Cython.Build import cythonize
+try:
+    from Cython.Build import cythonize
+except ImportError:
+    cythonize = None
 
-current_dir = os.path.dirname(os.path.abspath(__file__))
-# Assume CMake build is at ../build
-build_dir = os.path.abspath(os.path.join(current_dir, "../build"))
-include_dir = os.path.join(build_dir, "_deps/databento-src/include")
-lib_dir = os.path.join(build_dir, "lib/Release")
+ext_modules = []
 
-# If headers don't exist, we can't build.
-# We will assume user runs cmake first.
+if cythonize:
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    # Assume CMake build is at ../build
+    build_dir = os.path.abspath(os.path.join(current_dir, "../build"))
+    include_dir = os.path.join(build_dir, "_deps/databento-src/include")
+    lib_dir = os.path.join(build_dir, "lib/Release")
 
-httplib_dir = os.path.join(build_dir, "_deps/httplib-src")
-json_dir = os.path.join(build_dir, "_deps/json-src/include")
+    # If headers don't exist, we can't build.
+    # We will assume user runs cmake first.
+    
+    httplib_dir = os.path.join(build_dir, "_deps/httplib-src")
+    json_dir = os.path.join(build_dir, "_deps/json-src/include")
 
-extensions = [
-    Extension(
-        "databento_ext",
-        ["databento.pyx"],
-        include_dirs=[include_dir, httplib_dir, json_dir],
-        library_dirs=[lib_dir, "/usr/local/lib"],
-        libraries=["databento", "zstd", "curl", "ssl", "crypto", "brotlicommon", "brotlidec", "brotlienc"],
-        language="c++",
-        extra_compile_args=["-std=c++17", "-O3", "-undefined", "dynamic_lookup"]
-    )
-]
+    if os.path.exists(include_dir) and os.path.exists(lib_dir):
+        extensions = [
+            Extension(
+                "databento_ext",
+                ["databento.pyx"],
+                include_dirs=[include_dir, httplib_dir, json_dir],
+                library_dirs=[lib_dir, "/usr/local/lib"],
+                libraries=["databento", "zstd", "curl", "ssl", "crypto", "brotlicommon", "brotlidec", "brotlienc"],
+                language="c++",
+                extra_compile_args=["-std=c++17", "-O3", "-undefined", "dynamic_lookup"]
+            )
+        ]
+        ext_modules = cythonize(extensions, compiler_directives={'language_level': "3"})
+    else:
+        print(f"Databento include/lib not found at {build_dir}, skipping extension build")
+else:
+    print("Cython not found, skipping extension build")
 
 setup(
     name="databento_ext",
-    ext_modules=cythonize(extensions, compiler_directives={'language_level': "3"}),
+    ext_modules=ext_modules,
 )

extensions/cpp/duckdb/cython/setup.py

@@ -1,24 +1,33 @@
 import os
 from setuptools import setup, Extension
-from Cython.Build import cythonize
+try:
+    from Cython.Build import cythonize
+except ImportError:
+    cythonize = None
 
 current_dir = os.path.dirname(os.path.abspath(__file__))
 third_party_dir = os.path.abspath(os.path.join(current_dir, "../third_party"))
 
-print(f"Build info:")
-print(f"  Third Party: {third_party_dir}")
+ext_modules = []
 
-extensions = [
-    Extension(
-        "duckdb_ext",
-        ["duckdb_ext.pyx", os.path.join(third_party_dir, "duckdb.cpp")],
-        include_dirs=[third_party_dir],
-        language="c++",
-        extra_compile_args=["-std=c++17", "-O3", "-undefined", "dynamic_lookup", "-DDUCKDB_STATIC_BUILD"] 
-    )
-]
+if cythonize:
+    print(f"Build info:")
+    print(f"  Third Party: {third_party_dir}")
+
+    extensions = [
+        Extension(
+            "duckdb_ext",
+            ["duckdb_ext.pyx", os.path.join(third_party_dir, "duckdb.cpp")],
+            include_dirs=[third_party_dir],
+            language="c++",
+            extra_compile_args=["-std=c++17", "-O3", "-undefined", "dynamic_lookup", "-DDUCKDB_STATIC_BUILD"] 
+        )
+    ]
+    ext_modules = cythonize(extensions, compiler_directives={'language_level': "3"})
+else:
+    print("Cython not found, skipping extension build")
 
 setup(
     name="duckdb_ext",
-    ext_modules=cythonize(extensions, compiler_directives={'language_level': "3"}),
+    ext_modules=ext_modules,
 )