Metadata-Version: 2.4
Name: vaquum-limen
Version: 4.8.0
Summary: Manifest-driven Bitcoin research software for YAML-defined experiments, benchmark artifacts, backtest ledgers, and decoder cohorts.
Author: Prasenjit Dey, Arun Raguraman, Jatin Thakur, Soujanyaa Boruah, Ng Wei Da
Author-email: Mikko Kotila <mailme@mikkokotila.com>
License-Expression: MIT
Project-URL: Homepage, https://docs.vaquum.fi/limen/
Project-URL: Documentation, https://docs.vaquum.fi/limen/
Project-URL: Repository, https://github.com/vaquum/limen
Project-URL: Issues, https://github.com/Vaquum/Limen/issues
Project-URL: Security, https://github.com/Vaquum/Limen/security/advisories/new
Keywords: bitcoin,machine-learning,research,backtest,yaml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: AUTHORS
Requires-Dist: click<9,>=8.1
Requires-Dist: numpy<3,>=2.2
Requires-Dist: pandas<3,>=2.3
Requires-Dist: polars<2,>=1.0
Requires-Dist: requests<3,>=2.32
Requires-Dist: ruamel.yaml<0.19,>=0.18
Requires-Dist: scikit-learn<2,>=1.6
Requires-Dist: tomli<3,>=2.0; python_version < "3.11"
Requires-Dist: tqdm<5,>=4.67
Provides-Extra: data
Requires-Dist: pyarrow<23,>=18; extra == "data"
Provides-Extra: boosting
Requires-Dist: lightgbm<5,>=4.6; extra == "boosting"
Requires-Dist: xgboost<4,>=2.1; extra == "boosting"
Provides-Extra: indicators
Requires-Dist: ta-lib<0.7,>=0.6; extra == "indicators"
Provides-Extra: stats
Requires-Dist: scipy<2,>=1.15; extra == "stats"
Requires-Dist: statsmodels<0.15,>=0.14; extra == "stats"
Provides-Extra: tabpfn
Requires-Dist: tabpfn<7,>=6; extra == "tabpfn"
Provides-Extra: all
Requires-Dist: lightgbm<5,>=4.6; extra == "all"
Requires-Dist: pyarrow<23,>=18; extra == "all"
Requires-Dist: scipy<2,>=1.15; extra == "all"
Requires-Dist: statsmodels<0.15,>=0.14; extra == "all"
Requires-Dist: ta-lib<0.7,>=0.6; extra == "all"
Requires-Dist: tabpfn<7,>=6; extra == "all"
Requires-Dist: xgboost<4,>=2.1; extra == "all"
Provides-Extra: test
Requires-Dist: coverage[toml]<8,>=7; extra == "test"
Requires-Dist: pytest<10,>=8; extra == "test"
Provides-Extra: release
Requires-Dist: anthropic<1,>=0.54; extra == "release"
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: check-manifest<1,>=0.50; extra == "dev"
Requires-Dist: check-wheel-contents<1,>=0.6; extra == "dev"
Requires-Dist: coverage[toml]<8,>=7; extra == "dev"
Requires-Dist: cyclonedx-bom<8,>=5; extra == "dev"
Requires-Dist: pandas-stubs<2.4,>=2.3; extra == "dev"
Requires-Dist: pip-licenses<6,>=5; extra == "dev"
Requires-Dist: pyright<1.1.409,>=1.1.408; extra == "dev"
Requires-Dist: pyroma<6,>=5; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.8; extra == "dev"
Requires-Dist: scipy-stubs<1.16,>=1.15; extra == "dev"
Requires-Dist: tomli<3,>=2.0; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Dynamic: license-file

<div align="center">
  <br />
  <a href="https://github.com/Vaquum"><img src="https://github.com/Vaquum/Home/raw/main/assets/Logo.png" alt="Vaquum" width="150" /></a>
  <br />
</div>
<br />
<div align="center"><b>Vaquum Limen turns Bitcoin market data into searchable signals, backtested outcomes, and decoder cohorts.</b></div>

<div align="center">
  <a href="#limen">Limen</a> •
  <a href="#what-limen-is-not">What Limen Is Not</a> •
  <a href="#capabilities">Capabilities</a> •
  <a href="#first-experiment">First Experiment</a> •
  <a href="#learn-more">Learn More</a>
</div>
<br />
<div align="center">
  <a href="https://www.bestpractices.dev/projects/11898"><img src="https://www.bestpractices.dev/projects/11898/badge" alt="OpenSSF practices badge" /></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/Vaquum/Limen"><img src="https://img.shields.io/ossf-scorecard/github.com/Vaquum/Limen?label=openssf+scorecard&amp;style=flat" alt="OpenSSF Scorecard" /></a>
  <a href="https://pypi.org/project/vaquum-limen/"><img src="https://img.shields.io/pypi/v/vaquum-limen?label=pypi" alt="PyPI version" /></a>
  <a href="https://docs.vaquum.fi/limen/"><img src="https://img.shields.io/badge/docs-limen-blue" alt="Limen docs" /></a>
  <a href="https://github.com/Vaquum/Limen/actions/workflows/pr_checks_tests.yml"><img src="https://github.com/Vaquum/Limen/actions/workflows/pr_checks_tests.yml/badge.svg" alt="PR tests" /></a>
</div>

<hr />

<a id="limen"></a>

# Limen — Research engine

*Manifest-driven Bitcoin alpha research engine that turns market data into searchable signals, backtested outcomes, and decoder cohorts.*

Limen unifies parameter search across machine learning and rule-based strategies. Built-in analytics record benchmark, backtest, and cohort artifacts for inspection. The project evolves from Talos, a hyperparameter optimization framework for TensorFlow and Keras.

## What Limen Is Not

Limen is not:

- a trade execution system
- a downstream trade decision engine
- a generic multi-asset research platform

In the wider Vaquum architecture, Origo sits upstream as the data layer. Nexus, Praxis, and Veritas sit downstream for decisioning, execution, and oversight.

## Capabilities

- Manifest-driven experiment pipelines
- Search across models, rules, features, targets, and hyperparameters
- Built-in indicator and feature library for Bitcoin research
- Support for both machine learning and rule-based strategy research
- Bitcoin-native transforms, scaling, and target construction
- Split-first train, validation, and test workflows
- Built-in benchmark, backtest, and parameter diagnostics
- Decoder cohort construction with pluggable selection
- Reproducible runs with checkpointing, resumption, and retraining

## First Experiment

The first runnable path is a YAML manifest executed through the `limen` CLI.

1. Install the package:

```bash
pip install vaquum-limen
```

Supported runtime: Limen requires Python `>=3.10,<3.14`; package metadata advertises Python 3.10-3.13 on macOS and Linux. The default install is intentionally light. Use `vaquum-limen[data]` for Arrow dataset IO, `vaquum-limen[boosting]` for LightGBM/XGBoost models, `vaquum-limen[indicators]` for TA-Lib comparison tooling, `vaquum-limen[stats]` for statistical helpers, or `vaquum-limen[all]` for the full research stack. Security support covers the latest released Limen version through [SECURITY.md](https://github.com/Vaquum/Limen/blob/main/SECURITY.md).

2. Scaffold a starter manifest:

```bash
limen init logreg-first.yaml --template logreg_binary
```

3. Validate, profile, and dry-run the manifest:

```bash
limen validate logreg-first.yaml
limen profile logreg-first.yaml
limen run --dry-run logreg-first.yaml
```

4. Run it:

```bash
limen run logreg-first.yaml
```

5. Inspect the result directory printed by the CLI:

- copied YAML manifest
- `metadata.json`
- `results.csv`
- `round_data.jsonl`

That path runs the manifest-backed engine without Python orchestration code. The Python API remains available for custom SFDs, custom prep/model logic, and direct UEL integration.

## Risk Boundary

Limen is research software. Benchmark and backtest outputs are not investment advice, trading advice, execution simulation, regulatory approval, or a promise of future performance. Past performance is not predictive, and trading digital assets can result in total loss of capital.

## Learn more

- Start with the full docs hub at [docs.vaquum.fi/limen](https://docs.vaquum.fi/limen/)
- Start with the YAML/CLI path in [Command Line Interface](https://docs.vaquum.fi/limen/reference/command-line-interface) and [Experiment Manifest](https://docs.vaquum.fi/limen/guides/experiment-manifest)
- Use [Universal Experiment Loop](https://docs.vaquum.fi/limen/guides/universal-experiment-loop) for the engine beneath CLI and direct Python integration
- Define extension research units in [Single-File Decoder](https://docs.vaquum.fi/limen/guides/single-file-decoder) and [Built-In SFDs](https://docs.vaquum.fi/limen/guides/built-in-sfds)
- Analyze results in [Log](https://docs.vaquum.fi/limen/guides/log), [Benchmark](https://docs.vaquum.fi/limen/guides/benchmark), and [Backtest](https://docs.vaquum.fi/limen/guides/backtest)
- Promote finished runs into reusable outputs with [Trainer](https://docs.vaquum.fi/limen/guides/trainer) and [Cohort](https://docs.vaquum.fi/limen/guides/cohort)
- Contribute through [CONTRIBUTING.md](https://github.com/Vaquum/Limen/blob/main/CONTRIBUTING.md) and [Developer docs](https://docs.vaquum.fi/limen/developer/)

## Contributing

Contribution starts through [CONTRIBUTING.md](https://github.com/Vaquum/Limen/blob/main/CONTRIBUTING.md), [docs changes](https://github.com/Vaquum/Limen/tree/main/docs), or [open issues](https://github.com/Vaquum/Limen/issues).

Before contributing, start with the [Developer docs](https://docs.vaquum.fi/limen/developer/).

## Support

Use [SUPPORT.md](https://github.com/Vaquum/Limen/blob/main/SUPPORT.md) for support routes and scope boundaries.

## Vulnerabilities

Report vulnerabilities privately through [GitHub Security Advisories](https://github.com/Vaquum/Limen/security/advisories/new). Do not report vulnerabilities through public issues.

## Citations

Published work should cite:

Vaquum Limen [Computer software]. (2026). Retrieved from https://github.com/Vaquum/Limen.

Machine-readable citation metadata lives in [CITATION.cff](https://github.com/Vaquum/Limen/blob/main/CITATION.cff).

## License

[MIT License](https://github.com/Vaquum/Limen/blob/main/LICENSE).
