dijkies 0.0.3__py3-none-any.whl

dijkies/performance.py

@@ -0,0 +1,166 @@
+from abc import ABC, abstractmethod
+
+import numpy as np
+from pandas.core.series import Series as PandasSeries
+
+import uuid
+from datetime import datetime
+
+from pandas.core.series import Series
+from pydantic import BaseModel
+
+from dijkies.executors import State
+
+
+class PerformanceInformationRow(BaseModel):
+    id: str = str(uuid.uuid4())
+    candle_time: datetime
+    candle_open: float
+    candle_high: float
+    candle_low: float
+    candle_close: float
+    buy_orders: list = []
+    sell_orders: list = []
+    balance_total_base: float
+    balance_total_quote: float
+    balance_available_base: float
+    balance_available_quote: float
+    balance_base_on_hold: float
+    balance_quote_on_hold: float
+    total_fee_paid: float
+    total_value_strategy: float
+    roi_strategy: float
+    roi_strategy_per_month: float
+    total_value_hodl: float
+    roi_hodl: float
+    roi_hodl_per_month: float
+    number_of_transactions: int
+    absolute_profit: float
+
+    @classmethod
+    def from_objects(
+        cls,
+        candle: Series,
+        start_candle: Series,
+        state: State,
+        initialization_value_in_quote: float,
+    ) -> "PerformanceInformationRow":
+        strategy_value = state.total_value_in_quote(candle.close)
+        hodl_value = (candle.close / start_candle.open) * initialization_value_in_quote
+
+        roi_strategy = ((strategy_value / initialization_value_in_quote) - 1) * 100
+        roi_hodl = ((candle.close / start_candle.open) - 1) * 100
+
+        duration_in_months = (candle.time - start_candle.time).total_seconds() / (
+            60 * 60 * 24 * 30
+        )
+
+        strategy_per_month = (roi_strategy / 100 + 1) ** (
+            1 / max(duration_in_months, 0.01)
+        )
+        hodl_per_month = (roi_hodl / 100 + 1) ** (1 / max(duration_in_months, 0.01))
+
+        return cls(
+            candle_time=candle.time,
+            candle_open=candle.open,
+            candle_high=candle.high,
+            candle_low=candle.low,
+            candle_close=candle.close,
+            buy_orders=state.buy_orders,
+            sell_orders=state.sell_orders,
+            balance_total_base=state.total_base,
+            balance_total_quote=state.total_quote,
+            balance_available_base=state.base_available,
+            balance_available_quote=state.quote_available,
+            balance_base_on_hold=state.base_on_hold,
+            balance_quote_on_hold=state.quote_on_hold,
+            total_fee_paid=state.total_fee_paid,
+            total_value_strategy=strategy_value,
+            roi_strategy=roi_strategy,
+            roi_strategy_per_month=strategy_per_month,
+            total_value_hodl=hodl_value,
+            roi_hodl=roi_hodl,
+            roi_hodl_per_month=hodl_per_month,
+            number_of_transactions=state.number_of_transactions,
+            absolute_profit=strategy_value - initialization_value_in_quote,
+        )
+
+
+class Metric(ABC):
+    @property
+    @abstractmethod
+    def metric_name(self) -> str:
+        pass
+
+    @abstractmethod
+    def calculate(self, time_series: PandasSeries) -> float:
+        pass
+
+
+class DrawDown(Metric):
+    @property
+    def metric_name(self) -> str:
+        return "draw_down"
+
+    def calculate(self, time_series: PandasSeries) -> float:
+        returns = time_series.pct_change()
+        returns.fillna(0.0, inplace=True)
+
+        cumulative = (returns + 1).cumprod()
+        running_max = np.maximum.accumulate(cumulative)
+
+        result = ((cumulative - running_max) / running_max).min() * 100
+
+        return result
+
+
+class ReturnOnInvestment(Metric):
+    @property
+    def metric_name(self) -> str:
+        return "roi"
+
+    def calculate(self, time_series: PandasSeries) -> float:
+        return ((time_series.iloc[-1] / time_series.iloc[0]) - 1) * 100
+
+
+class NormalizedReturnOnInvestment(Metric):
+    def __init__(self, candle_interval_in_minutes: int) -> None:
+        self.candle_interval_in_minutes = candle_interval_in_minutes
+
+    @property
+    def metric_name(self) -> str:
+        return "normalized_roi"
+
+    def calculate(self, time_series: PandasSeries) -> float:
+        """
+        returns the average return per month.
+        """
+        total_time_in_minutes = len(time_series) * self.candle_interval_in_minutes
+        total_time_in_months = total_time_in_minutes / (60 * 24 * 30)
+
+        total_return = time_series.iloc[-1] / time_series.iloc[0]
+        return_per_month = total_return ** (min(1 / total_time_in_months, 1))
+
+        return (return_per_month - 1) * 100
+
+
+class SharpeRatio(Metric):
+    def __init__(
+        self, risk_free_rate_per_year: float, candle_interval_in_minutes: int
+    ) -> None:
+        self.risk_free_rate_per_year = risk_free_rate_per_year
+        self.candle_interval_in_minutes = candle_interval_in_minutes
+
+    @property
+    def metric_name(self) -> str:
+        return "sharpe_ratio"
+
+    def calculate(self, time_series: PandasSeries) -> float:
+        risk_free_rate_per_day = (1 + self.risk_free_rate_per_year) ** (1 / 365) - 1
+        measurements_per_day = 60 * 24 / self.candle_interval_in_minutes
+        normalized_std_return = risk_free_rate_per_day / max(measurements_per_day, 1)
+        returns = time_series.pct_change()
+        excess_return = returns.mean() - normalized_std_return
+        volatility = max(returns.std(), 0.00001)
+        sharpe_ratio = excess_return / volatility
+        return sharpe_ratio * np.sqrt(measurements_per_day)

dijkies/strategy.py

@@ -0,0 +1,68 @@
+import inspect
+from abc import ABC, abstractmethod
+
+from pandas.core.frame import DataFrame as PandasDataFrame
+
+from dijkies.executors import ExchangeAssetClient
+from dijkies.data_pipeline import DataPipeline
+
+
+class Strategy(ABC):
+    def __init__(
+        self,
+        executor: ExchangeAssetClient,
+    ) -> None:
+        self.executor = executor
+        self.state = self.executor.state
+
+    @abstractmethod
+    def execute(self, data: PandasDataFrame) -> None:
+        pass
+
+    def run(self, data: PandasDataFrame) -> None:
+        self.executor.update_state()
+        self.execute(data)
+
+    @classmethod
+    def _get_strategy_params(cls) -> list[str]:
+        subclass_sig = inspect.signature(cls.__init__)
+        base_sig = inspect.signature(Strategy.__init__)
+
+        subclass_params = {
+            name: p for name, p in subclass_sig.parameters.items() if name != "self"
+        }
+        base_params = {
+            name: p for name, p in base_sig.parameters.items() if name != "self"
+        }
+
+        unique_params = {
+            name: p for name, p in subclass_params.items() if name not in base_params
+        }
+
+        return list(unique_params.keys())
+
+    def params_to_json(self):
+        params = self._get_strategy_params()
+        return {p: getattr(self, p) for p in params}
+
+    def __getstate__(self):
+        state = self.__dict__.copy()
+        state["executor"] = None
+        state["data_pipeline"] = None
+        return state
+
+    @property
+    @abstractmethod
+    def analysis_dataframe_size_in_minutes(self) -> int:
+        pass
+
+    @property
+    @abstractmethod
+    def exchange(self) -> str:
+        pass
+
+    def get_data_pipeline(self) -> DataPipeline:
+        """
+        implement this method for deployement
+        """
+        raise NotImplementedError()

dijkies-0.0.3.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.3
+Name: dijkies
+Version: 0.0.3
+Summary: A python framework that can be used to create, test and deploy trading algorithms.
+Author: Arnold Dijk
+Author-email: Arnold Dijk <arnold.dijk@teamrockstars.nl>
+License: MIT
+Requires-Dist: mlflow>=3.7.0
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pre-commit>=4.5.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: python-binance>=1.0.33
+Requires-Dist: python-bitvavo-api>=1.4.3
+Requires-Dist: ta>=0.11.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Dijkies
+
+**Dijkies** is a Python framework for creating, testing, and deploying algorithmic trading strategies in a clean, modular, and exchange-agnostic way.
+
+The core idea behind Dijkies is to **separate trading logic from execution and infrastructure**, allowing the same strategy code to be reused for:
+
+- Historical backtesting
+- Paper trading
+- Live trading
+
+## Philosophy
+
+In Dijkies, a strategy is responsible only for **making decisions** — when to buy, when to sell, and how much. Everything else, such as order execution, fee calculation, balance management, and exchange communication, is handled by dedicated components.
+
+This separation ensures that strategies remain:
+
+- Easy to reason about
+- Easy to test
+- Easy to reuse across environments
+
+A strategy written once can be backtested on historical data and later deployed to a real exchange without modification.
+
+## How It Works
+
+At a high level, Dijkies operates as follows:
+
+1. Market data (candles) is fetched from an exchange or data provider
+2. A rolling window of historical data is passed to a strategy
+3. The strategy analyzes the data and generates buy/sell signals
+4. Orders are placed through a standardized execution interface
+5. Account state is updated accordingly
+6. Results are collected (during backtesting) or executed live
+
+
+## Key Design Principles
+
+- **Strategy–Executor separation**  
+  Trading logic is completely decoupled from execution logic.
+
+- **Single interface for backtesting and live trading**  
+  Switching between backtesting and live trading requires no strategy changes.
+
+- **Explicit state management**  
+  All balances and positions are tracked in a transparent `State` object.
+
+- **Minimal assumptions**  
+  Dijkies does not enforce indicators, timeframes, or asset types.
+
+- **Composable and extensible**  
+  New exchanges, execution models, and risk layers can be added easily.
+
+## Who Is This For?
+
+Dijkies is designed for:
+
+- Developers building algorithmic trading systems
+- Quantitative traders who want full control over strategy logic
+- Anyone who wants to move from backtesting to production without rewriting code
+
+## What Dijkies Is Not
+
+- A no-code trading bot
+- A black-box strategy optimizer
+- A fully managed trading platform
+
+Dijkies provides the **building blocks**, not the trading edge.
+
+---
+
+## Quick Start
+
+This quick start shows how to define a strategy, fetch market data, and run a backtest in just a few steps.
+
+### 1. Define a Strategy
+
+A strategy is a class that inherits from `Strategy` and implements the `execute` method.  
+It receives a rolling dataframe of candles and decides when to place orders.
+
+```python
+from dijkies.strategy import Strategy
+from dijkies.executors import ExchangeAssetClient
+from ta.momentum import RSIIndicator
+import pandas as pd
+
+
+class RSIStrategy(Strategy):
+    # Amount of historical data passed into execute()
+    analysis_dataframe_size_in_minutes = 60 * 24 * 30  # 30 days
+
+    def __init__(
+        self,
+        executor: ExchangeAssetClient,
+        lower_threshold: float,
+        higher_threshold: float,
+    ) -> None:
+        self.lower_threshold = lower_threshold
+        self.higher_threshold = higher_threshold
+        super().__init__(executor)
+
+    def execute(self, candle_df: pd.DataFrame) -> None:
+        candle_df["rsi"] = RSIIndicator(candle_df.close).rsi()
+
+        previous = candle_df.iloc[-2]
+        current = candle_df.iloc[-1]
+
+        # Buy when RSI crosses below lower threshold
+        if previous.rsi > self.lower_threshold and current.rsi < self.lower_threshold:
+            self.executor.place_market_buy_order(
+                self.executor.state.base,
+                self.executor.state.quote_available,
+            )
+
+        # Sell when RSI crosses above higher threshold
+        if previous.rsi < self.higher_threshold and current.rsi > self.higher_threshold:
+            self.executor.place_market_sell_order(
+                self.executor.state.base,
+                self.executor.state.base_available,
+            )
+```
+
+### 2. fetch data for your backtest
+Market data is provided as a pandas DataFrame containing OHLCV candles.
+
+```python
+from dijkies.exchange_market_api import BitvavoMarketAPI
+
+market_api = BitvavoMarketAPI()
+candle_df = market_api.get_candles(base="XRP", lookback_in_minutest=60*24*365)
+```
+
+### 3. Set Up State and BacktestingExecutor
+Market data is provided as a pandas DataFrame containing OHLCV candles.
+
+```python
+from dijkies.executors import BacktestExchangeAssetClient, State
+
+state = State(
+    base="XRP",
+    total_base=0,
+    total_quote=1000,
+)
+
+executor = BacktestExchangeAssetClient(
+    state=state,
+    fee_limit_order=0.0015,
+    fee_market_order=0.0025,
+)
+```
+
+### 4. Run the Backtest
+
+Use the Backtester to run the strategy over historical data.
+
+```python
+from dijkies.backtest import Backtester
+
+strategy = RSIStrategy(
+    executor=executor,
+    lower_threshold=35,
+    higher_threshold=65,
+)
+
+backtester = Backtester()
+
+results = backtester.run(
+    candle_df=candle_df,
+    strategy=strategy,
+)
+
+results.total_value_strategy.plot()
+results.total_value_hodl.plot()
+```

dijkies-0.0.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+dijkies/__init__.py,sha256=FmmEOqu9R1gE1wBWWIrAIFTF1rI5sEjpsCdrw4RC5Z8,167
+dijkies/backtest.py,sha256=Z3U8pijdNwGh_h4dlPtORk3znIOBlTKOaGR-IK-swys,3206
+dijkies/credentials.py,sha256=pwhRsTFnaDOinnRwnplnxAIDS778dPd2awFDmjo3dpY,104
+dijkies/data_pipeline.py,sha256=SK5NCpI5okhwiPOAPTzoDVLgqPH6SGPsT4khNXcf7jI,313
+dijkies/deployment.py,sha256=N8xtF2YTU1wA0RAcwVmJEaXKZnNH94XjutIs7aOFyYo,3638
+dijkies/evaluate.py,sha256=52H87f4E7-1eTDN2CLSKkswtydTIeDSMZdCoXo56woA,8064
+dijkies/exceptions.py,sha256=BLqK0-rmpqx3wtZ8abu19u8ClnsAjkcpz4B22p-YYt0,1907
+dijkies/exchange_market_api.py,sha256=ZH2gD_Z7PkX3KLT1GtG20Xr-bacj4B3IGsJNP7Hz5AE,7606
+dijkies/executors.py,sha256=7GJznhlv2WMP6UjqQeE6s9VQsvzD0Y0okXdJd4rmMdk,20896
+dijkies/logger.py,sha256=yrxNyzriXO_WITRsIEWkVQeqLRavHVklFainDO18p7Y,432
+dijkies/performance.py,sha256=1EoGx0_riiAyOP8G7UQcYwmjt8b8hw4c3UzAgsbpOuE,5416
+dijkies/strategy.py,sha256=4UZpuZcDvtol6RbarUw-K846bZritSDqDirz9w8ycPw,1804
+dijkies-0.0.3.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
+dijkies-0.0.3.dist-info/METADATA,sha256=zgh4Zr4w3-yFTLg0le_rKDHMIsMpltd68ZT9AAkTx1w,5717
+dijkies-0.0.3.dist-info/RECORD,,

dijkies-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.18
+Root-Is-Purelib: true
+Tag: py3-none-any