ctalearn 0.1.0__tar.gz

ctalearn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ting-Hsuan Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctalearn-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: ctalearn
+Version: 0.1.0
+Summary: A cross-sectional / time-series alpha research toolkit for CTA strategies
+Author-email: Ting-Hsuan Huang <felixhuang07@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fffelix-huang/ctalearn
+Project-URL: Documentation, https://fffelix-huang.github.io/ctalearn/
+Project-URL: Repository, https://github.com/fffelix-huang/ctalearn
+Project-URL: Issues, https://github.com/fffelix-huang/ctalearn/issues
+Keywords: alpha,quant,trading,backtesting,cross-sectional,time-series,factor,polars,cta
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy>=1.16.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: polars>=1.34.0
+Requires-Dist: numba>=0.62.1
+Requires-Dist: lark>=1.3.1
+Dynamic: license-file
+
+# ctalearn
+
+[![CI](https://github.com/fffelix-huang/ctalearn/actions/workflows/ci.yml/badge.svg)](https://github.com/fffelix-huang/ctalearn/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.13%20%7C%203.14-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A cross-sectional / time-series **alpha research toolkit** for CTA strategies.
+
+**ctalearn** is built around a thin `DataFrame` wrapper over [Polars](https://pola.rs)
+that guarantees a dense, regularly-sampled time grid. On top of it sits a library
+of vectorized operators (cross-sectional, time-series, arithmetic, strategy),
+a Numba-accelerated backtester, Glassnode data ingestion, and a small embedded
+DSL for expressing alphas as plain text.
+
+## Key features
+
+- **Aligned `DataFrame`** — wraps `pl.DataFrame`, auto-detects bar frequency,
+  fills gaps to a dense grid, and aligns operands automatically on arithmetic
+  (`+ - * /`).
+- **Operator library** — `cs_*` (across assets), `ts_*` (through time),
+  element-wise transforms, and signal-to-weight strategies. Native
+  Polars where possible; Numba only where Polars has no equivalent.
+- **Alpha DSL** — a Lark grammar for expressions like
+  `cs_rank(ts_mean(close, 20) - open)`, with static type checking before
+  execution. Ships its built-in function registry so consumers only provide
+  their own data loaders.
+- **Backtesting** — Numba-accelerated `simulate_trade(weights, prices, fee)`.
+- **Data** — cached Glassnode REST ingestion, single-asset and parallel
+  cross-sectional fetch.
+
+## Installation
+
+Requires Python 3.13+. Add it to your project straight from GitHub
+(managed with [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv add git+https://github.com/fffelix-huang/ctalearn.git
+```
+
+## Quick start
+
+```python
+import polars as pl
+from ctalearn import DataFrame
+from ctalearn.operator import ts_mean, cs_rank
+
+prices = DataFrame(
+    pl.DataFrame({
+        "ts":  pl.datetime_range(..., interval="1d", eager=True),
+        "BTC": [...],
+        "ETH": [...],
+    }),
+    time_col="ts",
+)
+
+# 20-bar moving average, then rank across assets each bar.
+signal = cs_rank(prices - ts_mean(prices, 20))
+```
+
+### Alpha DSL
+
+Express the same idea as text and run it through the interpreter:
+
+```python
+from ctalearn.dsl import (
+    parser, TypeCheckTransformer, ExecutionTransformer,
+    BUILTIN_FUNCTIONS, BUILTIN_FUNCTION_SCHEMA, DslType,
+)
+
+code = "return cs_rank(close - ts_mean(close, 20));"
+
+# Caller supplies only the factor side; functions come from the library.
+factor_schema = {"close": DslType.DATAFRAME}
+data_loaders  = {"close": lambda: prices}
+
+tree   = parser.parse(code)
+TypeCheckTransformer(factor_schema, BUILTIN_FUNCTION_SCHEMA).transform(tree)
+result = ExecutionTransformer(BUILTIN_FUNCTIONS, data_loaders).transform(tree)
+```
+
+See [`examples/dsl_interpreter.py`](examples/dsl_interpreter.py) for a complete,
+runnable integration.
+
+## Development
+
+```bash
+git clone https://github.com/fffelix-huang/ctalearn.git
+cd ctalearn
+uv sync                            # install / sync dependencies
+uv run pytest                      # run tests (doctests + coverage; benchmarks skipped)
+uv run pytest --benchmark-only     # run only the benchmarks
+uv run ruff check --fix            # lint
+uv run ruff format                 # format
+uv run pre-commit run --all-files  # all hooks
+```
+
+## License
+
+[MIT](LICENSE)

ctalearn-0.1.0/README.md

@@ -0,0 +1,99 @@
+# ctalearn
+
+[![CI](https://github.com/fffelix-huang/ctalearn/actions/workflows/ci.yml/badge.svg)](https://github.com/fffelix-huang/ctalearn/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.13%20%7C%203.14-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A cross-sectional / time-series **alpha research toolkit** for CTA strategies.
+
+**ctalearn** is built around a thin `DataFrame` wrapper over [Polars](https://pola.rs)
+that guarantees a dense, regularly-sampled time grid. On top of it sits a library
+of vectorized operators (cross-sectional, time-series, arithmetic, strategy),
+a Numba-accelerated backtester, Glassnode data ingestion, and a small embedded
+DSL for expressing alphas as plain text.
+
+## Key features
+
+- **Aligned `DataFrame`** — wraps `pl.DataFrame`, auto-detects bar frequency,
+  fills gaps to a dense grid, and aligns operands automatically on arithmetic
+  (`+ - * /`).
+- **Operator library** — `cs_*` (across assets), `ts_*` (through time),
+  element-wise transforms, and signal-to-weight strategies. Native
+  Polars where possible; Numba only where Polars has no equivalent.
+- **Alpha DSL** — a Lark grammar for expressions like
+  `cs_rank(ts_mean(close, 20) - open)`, with static type checking before
+  execution. Ships its built-in function registry so consumers only provide
+  their own data loaders.
+- **Backtesting** — Numba-accelerated `simulate_trade(weights, prices, fee)`.
+- **Data** — cached Glassnode REST ingestion, single-asset and parallel
+  cross-sectional fetch.
+
+## Installation
+
+Requires Python 3.13+. Add it to your project straight from GitHub
+(managed with [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv add git+https://github.com/fffelix-huang/ctalearn.git
+```
+
+## Quick start
+
+```python
+import polars as pl
+from ctalearn import DataFrame
+from ctalearn.operator import ts_mean, cs_rank
+
+prices = DataFrame(
+    pl.DataFrame({
+        "ts":  pl.datetime_range(..., interval="1d", eager=True),
+        "BTC": [...],
+        "ETH": [...],
+    }),
+    time_col="ts",
+)
+
+# 20-bar moving average, then rank across assets each bar.
+signal = cs_rank(prices - ts_mean(prices, 20))
+```
+
+### Alpha DSL
+
+Express the same idea as text and run it through the interpreter:
+
+```python
+from ctalearn.dsl import (
+    parser, TypeCheckTransformer, ExecutionTransformer,
+    BUILTIN_FUNCTIONS, BUILTIN_FUNCTION_SCHEMA, DslType,
+)
+
+code = "return cs_rank(close - ts_mean(close, 20));"
+
+# Caller supplies only the factor side; functions come from the library.
+factor_schema = {"close": DslType.DATAFRAME}
+data_loaders  = {"close": lambda: prices}
+
+tree   = parser.parse(code)
+TypeCheckTransformer(factor_schema, BUILTIN_FUNCTION_SCHEMA).transform(tree)
+result = ExecutionTransformer(BUILTIN_FUNCTIONS, data_loaders).transform(tree)
+```
+
+See [`examples/dsl_interpreter.py`](examples/dsl_interpreter.py) for a complete,
+runnable integration.
+
+## Development
+
+```bash
+git clone https://github.com/fffelix-huang/ctalearn.git
+cd ctalearn
+uv sync                            # install / sync dependencies
+uv run pytest                      # run tests (doctests + coverage; benchmarks skipped)
+uv run pytest --benchmark-only     # run only the benchmarks
+uv run ruff check --fix            # lint
+uv run ruff format                 # format
+uv run pre-commit run --all-files  # all hooks
+```
+
+## License
+
+[MIT](LICENSE)

ctalearn-0.1.0/ctalearn/__init__.py

@@ -0,0 +1,5 @@
+from importlib.metadata import version
+
+from ctalearn.core.dataframe import DataFrame
+
+__version__ = version("ctalearn")