blackrubby 0.1.2__tar.gz

blackrubby-0.1.2/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

blackrubby-0.1.2/.github/workflows/wheels.yml

@@ -0,0 +1,71 @@
+name: Build and test wheels
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      publish_to_pypi:
+        description: "Publish the already-built wheels to PyPI (requires license and trusted publisher setup)"
+        required: true
+        type: boolean
+        default: false
+
+jobs:
+  wheels:
+    name: ${{ matrix.os }} wheels
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-15]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade cibuildwheel
+      - run: python -m cibuildwheel --output-dir wheelhouse
+        env:
+          CIBW_BUILD: cp310-* cp311-* cp312-* cp313-* cp314-* cp315-*
+          CIBW_SKIP: "*-win32 *-manylinux_i686 *-musllinux_* *-macosx_universal2"
+          CIBW_TEST_REQUIRES: pytest numpy
+          CIBW_TEST_COMMAND: pytest {project}/tests
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: Source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    if: github.event_name == 'workflow_dispatch' && inputs.publish_to_pypi
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: "*"
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

blackrubby-0.1.2/.gitignore

@@ -0,0 +1,8 @@
+build/
+dist/
+_dist/
+wheelhouse/
+*.egg-info/
+__pycache__/
+*.py[cod]
+blackrubby_package/

blackrubby-0.1.2/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/eigen"]
+	path = vendor/eigen
+	url = https://github.com/eigen-mirror/eigen.git

blackrubby-0.1.2/CMakeLists.txt

@@ -0,0 +1,51 @@
+cmake_minimum_required(VERSION 3.18)
+project(blackrubby_native LANGUAGES CXX)
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG REQUIRED)
+
+if(DEFINED ENV{EIGEN3_INCLUDE_DIR})
+    find_path(EIGEN3_INCLUDE_DIR Eigen/Dense HINTS "$ENV{EIGEN3_INCLUDE_DIR}" NO_DEFAULT_PATH)
+endif()
+if(NOT EIGEN3_INCLUDE_DIR)
+    find_path(EIGEN3_INCLUDE_DIR Eigen/Dense HINTS "${CMAKE_CURRENT_SOURCE_DIR}/../eigen-3.4.0")
+endif()
+if(NOT EIGEN3_INCLUDE_DIR)
+    find_path(EIGEN3_INCLUDE_DIR Eigen/Dense HINTS "${CMAKE_CURRENT_SOURCE_DIR}/vendor/eigen")
+endif()
+if(NOT EIGEN3_INCLUDE_DIR)
+    message(STATUS "Vendored Eigen not found; fetching Eigen 3.4.0 (set EIGEN3_INCLUDE_DIR to skip the download)")
+    include(FetchContent)
+    set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
+    set(EIGEN_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+    set(EIGEN_BUILD_DOC OFF CACHE BOOL "" FORCE)
+    set(EIGEN_BUILD_PKGCONFIG OFF CACHE BOOL "" FORCE)
+    FetchContent_Declare(eigen
+        URL https://github.com/eigen-mirror/eigen/archive/refs/tags/3.4.0.tar.gz
+        URL_HASH SHA256=8586084f71f9bde545ee7fa6d00288b264a2b7ac3607b974e54d13e7162c1c72
+        DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+    )
+    FetchContent_GetProperties(eigen)
+    if(NOT eigen_POPULATED)
+        FetchContent_Populate(eigen)
+    endif()
+    set(EIGEN3_INCLUDE_DIR "${eigen_SOURCE_DIR}")
+endif()
+
+pybind11_add_module(_core MODULE src/core.cpp)
+target_compile_features(_core PRIVATE cxx_std_17)
+target_compile_definitions(_core PRIVATE BLACKRUBBY_NO_MAIN)
+target_include_directories(_core PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/vendor")
+target_include_directories(_core SYSTEM PRIVATE "${EIGEN3_INCLUDE_DIR}")
+if(MSVC)
+    target_compile_options(_core PRIVATE /O2 /EHsc)
+else()
+    target_compile_options(_core PRIVATE -O3)
+endif()
+
+find_package(OpenMP QUIET)
+if(OpenMP_CXX_FOUND)
+    target_link_libraries(_core PRIVATE OpenMP::OpenMP_CXX)
+endif()
+
+install(TARGETS _core DESTINATION blackrubby)

blackrubby-0.1.2/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [Jeremiah White]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

blackrubby-0.1.2/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: blackrubby
+Version: 0.1.2
+Summary: C++ symbolic-plus-kernel regression estimator with a NumPy Python API
+Keywords: regression,symbolic regression,random Fourier features,machine learning
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+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 :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Description-Content-Type: text/markdown
+
+# BlackRubby Regressor
+
+BlackRubby is a numeric regression estimator that fuses two complementary learners:
+
+- **Rubby** — a symbolic search that evolves closed-form candidate expressions (e.g. `sqrt(x0^3 / (x1 + x2))`) on a 3×3×3 cube-walk genome.
+- **Black** — a random-Fourier-feature ridge regression that fits a smooth kernel model over the inputs.
+
+The final model is a single ridge over `[Fourier features | standardized inputs | symbolic columns]`, where the bandwidth, ridge strength, and whether to trust the symbolic columns are all chosen by exact leave-one-out cross-validation. It handles multiple numeric input features and one numeric target, with no Python-side dependencies beyond NumPy.
+
+```python
+import numpy as np
+from blackrubby import BlackRubbyRegressor
+
+rng = np.random.default_rng(7)
+X = rng.uniform(-1, 1, size=(512, 3))
+y = np.sin(X[:, 0] * X[:, 1]) + 0.2 * X[:, 2]
+
+model = BlackRubbyRegressor(expansion_dim=256, random_state=7)
+model.fit(X[:400], y[:400])
+print("held-out R2:", model.score(X[400:], y[400:]))
+print("champion:", model.champion_formula_)
+```
+
+## Install
+
+```
+pip install blackrubby
+```
+
+Pre-built wheels are published for CPython 3.10–3.15 on Linux (x86_64), Windows (x64), and macOS (Intel and Apple Silicon). On a supported platform this installs in seconds with no compiler.
+
+Building from source requires only a C++17 compiler and CMake. Eigen 3.4.0 is vendored under `vendor/eigen`, so **no network access is needed**; set `EIGEN3_INCLUDE_DIR` to use a different Eigen installation.
+
+## How it works
+
+Given training pairs `(x_i, y_i)` with `x_i ∈ R^d`, BlackRubby fits a linear model in a lifted feature space:
+
+```
+ŷ(x) = wᵀ Φ(x) + b
+```
+
+The feature map `Φ(x)` has three blocks:
+
+1. **Random Fourier features.** `D` cos/sin pairs approximating a stationary kernel:
+   `Φ_fourier(x) = (1/√D) [cos(W x̂ / γ), sin(W x̂ / γ)]`, where `x̂` is the standardized input, `W ∈ R^{D×d}` has standard-normal entries, and `γ` is the bandwidth. This is the classic Rahimi–Recht approximation — as `D → ∞`, the inner product `Φ(x)ᵀΦ(x')` converges to the Gaussian kernel `k(x, x') = exp(-‖x̂ - x̂'‖² / 2γ²)`.
+
+2. **Standardized inputs.** The raw `(x - μ) / σ` block, which lets the model represent exactly-linear components without spending Fourier capacity on them.
+
+3. **Symbolic columns (Rubby).** Up to `sym_top_k` expressions found by the search, each standardized to zero mean and unit variance. These give the ridge a direct handle on non-smooth or strongly multiplicative structure (ratios, square roots, powers) that Fourier features approximate only slowly.
+
+The ridge weights minimize the regularized squared error:
+
+```
+w* = argmin_w  Σ_i (y_i - wᵀΦ(x_i) - b)² + α ‖w‖²
+```
+
+### Hyperparameters by exact leave-one-out CV
+
+`bandwidth γ`, ridge strength `α`, and the symbolic on/off decision are chosen on a `select_rows`-row subset using the **exact leave-one-out** formula for ridge regression. One eigendecomposition of the centered Gram matrix gives the LOO residual for every `α` in the grid simultaneously:
+
+```
+e_i^LOO = (y_i - ŷ_i) / (1 - h_i),   h = U diag(λ_j / (λ_j + nα)) Uᵀ
+```
+
+so the model only leans on the symbolic columns when they demonstrably reduce out-of-sample error. A 2-fold holdout at full feature width re-checks the symbolic decision, because the reduced-width selection screen can mis-rank those columns.
+
+### The Rubby symbolic search
+
+Candidate expressions are encoded as a walk on a 3×3×3 cube whose 27 cells each hold one operation or operand (`const`, `x_k`, `+`, `-`, `*`, `/`, `log`, `exp`, `sqrt`, `abs`, `x²`, `x³`). Starting from the corner cell, the genome's path (`sym_turns` moves, each ±x/±y/±z with wraparound) visits cells in order, and the visited nodes form a stack program evaluated column-wise over the data. Each candidate gets a least-squares scale and offset (`a·f(x) + b`), so the search only has to find the right *shape*.
+
+A generation consists of tournament selection (with a path-distance diversity check), uniform crossover over cube cells, point mutation, occasional MCTS refinement of the walk itself (UCT over path prefixes), and a periodic Levenberg–Marquardt polish of the constants on the active path. Fitness is normalized mean squared error, `NMSE = MSE / Var(y)`. The best distinct expressions form a hall of fame that feeds the ridge.
+
+The search runs on a strided `sym_rows`-row subsample for `sym_generations` generations and is fully seeded by `random_state`.
+
+### Final solve
+
+The full model is solved in primal form over up to `solve_rows` rows (auto-capped at `max(50000, 20 × n_features)`), accumulating the centered Gram matrix `G = ΦᵀΦ` in batches and applying a Cholesky solve with an LDLT fallback.
+
+## Reproducibility
+
+With the default `sym_time_limit=0`, the symbolic search is generation-bounded and **fully deterministic**: the same `random_state`, data, and parameters produce a bit-identical model on every run, regardless of thread count or machine load. Setting `sym_time_limit > 0` switches to a wall-clock cap, which can stop at different generations on different runs and therefore trades reproducibility for a hard time budget.
+
+## API
+
+```python
+BlackRubbyRegressor(
+    expansion_dim=1024,    # Fourier cos/sin pairs (D)
+    alpha=0.0,             # ridge strength; 0 = auto by LOO-CV
+    bandwidth=0.0,         # Fourier bandwidth γ; 0 = auto by LOO-CV
+    random_state=42,       # seed for projections and symbolic search
+    use_symbolic=True,     # run the Rubby search
+    sym_population=128,    # GA population size
+    sym_generations=100,   # GA generations (when time limit is 0)
+    sym_rows=1024,         # rows used by the symbolic search
+    sym_top_k=6,           # symbolic columns offered to the ridge
+    sym_time_limit=0.0,    # seconds; 0 = generation-bounded (reproducible)
+    select_rows=2048,      # rows used for hyperparameter selection
+    select_dim=128,        # Fourier pairs used during selection
+    batch_size=2048,       # rows per block in feature assembly
+    solve_rows=-1,         # rows in the final solve; -1 = auto cap, 0 = all
+    max_frequency=54.598,  # largest 1D frequency (standardized units); 1D inputs only
+)
+```
+
+Methods: `fit(X, y)`, `predict(X)`, `score(X, y)` (R²), `get_params()`, `set_params(**params)`.
+
+After fitting, the following attributes are available:
+
+| Attribute | Meaning |
+|---|---|
+| `n_features_in_` | number of input columns seen during `fit` |
+| `fit_seconds_` | total wall-clock fit time |
+| `symbolic_seconds_` | time spent in the Rubby search |
+| `chosen_bandwidth_` | selected Fourier bandwidth γ |
+| `chosen_alpha_` | selected ridge strength α |
+| `uses_symbolic_` | whether the LOO/holdout checks kept the symbolic columns |
+| `symbolic_columns_` | number of symbolic columns in the final model |
+| `champion_formula_` | best expression found, in infix (e.g. `0.9228*exp(x0*x1) - 0.0061`) |
+
+## Usage notes
+
+- `X` must be a finite 1D or 2D numeric array; `y` must be one finite numeric target per row. Multi-output regression, categorical encoding, and missing-value imputation are not built in — encode and impute before calling `fit`.
+- Fit on training data only, tune on validation data, and report on an untouched test set. The internal LOO-CV protects hyperparameter selection, but it is not a substitute for a held-out evaluation.
+- For 1D inputs the Fourier projection is a deterministic log-spaced frequency grid up to `max_frequency`, which suits signal-like data; for `d ≥ 2` the projection is a seeded random Gaussian matrix.
+- `score(X, y)` returns the coefficient of determination R² (1.0 is perfect, 0.0 is no better than predicting the mean).
+
+## Build from source
+
+```bash
+git clone --recurse-submodules https://github.com/zeusnotjupiter/BlackRubby.git
+cd BlackRubby
+python -m pip install build
+python -m build
+```
+
+(If you cloned without `--recurse-submodules`, run `git submodule update --init` first — the Eigen headers under `vendor/eigen` are required.)
+
+For an editable development build:
+
+```bash
+python -m pip install scikit-build-core pybind11 cmake numpy
+python -m pip install -e . --no-build-isolation
+```
+
+Run the tests with `python -m pip install pytest` then `python -m pytest tests`.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).

blackrubby-0.1.2/README.md

@@ -0,0 +1,149 @@
+# BlackRubby Regressor
+
+BlackRubby is a numeric regression estimator that fuses two complementary learners:
+
+- **Rubby** — a symbolic search that evolves closed-form candidate expressions (e.g. `sqrt(x0^3 / (x1 + x2))`) on a 3×3×3 cube-walk genome.
+- **Black** — a random-Fourier-feature ridge regression that fits a smooth kernel model over the inputs.
+
+The final model is a single ridge over `[Fourier features | standardized inputs | symbolic columns]`, where the bandwidth, ridge strength, and whether to trust the symbolic columns are all chosen by exact leave-one-out cross-validation. It handles multiple numeric input features and one numeric target, with no Python-side dependencies beyond NumPy.
+
+```python
+import numpy as np
+from blackrubby import BlackRubbyRegressor
+
+rng = np.random.default_rng(7)
+X = rng.uniform(-1, 1, size=(512, 3))
+y = np.sin(X[:, 0] * X[:, 1]) + 0.2 * X[:, 2]
+
+model = BlackRubbyRegressor(expansion_dim=256, random_state=7)
+model.fit(X[:400], y[:400])
+print("held-out R2:", model.score(X[400:], y[400:]))
+print("champion:", model.champion_formula_)
+```
+
+## Install
+
+```
+pip install blackrubby
+```
+
+Pre-built wheels are published for CPython 3.10–3.15 on Linux (x86_64), Windows (x64), and macOS (Intel and Apple Silicon). On a supported platform this installs in seconds with no compiler.
+
+Building from source requires only a C++17 compiler and CMake. Eigen 3.4.0 is vendored under `vendor/eigen`, so **no network access is needed**; set `EIGEN3_INCLUDE_DIR` to use a different Eigen installation.
+
+## How it works
+
+Given training pairs `(x_i, y_i)` with `x_i ∈ R^d`, BlackRubby fits a linear model in a lifted feature space:
+
+```
+ŷ(x) = wᵀ Φ(x) + b
+```
+
+The feature map `Φ(x)` has three blocks:
+
+1. **Random Fourier features.** `D` cos/sin pairs approximating a stationary kernel:
+   `Φ_fourier(x) = (1/√D) [cos(W x̂ / γ), sin(W x̂ / γ)]`, where `x̂` is the standardized input, `W ∈ R^{D×d}` has standard-normal entries, and `γ` is the bandwidth. This is the classic Rahimi–Recht approximation — as `D → ∞`, the inner product `Φ(x)ᵀΦ(x')` converges to the Gaussian kernel `k(x, x') = exp(-‖x̂ - x̂'‖² / 2γ²)`.
+
+2. **Standardized inputs.** The raw `(x - μ) / σ` block, which lets the model represent exactly-linear components without spending Fourier capacity on them.
+
+3. **Symbolic columns (Rubby).** Up to `sym_top_k` expressions found by the search, each standardized to zero mean and unit variance. These give the ridge a direct handle on non-smooth or strongly multiplicative structure (ratios, square roots, powers) that Fourier features approximate only slowly.
+
+The ridge weights minimize the regularized squared error:
+
+```
+w* = argmin_w  Σ_i (y_i - wᵀΦ(x_i) - b)² + α ‖w‖²
+```
+
+### Hyperparameters by exact leave-one-out CV
+
+`bandwidth γ`, ridge strength `α`, and the symbolic on/off decision are chosen on a `select_rows`-row subset using the **exact leave-one-out** formula for ridge regression. One eigendecomposition of the centered Gram matrix gives the LOO residual for every `α` in the grid simultaneously:
+
+```
+e_i^LOO = (y_i - ŷ_i) / (1 - h_i),   h = U diag(λ_j / (λ_j + nα)) Uᵀ
+```
+
+so the model only leans on the symbolic columns when they demonstrably reduce out-of-sample error. A 2-fold holdout at full feature width re-checks the symbolic decision, because the reduced-width selection screen can mis-rank those columns.
+
+### The Rubby symbolic search
+
+Candidate expressions are encoded as a walk on a 3×3×3 cube whose 27 cells each hold one operation or operand (`const`, `x_k`, `+`, `-`, `*`, `/`, `log`, `exp`, `sqrt`, `abs`, `x²`, `x³`). Starting from the corner cell, the genome's path (`sym_turns` moves, each ±x/±y/±z with wraparound) visits cells in order, and the visited nodes form a stack program evaluated column-wise over the data. Each candidate gets a least-squares scale and offset (`a·f(x) + b`), so the search only has to find the right *shape*.
+
+A generation consists of tournament selection (with a path-distance diversity check), uniform crossover over cube cells, point mutation, occasional MCTS refinement of the walk itself (UCT over path prefixes), and a periodic Levenberg–Marquardt polish of the constants on the active path. Fitness is normalized mean squared error, `NMSE = MSE / Var(y)`. The best distinct expressions form a hall of fame that feeds the ridge.
+
+The search runs on a strided `sym_rows`-row subsample for `sym_generations` generations and is fully seeded by `random_state`.
+
+### Final solve
+
+The full model is solved in primal form over up to `solve_rows` rows (auto-capped at `max(50000, 20 × n_features)`), accumulating the centered Gram matrix `G = ΦᵀΦ` in batches and applying a Cholesky solve with an LDLT fallback.
+
+## Reproducibility
+
+With the default `sym_time_limit=0`, the symbolic search is generation-bounded and **fully deterministic**: the same `random_state`, data, and parameters produce a bit-identical model on every run, regardless of thread count or machine load. Setting `sym_time_limit > 0` switches to a wall-clock cap, which can stop at different generations on different runs and therefore trades reproducibility for a hard time budget.
+
+## API
+
+```python
+BlackRubbyRegressor(
+    expansion_dim=1024,    # Fourier cos/sin pairs (D)
+    alpha=0.0,             # ridge strength; 0 = auto by LOO-CV
+    bandwidth=0.0,         # Fourier bandwidth γ; 0 = auto by LOO-CV
+    random_state=42,       # seed for projections and symbolic search
+    use_symbolic=True,     # run the Rubby search
+    sym_population=128,    # GA population size
+    sym_generations=100,   # GA generations (when time limit is 0)
+    sym_rows=1024,         # rows used by the symbolic search
+    sym_top_k=6,           # symbolic columns offered to the ridge
+    sym_time_limit=0.0,    # seconds; 0 = generation-bounded (reproducible)
+    select_rows=2048,      # rows used for hyperparameter selection
+    select_dim=128,        # Fourier pairs used during selection
+    batch_size=2048,       # rows per block in feature assembly
+    solve_rows=-1,         # rows in the final solve; -1 = auto cap, 0 = all
+    max_frequency=54.598,  # largest 1D frequency (standardized units); 1D inputs only
+)
+```
+
+Methods: `fit(X, y)`, `predict(X)`, `score(X, y)` (R²), `get_params()`, `set_params(**params)`.
+
+After fitting, the following attributes are available:
+
+| Attribute | Meaning |
+|---|---|
+| `n_features_in_` | number of input columns seen during `fit` |
+| `fit_seconds_` | total wall-clock fit time |
+| `symbolic_seconds_` | time spent in the Rubby search |
+| `chosen_bandwidth_` | selected Fourier bandwidth γ |
+| `chosen_alpha_` | selected ridge strength α |
+| `uses_symbolic_` | whether the LOO/holdout checks kept the symbolic columns |
+| `symbolic_columns_` | number of symbolic columns in the final model |
+| `champion_formula_` | best expression found, in infix (e.g. `0.9228*exp(x0*x1) - 0.0061`) |
+
+## Usage notes
+
+- `X` must be a finite 1D or 2D numeric array; `y` must be one finite numeric target per row. Multi-output regression, categorical encoding, and missing-value imputation are not built in — encode and impute before calling `fit`.
+- Fit on training data only, tune on validation data, and report on an untouched test set. The internal LOO-CV protects hyperparameter selection, but it is not a substitute for a held-out evaluation.
+- For 1D inputs the Fourier projection is a deterministic log-spaced frequency grid up to `max_frequency`, which suits signal-like data; for `d ≥ 2` the projection is a seeded random Gaussian matrix.
+- `score(X, y)` returns the coefficient of determination R² (1.0 is perfect, 0.0 is no better than predicting the mean).
+
+## Build from source
+
+```bash
+git clone --recurse-submodules https://github.com/zeusnotjupiter/BlackRubby.git
+cd BlackRubby
+python -m pip install build
+python -m build
+```
+
+(If you cloned without `--recurse-submodules`, run `git submodule update --init` first — the Eigen headers under `vendor/eigen` are required.)
+
+For an editable development build:
+
+```bash
+python -m pip install scikit-build-core pybind11 cmake numpy
+python -m pip install -e . --no-build-isolation
+```
+
+Run the tests with `python -m pip install pytest` then `python -m pytest tests`.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).