jasonlib-dev 0.1.0__tar.gz

jasonlib_dev-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+
+      - name: Run tests
+        run: uv run --group test pytest tests/
+
+      - name: Read version
+        id: version
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Create tag
+        run: |
+          git tag "v${{ steps.version.outputs.version }}" || true
+          git push origin "v${{ steps.version.outputs.version }}" || true
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

jasonlib_dev-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Test
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --group test
+
+      - name: Run tests
+        run: uv run pytest tests/

jasonlib_dev-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

jasonlib_dev-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: jasonlib-dev
+Version: 0.1.0
+Summary: Core JASON pivot-based feature computation library
+Requires-Python: >=3.13
+Requires-Dist: numba<0.63.0,>=0.62.1
+Requires-Dist: numpy<2.4.0,>=2.3.0
+Requires-Dist: pandas<4.0.0,>=3.0.1
+Requires-Dist: pydantic<3.0.0,>=2.11.0
+Requires-Dist: tqdm<5.0.0,>=4.67.1

jasonlib_dev-0.1.0/README.md

@@ -0,0 +1,27 @@
+# jasonlib
+
+Core JASON pivot-based feature computation library.
+
+## Installing as a dependency
+
+Add to your `pyproject.toml`:
+
+```toml
+dependencies = [
+    "jasonlib",
+]
+
+[tool.uv.sources]
+jasonlib = { git = "https://github.com/palinorio/jasonlib", tag = "v0.1.0" }
+```
+
+Update the `tag` value when consuming a newer version.
+
+## Releasing
+
+1. Update the `version` in `pyproject.toml`
+2. Commit and merge the change to `master`
+
+On merge, CI will automatically create a git tag matching the version. Consumers can then pin to the new tag.
+
+> Merging without bumping the version will not create a new tag — the existing tag is left unchanged.

jasonlib_dev-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "jasonlib-dev"
+version = "0.1.0"
+description = "Core JASON pivot-based feature computation library"
+requires-python = ">=3.13"
+dependencies = [
+    "numpy>=2.3.0,<2.4.0",
+    "pandas>=3.0.1,<4.0.0",
+    "numba>=0.62.1,<0.63.0",
+    "tqdm>=4.67.1,<5.0.0",
+    "pydantic>=2.11.0,<3.0.0",
+]
+
+[dependency-groups]
+test = [
+    "pytest>=9.0.2,<10.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jasonlib"]
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"

jasonlib_dev-0.1.0/src/jasonlib/__init__.py

@@ -0,0 +1,53 @@
+"""jasonlib - Core JASON pivot-based feature computation library.
+
+Public API::
+
+    from jasonlib import compute_jason, compute_trend_analysis, compute_pivot_analysis
+    from jasonlib import JAssetClass, JInterval, TrendFunction, PivotSortOption
+    from jasonlib import CoinDataset, TrendAnalysisResult, PivotAnalysisResult
+"""
+
+from jasonlib._calculator import compute_jason
+from jasonlib._models import JAssetClass, JInterval
+from jasonlib._trend_analysis import compute_trend_analysis
+from jasonlib._trend_models import (
+    ChartData,
+    CoinDataset,
+    CoinSeries,
+    InsufficientDataError,
+    MarketTrendSummary,
+    PlotWindow,
+    SummaryMetric,
+    TrendAnalysisResult,
+    TrendCharts,
+    TrendFunction,
+)
+from jasonlib._pivot_models import (
+    PivotSortOption,
+    PivotAnalysisSummary,
+    PivotAnalysisParameters,
+    PivotAnalysisResult,
+)
+from jasonlib._pivot_analysis import compute_pivot_analysis
+
+__all__ = [
+    "compute_jason",
+    "compute_trend_analysis",
+    "JAssetClass",
+    "JInterval",
+    "TrendFunction",
+    "CoinDataset",
+    "InsufficientDataError",
+    "TrendAnalysisResult",
+    "PlotWindow",
+    "SummaryMetric",
+    "MarketTrendSummary",
+    "CoinSeries",
+    "ChartData",
+    "TrendCharts",
+    "compute_pivot_analysis",
+    "PivotSortOption",
+    "PivotAnalysisSummary",
+    "PivotAnalysisParameters",
+    "PivotAnalysisResult",
+]

jasonlib_dev-0.1.0/src/jasonlib/_calculator.py

@@ -0,0 +1,248 @@
+"""Core JASON feature computation."""
+
+import numpy as np
+import pandas as pd
+from tqdm import tqdm
+
+from jasonlib._models import JAssetClass, JInterval
+from jasonlib._numba_kernels import _calculate_metrics_for_window
+from jasonlib._trading_calendar import (
+    TRADING_DAYS_PER_YEAR,
+    TRADING_HOURS_PER_DAY,
+    get_logger,
+    normalize_asset_class,
+)
+
+logger = get_logger("jasonlib.calculator")
+
+_JASON_COLUMNS = [
+    "high_vol",
+    "high_days",
+    "high_z",
+    "high_pivot",
+    "high_json2",
+    "high_json2_plus_1d",
+    "high_json2_plus_2d",
+    "last_fx",
+    "low_json2",
+    "low_json2_plus_1d",
+    "low_json2_plus_2d",
+    "low_pivot",
+    "low_z",
+    "low_days",
+    "low_vol",
+]
+
+_ROUNDING = {
+    "high_vol": 2,
+    "high_days": 1,
+    "high_z": 2,
+    "low_z": 2,
+    "low_days": 1,
+    "low_vol": 2,
+}
+
+
+def compute_jason(
+    df: pd.DataFrame,
+    interval: JInterval,
+    asset_class: JAssetClass,
+    lookback: int = 7,
+    n_pivots: int = 5,
+    min_days: int = 1,
+) -> pd.DataFrame:
+    """Compute JASON pivot-based features from OHLC candle data.
+
+    Identifies high/low pivot points over a rolling lookback window,
+    weights the most frequent pivots, and derives volatility-adjusted
+    support/resistance levels (JSON2), Z-scores, and days-since-pivot
+    metrics.
+
+    Args:
+        df: OHLCV candle data.  Must be datetime-indexed (UTC
+            ``DatetimeIndex``).  Required columns and dtypes:
+
+            ========  =========  ============================
+            Column    Dtype      Description
+            ========  =========  ============================
+            ``open``  float64    Opening price of the candle
+            ``high``  float64    Highest price in the candle
+            ``low``   float64    Lowest price in the candle
+            ``close`` float64    Closing price of the candle
+            ========  =========  ============================
+
+            Additional columns are ignored.  Rows must be sorted ascending
+            by timestamp; the function will sort if they are not.
+        interval: Candle size.  Determines the number of candles that fit
+            inside the *lookback* window.
+        asset_class: Trading calendar to use.  Determines days per year
+            and hours per day for annualization.  Required — no default.
+        lookback: Lookback period in trading days for pivot detection.
+            Default ``7``.
+        n_pivots: Number of top pivots (by frequency) to weight.
+            Default ``5``.
+        min_days: Minimum number of days for a pivot to be considered.
+            Default ``1``.
+
+    Returns:
+        ``pd.DataFrame`` indexed by ``DatetimeIndex`` (UTC), starting from
+        the first candle after the lookback window.  Columns:
+
+        ======================  =========  ==========================================
+        Column                  Dtype      Description
+        ======================  =========  ==========================================
+        ``high_vol``            float64    Annualized volatility (%) at high pivots
+        ``high_days``           float64    Trading days since the high pivot
+        ``high_z``              float64    Z-score from high pivot to last close
+        ``high_pivot``          float64    Weighted average high pivot price
+        ``high_json2``          float64    Support level (high_pivot * exp(-2*std))
+        ``high_json2_plus_1d``  float64    Support level projected +1 day
+        ``high_json2_plus_2d``  float64    Support level projected +2 days
+        ``last_fx``             float64    Last closing price at this timestamp
+        ``low_json2``           float64    Resistance level (low_pivot * exp(+2*std))
+        ``low_json2_plus_1d``   float64    Resistance level projected +1 day
+        ``low_json2_plus_2d``   float64    Resistance level projected +2 days
+        ``low_pivot``           float64    Weighted average low pivot price
+        ``low_z``               float64    Z-score from low pivot to last close
+        ``low_days``            float64    Trading days since the low pivot
+        ``low_vol``             float64    Annualized volatility (%) at low pivots
+        ======================  =========  ==========================================
+
+        Volatility and Z-score columns are rounded to 2 decimal places.
+        Days columns are rounded to 1 decimal place.
+    """
+    if df.empty:
+        return pd.DataFrame()
+
+    df = df.sort_index()
+
+    normalized_ac = normalize_asset_class(asset_class)
+    days_in_year = float(TRADING_DAYS_PER_YEAR[normalized_ac])
+    hours_per_day = TRADING_HOURS_PER_DAY[normalized_ac]
+    seconds_per_trading_day = hours_per_day * 3600
+
+    # Quadratic variation for volatility estimation
+    m_big = np.log(df["high"] / df["open"])
+    m_small = np.log(df["low"] / df["open"])
+    x = np.log(df["close"] / df["open"])
+    qv_series = (
+        0.511 * (m_big - m_small) ** 2
+        - 0.019 * (x * (m_big + m_small) - 2 * m_big * m_small)
+        - 0.383 * x**2
+    )
+
+    highs = df["high"].to_numpy(dtype=np.float64)
+    lows = df["low"].to_numpy(dtype=np.float64)
+    closes = df["close"].to_numpy(dtype=np.float64)
+
+    candle_seconds = interval.seconds
+
+    if normalized_ac == JAssetClass.CRYPTO:
+        lookback_candles = int(lookback * 24 * 3600 // candle_seconds)
+    else:
+        lookback_candles = int(
+            lookback * seconds_per_trading_day // candle_seconds
+        )
+
+    window_size = lookback_candles + 1
+
+    s_in_year = days_in_year * seconds_per_trading_day
+    min_days_in_years = (min_days / days_in_year) - (candle_seconds / s_in_year)
+
+    qv_values = qv_series.to_numpy(dtype=np.float64)
+
+    t_seconds = np.arange(
+        window_size * candle_seconds, 0, -candle_seconds, dtype=np.float64
+    )
+    t_seconds = np.maximum(t_seconds, candle_seconds)
+    relative_time_in_years = t_seconds / s_in_year
+
+    num_points = len(df)
+    results: list[tuple] = []
+
+    for i in tqdm(
+        range(lookback_candles, num_points),
+        desc="Computing JASON",
+        leave=False,
+    ):
+        start_idx = i - lookback_candles
+        end_idx = i + 1
+
+        qv_window = qv_values[start_idx:end_idx]
+        qv_sum_rev = np.cumsum(qv_window[::-1])[::-1]
+        w_sum_rev = np.arange(len(qv_window), 0, -1, dtype=np.float64)
+        vols_window = np.sqrt(
+            (qv_sum_rev * s_in_year) / (w_sum_rev * candle_seconds)
+        )
+
+        res_tuple = _calculate_metrics_for_window(
+            highs[start_idx:end_idx],
+            lows[start_idx:end_idx],
+            closes[start_idx:end_idx],
+            vols_window,
+            relative_time_in_years,
+            n_pivots,
+            min_days_in_years,
+            days_in_year,
+        )
+        results.append(res_tuple)
+
+    if not results:
+        return pd.DataFrame()
+
+    result_df = pd.DataFrame(
+        results, index=df.index[lookback_candles:], columns=_JASON_COLUMNS
+    )
+    result_df =  result_df.round(_ROUNDING)
+    result_df = _calculate_ztv(result_df)
+    return result_df
+
+
+
+
+# ============================================================================
+# ZTV AND LATEST METRICS
+# ============================================================================
+
+def _calculate_ztv(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Calculates all ZTV and Days metrics and returns a single DataFrame.
+
+    ZTV (Z-Time-Volatility) is a conviction score combining Z-Score, Time, and Volatility.
+    It measures the total power of a price move as a percentage of theoretical maximum.
+
+    Args:
+        jason_df: DataFrame with JASON features including:
+            - high_z, low_z: Z-scores
+            - high_vol, low_vol: Volatility at pivots
+            - high_days, low_days: Days since pivots
+
+    Returns:
+        DataFrame with additional columns:
+            - high_ztv, low_ztv: Raw ZTV values
+            - high_ztv_ratio, low_ztv_ratio: ZTV as ratio of max (0-1)
+            - high_days_ratio, low_days_ratio: Days as ratio of max (0-1)
+    """
+    # if jason_df.empty:
+    #     return pd.DataFrame()
+
+    # df = jason_df.copy()
+
+
+    # ZTV Metrics Logic
+    MAX_Z = 2.5
+    MAX_DAYS_ZTV = 4.0
+    MAX_VOL = 100.0
+    max_ztv = MAX_VOL * MAX_Z * np.sqrt(MAX_DAYS_ZTV)
+
+    df['high_ztv'] = df['high_z'] * df['high_vol'] * np.sqrt(df['high_days'].astype(float))
+    df['low_ztv'] = df['low_z'] * df['low_vol'] * np.sqrt(df['low_days'].astype(float))
+    df['high_ztv_ratio'] = (df['high_ztv'] / max_ztv).clip(0, 1)
+    df['low_ztv_ratio'] = (df['low_ztv'] / max_ztv).clip(0, 1)
+
+    # Days Metrics Logic
+    MAX_DAYS_RATIO = 5.0
+    df['high_days_ratio'] = (df['high_days'] / MAX_DAYS_RATIO).clip(0, 1)
+    df['low_days_ratio'] = (df['low_days'] / MAX_DAYS_RATIO).clip(0, 1)
+
+    return df

jasonlib_dev-0.1.0/src/jasonlib/_math.py

@@ -0,0 +1,52 @@
+"""Sigmoid utility functions for trend score calculations."""
+
+import numpy as np
+import pandas as pd
+
+
+def sigmoid_z(x: pd.Series, threshold: float = 2.0, k: float = 10.0) -> pd.Series:
+    """Apply a sigmoid function centered around a threshold.
+
+    Args:
+        x: Input Series.
+        threshold: Center point of the sigmoid.
+        k: Steepness factor.
+
+    Returns:
+        Sigmoid-transformed Series with same index.
+    """
+    numeric_x = x.astype(float).to_numpy()
+    result = 1 / (1 + np.exp(-k * (numeric_x - threshold)))
+    return pd.Series(result, index=x.index)
+
+
+def sigmoid_diff(x: pd.Series, threshold: float = 1.0, k: float = 10.0) -> pd.Series:
+    """Apply a differential sigmoid creating symmetric positive/negative mapping.
+
+    Args:
+        x: Input Series.
+        threshold: Threshold for the differential.
+        k: Steepness factor.
+
+    Returns:
+        Differential sigmoid-transformed Series with same index.
+    """
+    numeric_x = x.astype(float).to_numpy()
+    result = 1 + 1 / (1 + np.exp(-k * (numeric_x - threshold))) - 1 / (1 + np.exp(-k * (-numeric_x + threshold)))
+    return pd.Series(result, index=x.index)
+
+
+def sigmoid_vol(x: pd.Series, hist_vol: float = 50.0, k: float = 0.2) -> pd.Series:
+    """Apply a sigmoid function for volatility weighting.
+
+    Args:
+        x: Input Series of volatility values.
+        hist_vol: Historical volatility center point.
+        k: Steepness factor.
+
+    Returns:
+        Sigmoid-weighted Series with same index.
+    """
+    numeric_x = x.astype(float).to_numpy()
+    result = 1 / (1 + np.exp(-k * (numeric_x - hist_vol)))
+    return pd.Series(result, index=x.index)

jasonlib_dev-0.1.0/src/jasonlib/_models.py

@@ -0,0 +1,62 @@
+"""JASON domain model enums."""
+
+from enum import Enum
+
+import pandas as pd
+
+
+class JAssetClass(str, Enum):
+    """Supported asset classes for JASON calculations.
+
+    Determines the trading calendar used for time-aware computations:
+    - CRYPTO: 365 days/year, 24 hours/day
+    - EQUITY: 252 trading days/year, 6.5 hours/day (US market hours)
+    - COMMOD: 252 trading days/year, 23 hours/day (CME Globex)
+    - FX: 252 trading days/year, 23 hours/day (CME Globex)
+    - EQUITY_IDX: 252 trading days/year, 23 hours/day (CME Globex)
+    """
+
+    CRYPTO = "CRYPTO"
+    FX = "FX"
+    COMMOD = "COMMOD"
+    EQUITIES = "EQUITIES"
+    EQUITY_IDX = "EQUITY_IDX"
+
+
+_INTERVAL_SECONDS = {
+    "1m": 60,
+    "5m": 300,
+    "15m": 900,
+    "30m": 1800,
+    "1h": 3600,
+    "4h": 14400,
+    "12h": 43200,
+    "1d": 86400,
+}
+
+
+class JInterval(str, Enum):
+    """Supported candle intervals for JASON calculations.
+
+    Uses MetaTrader-style naming: M for minutes, H for hours, D for days.
+    Each member's string value is the compact interval notation (e.g. "1h").
+    Use the ``seconds`` property to get the candle duration in seconds.
+    """
+
+    M1 = "1m"
+    M5 = "5m"
+    M15 = "15m"
+    M30 = "30m"
+    H1 = "1h"
+    H4 = "4h"
+    H12 = "12h"
+    D1 = "1d"
+
+    @property
+    def seconds(self) -> int:
+        """Return candle duration in seconds."""
+        return _INTERVAL_SECONDS[self.value]
+
+    def to_timedelta(self) -> pd.Timedelta:
+        """Convert interval to pandas Timedelta."""
+        return pd.Timedelta(seconds=self.seconds)