Metadata-Version: 2.4
Name: vaquum_limen
Version: 3.15.3
Summary: Limen unifies parameter search across machine learning and rule-based strategies, with built-in analytics that show not just what works, but why it works.
Author: Prasenjit Dey, Arun Raguraman, Jatin Thakur, Soujanyaa Boruah, Ng Wei Da
Author-email: Mikko Kotila <mailme@mikkokotila.com>
License: MIT
Project-URL: Homepage, https://vaquum.fi
Project-URL: Documentation, https://docs.vaquum.fi/limen/
Project-URL: Repository, https://github.com/vaquum/limen
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.3.1
Requires-Dist: polars>=1.0.0
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: tqdm>=4.67.0
Requires-Dist: xgboost
Requires-Dist: python-dotenv
Requires-Dist: scipy
Requires-Dist: statsmodels
Requires-Dist: tslearn
Requires-Dist: lightgbm
Requires-Dist: pyarrow
Requires-Dist: numpy>=2.2.6
Requires-Dist: ta-lib
Requires-Dist: requests
Requires-Dist: ruamel.yaml>=0.18
Requires-Dist: click>=8.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: tabpfn
Requires-Dist: tabpfn>=6; extra == "tabpfn"
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"><strong>Vaquum Limen turns Bitcoin market data into searchable signals, backtested outcomes, and decoder cohorts.</strong></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 Best Practices" /></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>
</div>

<hr />

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

# Limen — The 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, with built-in analytics that show not just what works, but why it works. It evolves from Talos, the hyperparameter optimization framework for TensorFlow and Keras cited in over 1,000 scientific papers with zero breaking bugs in six years.

## 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
- Extensive 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
- Leakage-safe train, validation, and test workflows
- Built-in backtesting, confusion analytics, and parameter diagnostics
- Decoder cohort construction with pluggable selection
- Reproducible runs with checkpointing, resumption, and retraining

## First Experiment

The fastest first success is a small parameter sweep on the bundled BTC/USDT kline dataset with the built-in logistic-regression decoder.

1. Install the package:

```bash
pip install vaquum_limen
```

2. Load data and run a first experiment:

```python
import limen

historical = limen.HistoricalData()
data = historical.get_spot_klines(kline_size=7200, row_count_limit=2000)

uel = limen.UniversalExperimentLoop(data=data, sfd=limen.sfd.logreg_binary)

uel.run(
    experiment_name="logreg-first",
    n_permutations=25,
    prep_each_round=True,
)
```

3. Inspect the core outputs:

- `uel.experiment_log` for the parameter sweep results
- `uel.experiment_confusion_metrics` for confusion analytics
- `uel.experiment_backtest_results` for backtest results

That path is the simplest way to get a real Limen run on your machine without relying on repo-local fixture files. If you want richer run directories, checkpoints, resumability, and stored round artefacts, continue into the UEL documentation below.

## Learn More

- Start with the full docs hub in [docs/README.md](docs/README.md)
- Define research units in [docs/Single-File-Decoder.md](docs/Single-File-Decoder.md), [docs/Built-In-SFDs.md](docs/Built-In-SFDs.md), and [docs/Experiment-Manifest.md](docs/Experiment-Manifest.md)
- Run experiments in [docs/Universal-Experiment-Loop.md](docs/Universal-Experiment-Loop.md) and extend the artifact-rich path through [docs/Advanced-Search.md](docs/Advanced-Search.md) and [docs/Reducers-And-Feedback.md](docs/Reducers-And-Feedback.md)
- Analyze results in [docs/Log.md](docs/Log.md), [docs/Benchmark.md](docs/Benchmark.md), and [docs/Backtest.md](docs/Backtest.md)
- Understand the model layer in [docs/Reference-Architecture.md](docs/Reference-Architecture.md) and the helper layer in [docs/Utilities.md](docs/Utilities.md)
- Promote finished runs into reusable outputs with [docs/Trainer.md](docs/Trainer.md) and [docs/Cohort.md](docs/Cohort.md)
- Contribute through [docs/Developer/README.md](docs/Developer/README.md)

## Contributing

The simplest way to start contributing is by [joining an open discussion](https://github.com/Vaquum/Limen/issues?q=is%3Aissue%20state%3Aopen%20label%3Aquestion%2Fdiscussion), contributing to [the docs](https://github.com/Vaquum/Limen/tree/main/docs), or by [picking up an open issue](https://github.com/Vaquum/Limen/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug%20OR%20label%3Aenhancement%20OR%20label%3A%22good%20first%20issue%22%20OR%20label%3A%22help%20wanted%22%20OR%20label%3APriority%20OR%20label%3Aprocess).

Before contributing, start with [docs/Developer/README.md](docs/Developer/README.md).

## Vulnerabilities

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

## Citations

If you use Limen for published work, please cite:

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

## License

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