Metadata-Version: 2.4
Name: falcata
Version: 1.1.0
Summary: Falcata: GPU-first gradient boosted decision trees
Author-Email: Felix Jonas Kroner <felix@mechafauna.ai>, Max <max@mechafauna.ai>
Maintainer-Email: Felix Jonas Kroner <felix@mechafauna.ai>, Max <max@mechafauna.ai>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Project-URL: homepage, https://github.com/MechaFauna-ai/Falcata
Project-URL: repository, https://github.com/MechaFauna-ai/Falcata.git
Project-URL: changelog, https://github.com/MechaFauna-ai/Falcata/releases
Requires-Python: >=3.10
Requires-Dist: narwhals>=1.15
Requires-Dist: numpy>=1.21.3
Requires-Dist: scipy
Provides-Extra: arrow
Requires-Dist: narwhals[pyarrow]; extra == "arrow"
Requires-Dist: pyarrow>=16.0.0; extra == "arrow"
Provides-Extra: multigpu
Requires-Dist: nvidia-nccl-cu12; extra == "multigpu"
Provides-Extra: dask
Requires-Dist: dask[array,dataframe,distributed]>=2.0.0; extra == "dask"
Requires-Dist: narwhals[pandas]; extra == "dask"
Requires-Dist: pandas>=1.3.4; extra == "dask"
Provides-Extra: pandas
Requires-Dist: narwhals[pandas]; extra == "pandas"
Requires-Dist: pandas>=1.3.4; extra == "pandas"
Provides-Extra: plotting
Requires-Dist: graphviz; extra == "plotting"
Requires-Dist: matplotlib; extra == "plotting"
Provides-Extra: polars
Requires-Dist: narwhals[polars]; extra == "polars"
Requires-Dist: polars>=1.0.0; extra == "polars"
Provides-Extra: scikit-learn
Requires-Dist: scikit-learn>=1.0.2; extra == "scikit-learn"
Description-Content-Type: text/x-rst

Falcata
=======

GPU-first gradient boosted decision trees.

*Falcataria moluccana* — the falcata — is one of the fastest-growing trees on
earth. This one grows them faster too.

Falcata is a CUDA-native GBDT library: a leaf-wise learner whose training loop
was rebuilt around batched, level-parallel GPU kernels rather than one split at
a time.

What makes it fast
------------------

- **Hybrid level-batched growth** — whole levels of sibling pairs are scored,
  synchronized and applied in one launch each instead of per split, turning a
  latency-bound loop into a throughput-bound one, with leaf-wise-identical trees.
- **CUDA-graph level loops** — the per-level launch sequence is captured once and
  replayed by a device-side controller, removing host round-trips.
- **Per-tree compact column view** — with any ``feature_fraction < 1``, only
  the sampled columns are materialized for histogram construction; the win
  scales with the excluded fraction (29.7× end-to-end at
  ``feature_fraction = 0.1``, 2.33× at 0.6, on the Numerai deep regime;
  21 Oct 2026 on ``a82336d8``).
- **GPU-native dataset construction** — dense binning, row-data build and EFB
  pre-checking run on the device; CuPy and ``__cuda_array_interface__`` inputs
  are ingested without a host round-trip.
- **Quantized training, two ways** — ``quant_mode=stochastic`` is the speed
  end: 4-bin gradients with seeded stochastic rounding; ``quant_mode=fixedpoint``
  is the near-lossless end: deterministic rounding with an internal
  outlier-robust gradient scale. Stochastic raises its 4 bins to 16 (64 for
  constant-hessian objectives) on large data with small leaves; bin counts are
  overridable with ``quant_bins``; both modes are bit-reproducible run to run
  and across GPU models (verified sm_89 vs sm_120 on a pre-launch build; the
  integer-only Philox stream keeps the guarantee by construction).
- **GPU inference via NVIDIA FIL** — with cuML installed (``cuml-cu13`` for
  the prebuilt CUDA 13 wheel), ``Booster.predict()`` transparently runs on the
  Forest Inference Library; CuPy arrays stay on the device end to end. The
  default fp32 thresholds can route rows near a split threshold differently
  from the exact predictor; ``FALCATA_FIL_PRECISION=double`` restores exact
  routing and ``FALCATA_FIL=0`` disables FIL.
- **An execution planner** — shape-conditional kernel choices are resolved once
  from the data and parameters (``cuda_plan=auto``), every decision
  bit-identical except where the ``cuda_plan`` documentation says otherwise,
  and individually overridable.

Every optimization above is required to be bit-identical to the reference path,
and that is enforced mechanically: a 441-cell regression lattice of
(config × data-shape) training cells (98 md5-fingerprinted, 341 plan-flip
equality, 2 metric cells) runs locally on a GPU for every merge and nightly
(hosted CI has no GPU), alongside validity assertions, metric floors and a perf
gate.

Install
-------

.. code:: sh

    pip install falcata

On Linux x86_64 this installs a **prebuilt wheel** — no compilation, no CUDA
toolkit needed — built with CUDA 13, with native GPU code for sm_75 through
sm_120 (T4, RTX 20xx, A100, RTX 30xx/40xx, H100, B100/B200, RTX 50xx). It needs
an NVIDIA driver that supports CUDA 13 (R580 or newer). Older GPUs (Pascal and
Volta) fail fast with a message pointing at the source build; build with
CUDA 12.x for those.

Everywhere else (and with ``pip install --no-binary falcata falcata``), pip
builds from source, which needs the CUDA toolkit (>= 11.0), CMake >= 3.28, a
C++17 compiler and Python >= 3.10. The source distribution vendors every
dependency. The build compiles only for the GPU(s) in the machine (a clean
build takes about 42 s on a 32-thread desktop with CUDA 13.3; 21 Oct 2026 on
``a82336d8``); with no GPU visible it targets every architecture the toolkit
supports, plus PTX, which takes several times as long (not timed for 1.1; the
release wheel's seven architectures without PTX take about 2.5 minutes). To
pick an architecture explicitly:

.. code:: sh

    # RTX 5090 = 120, RTX 4090 = 89, A100 = 80, T4 = 75
    pip install falcata --config-settings=cmake.define.CMAKE_CUDA_ARCHITECTURES=89

There is a CPU build, though it is not what this library is for:

.. code:: sh

    pip install falcata --config-settings=cmake.define.USE_CUDA=OFF

Multi-GPU training additionally needs NCCL *and its headers*
(``libnccl-dev`` on Debian/Ubuntu):

.. code:: sh

    pip install falcata \
      --config-settings=cmake.define.USE_NCCL=ON \
      --config-settings=cmake.define.BUILD_WITH_SHARED_NCCL=ON

Falcata installs under its own name only, so it coexists with stock LightGBM in
one environment; ``import lightgbm`` keeps resolving to LightGBM.

Quick start
-----------

.. code:: python

    import falcata as flc

    ds = flc.Dataset(X_train, label=y_train, params={"device_type": "cuda"})
    model = flc.train(
        {
            "objective": "regression",
            "device_type": "cuda",
            "num_leaves": 255,
            "quant_mode": "stochastic",   # none | stochastic | fixedpoint
            "cuda_precision": "fp32",     # fp64 (default) | fp32
            "cuda_plan": "auto",          # the planner picks the kernels
        },
        ds,
        num_boost_round=1000,
    )

Compatibility with LightGBM
---------------------------

Falcata began as a fork of LightGBM and deliberately stays interoperable at the
data boundaries:

- **Models** with scalar leaves written by Falcata load in stock LightGBM (and
  vice versa) with bit-identical predictions, asserted by a production deploy
  gate; vector-leaf models use a format extension stock LightGBM cannot read.
- **Binary datasets** (``.dataset``) interchange in both directions.
- **Parameter names** are unchanged; Falcata's additions (``quant_mode``,
  ``cuda_precision``, ``cuda_plan``) are new names upstream simply ignores.
- The historical ``LGBM_*`` C API names remain as aliases for ``FLC_*``. The
  Python package is ``import falcata`` only — code written against
  ``import lightgbm`` needs its import changed, nothing else.

License
-------

MIT. Falcata derives from LightGBM (copyright Microsoft Corporation and the
LightGBM developers, MIT); that copyright is retained. Falcata is not affiliated
with, endorsed by, or supported by Microsoft or the LightGBM maintainers.
