pathforge 0.1.0__tar.gz

pathforge-0.1.0/PKG-INFO

@@ -0,0 +1,3 @@
+Metadata-Version: 2.4
+Name: pathforge
+Version: 0.1.0

pathforge-0.1.0/README.md

@@ -0,0 +1,101 @@
+# 🔥 pathforge
+
+> Simulate realistic financial markets from historical price data — for strategy testing, research, and risk analysis.
+
+[![PyPI version](https://img.shields.io/pypi/v/pathforge.svg)](https://pypi.org/project/pathforge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/franmanz/pathforge/blob/main/LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+
+## Why pathforge?
+
+Testing a trading strategy on a single historical price series tells you how it performed on **one specific path** the market happened to take. That's not enough. A robust strategy should work across the full range of outcomes the market could have produced.
+
+`pathforge` learns the statistical behaviour of any asset from its historical prices and generates hundreds of realistic alternative price paths. Test your strategy across all of them and you'll know how robust it really is.
+
+## Installation
+```bash
+pip install pathforge
+```
+
+To use the built-in plot functionality:
+```bash
+pip install pathforge[examples]
+```
+
+## Quick Start
+```python
+import pathforge as pf
+import yfinance as yf
+
+# Download historical price data
+ticker = yf.Ticker("AAPL")
+prices = ticker.history(period="5y")["Close"]
+
+# Create a forge and fit a model
+forge = pf.PathForge(prices)
+forge.fit(model="garch")
+
+# Simulate one year of trading days across 100 paths
+sim = forge.simulate(days=252, n_paths=100, seed=42)
+
+# Explore the results
+sim.summary()
+sim.plot()
+
+# Get the paths as a DataFrame for your own analysis
+df = sim.to_dataframe()  # shape: (253, 100)
+```
+
+## Models
+
+| Model | `model=` | Best for |
+|---|---|---|
+| Geometric Brownian Motion | `"gbm"` | Fast baseline, simple assumptions |
+| GARCH(1,1) | `"garch"` | Realistic volatility clustering |
+| Block Bootstrap | `"bootstrap"` | Non-parametric, no distributional assumptions |
+| Merton Jump Diffusion | `"jump_diffusion"` | Capturing sudden crashes and spikes |
+
+### Which model should I use?
+
+- **GBM** — good sanity check, fast, but underestimates tail risk
+- **GARCH** — best for most use cases, captures the volatility clustering seen in real markets
+- **Bootstrap** — most honest for strategy testing, resamples real historical behaviour directly
+- **Jump Diffusion** — best when your data contains sudden large moves you want to preserve
+
+## API Reference
+
+### `PathForge(data)`
+
+The main class. Pass a `pd.Series` or `pd.DataFrame` of daily closing prices.
+
+| Method | Description |
+|---|---|
+| `.fit(model="garch")` | Fit a simulation model to the historical data |
+| `.simulate(days=252, n_paths=100, start_price=None, seed=None)` | Generate simulated price paths |
+
+### `SimulationResult`
+
+Returned by `.simulate()`. 
+
+| Attribute / Method | Description |
+|---|---|
+| `.paths` | `np.ndarray` of shape `(days+1, n_paths)` |
+| `.to_dataframe()` | Paths as a `pd.DataFrame`, one column per path |
+| `.summary()` | Print statistical summary of the simulation |
+| `.plot(max_paths=50)` | Plot simulated paths with historical context |
+
+## Roadmap
+
+- [ ] Poisson jump diffusion ✅
+- [ ] Intraday timeframes (1m, 5m, 15m, 1h)
+- [ ] Multi-asset correlated simulation
+- [ ] Regime switching model
+- [ ] CLI: `pathforge simulate AAPL --days 252 --paths 500`
+
+## Contributing
+
+PRs and issues welcome at [github.com/franmanz/pathforge](https://github.com/franmanz/pathforge).
+
+## License
+
+MIT © 2026 franmanz

pathforge-0.1.0/pathforge/__init__.py

@@ -0,0 +1,6 @@
+from pathforge.forge import PathForge
+from pathforge.result import SimulationResult
+
+__version__ = "0.1.0"
+
+__all__ = ["PathForge", "SimulationResult"]

pathforge-0.1.0/pathforge/forge.py

@@ -0,0 +1,97 @@
+import numpy as np
+import pandas as pd
+from pathforge.result import SimulationResult
+
+## MAIN CLASS
+class PathForge:
+    """
+    Fits a statistical model to historical price data and generates
+    simulated future price paths.
+    """
+    def __init__(self, data):
+        self._prices = self._extract_prices(data)
+        self._returns = self._prices.pct_change().dropna()
+        self._model = None
+        self._fitted = False
+
+    def _extract_prices(self, data):
+        if isinstance(data, pd.Series):
+            return data.dropna()
+        if isinstance(data, pd.DataFrame):
+            return data.iloc[:, 0].dropna()
+        raise TypeError("data must be a pandas Series or DataFrame")
+    
+    def fit(self, model="garch"):
+        """
+        Fit a simulation model to the historical price data.
+
+        Parameters
+        ----------
+        model : str
+            "gbm", "garch", or "bootstrap"
+        """
+        if model == "gbm":
+            from pathforge.models.gbm import GBMModel
+            self._model = GBMModel(self._returns)
+        elif model == "garch":
+            from pathforge.models.garch import GARCHModel
+            self._model = GARCHModel(self._returns)
+        elif model == "bootstrap":
+            from pathforge.models.bootstrap import BlockBootstrapModel
+            self._model = BlockBootstrapModel(self._returns)
+        elif model == "jump_diffusion":
+            from pathforge.models.jump_diffusion import JumpDiffusionModel
+            self._model = JumpDiffusionModel(self._returns) 
+        else:
+            raise ValueError(f"Unknown model '{model}'. Choose from: gbm, garch, bootstrap")
+
+        self._model.fit()
+        self._fitted = True
+        return self #allows forge.fit("garch").simulate(...) in one line etc.
+
+    #Simulation method
+    def simulate(self, days=252, n_paths=100, start_price=None, seed=None):
+        """
+        Generate simulated price paths.
+
+        Parameters
+        ----------
+        days : int
+            Number of trading days to simulate. 252 is one trading year.
+        n_paths : int
+            Number of independent paths to generate.
+        start_price : float, optional
+            Starting price. Defaults to the last observed price.
+        seed : int, optional
+            Random seed for reproducibility.
+        """
+        if not self._fitted:
+            raise RuntimeError("Call .fit() before .simulate()")
+
+        if seed is not None:
+            np.random.seed(seed)
+
+        if start_price is None:
+            start_price = float(self._prices.iloc[-1])
+
+        returns_matrix = self._model.sample(days=days, n_paths=n_paths)
+        price_paths = self._build_price_paths(returns_matrix, start_price)
+
+        return SimulationResult(price_paths, historical_prices=self._prices, model_name=self._model.__class__.__name__)
+
+    #Build price paths is reverse of pct_change()
+    def _build_price_paths(self, returns_matrix, start_price):
+        """Convert a matrix of returns into price paths."""
+        n_days, n_paths = returns_matrix.shape
+        price_paths = np.empty((n_days + 1, n_paths))
+        price_paths[0] = start_price
+        for t in range(n_days):
+            price_paths[t + 1] = price_paths[t] * (1 + returns_matrix[t])
+        return price_paths
+    
+
+    
+
+        
+
+

pathforge-0.1.0/pathforge/models/__init__.py

@@ -0,0 +1,6 @@
+from pathforge.models.gbm import GBMModel
+from pathforge.models.garch import GARCHModel
+from pathforge.models.bootstrap import BlockBootstrapModel
+from pathforge.models.jump_diffusion import JumpDiffusionModel
+
+__all__ = ["GBMModel", "GARCHModel", "BlockBootstrapModel", "JumpDiffusionModel"]

pathforge-0.1.0/pathforge/models/base.py

@@ -0,0 +1,18 @@
+import numpy as np
+import pandas as pd
+
+
+class BaseModel:
+    """Base class for all PathForge simulation models."""
+
+    def __init__(self, returns):
+        self.returns = returns.values.astype(float)
+        self.params_ = {}
+
+    def fit(self):
+        raise NotImplementedError
+
+    def sample(self, days, n_paths):
+        raise NotImplementedError
+    
+    

pathforge-0.1.0/pathforge/models/bootstrap.py

@@ -0,0 +1,58 @@
+import numpy as np
+from pathforge.models.base import BaseModel
+
+
+class BlockBootstrapModel(BaseModel):
+    """
+    Block Bootstrap model.
+
+    Resamples contiguous blocks of historical returns to generate
+    simulated paths. Makes no distributional assumptions — the
+    simulated paths are built entirely from real historical data.
+    """
+
+    def __init__(self, returns, block_size=None):
+        super().__init__(returns)
+        self._block_size_override = block_size
+
+    def fit(self):
+        if self._block_size_override is not None:
+            block_size = self._block_size_override
+        else:
+            block_size = self._estimate_block_size()
+
+        self.params_["block_size"] = block_size
+
+    def sample(self, days, n_paths):
+        block_size = self.params_["block_size"]
+        n = len(self.returns)
+        simulated = np.empty((days, n_paths))
+
+        for path in range(n_paths):
+            path_returns = []
+            while len(path_returns) < days:
+                start = np.random.randint(0, n - block_size + 1)
+                block = self.returns[start: start + block_size]
+                remaining = days - len(path_returns)
+                path_returns.extend(block[:remaining].tolist())
+            simulated[:, path] = path_returns
+
+        return simulated
+
+    def _estimate_block_size(self):
+        """Estimate block size from the autocorrelation of squared returns."""
+        sq_returns = self.returns ** 2
+        n = len(sq_returns)
+        max_lag = min(50, n // 5)
+        threshold = 1.96 / np.sqrt(n)
+
+        acf = np.array([
+            np.corrcoef(sq_returns[:-lag], sq_returns[lag:])[0, 1]
+            for lag in range(1, max_lag + 1)
+        ])
+
+        significant_lags = np.where(np.abs(acf) > threshold)[0]
+
+        if len(significant_lags) == 0:
+            return 10
+        return max(10, int(significant_lags[-1]) + 1)

pathforge-0.1.0/pathforge/models/garch.py

@@ -0,0 +1,49 @@
+import numpy as np
+import warnings
+from pathforge.models.base import BaseModel
+
+
+class GARCHModel(BaseModel):
+    """
+    GARCH(1,1) model.
+
+    Captures volatility clustering — the tendency for large price
+    moves to be followed by more large moves.
+    """
+
+    def fit(self):
+        try:
+            from arch import arch_model
+        except ImportError:
+            raise ImportError("Install arch to use GARCH: pip install arch")
+
+        pct_returns = self.returns * 100
+
+        am = arch_model(pct_returns, mean="Constant", vol="GARCH", p=1, q=1)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            result = am.fit(disp="off")
+
+        params = result.params
+        self.params_["mu"] = float(params["mu"]) / 100
+        self.params_["omega"] = float(params["omega"]) / 10000
+        self.params_["alpha"] = float(params["alpha[1]"])
+        self.params_["beta"] = float(params["beta[1]"])
+
+    def sample(self, days, n_paths):
+        mu = self.params_["mu"]
+        omega = self.params_["omega"]
+        alpha = self.params_["alpha"]
+        beta = self.params_["beta"]
+
+        hist_var = np.var(self.returns)
+        simulated = np.empty((days, n_paths))
+
+        for path in range(n_paths):
+            sigma2 = hist_var
+            for t in range(days):
+                eps = np.random.normal(0, np.sqrt(sigma2))
+                simulated[t, path] = mu + eps
+                sigma2 = omega + alpha * eps**2 + beta * sigma2
+
+        return simulated

pathforge-0.1.0/pathforge/models/gbm.py

@@ -0,0 +1,26 @@
+import numpy as np
+from pathforge.models.base import BaseModel
+
+
+class GBMModel(BaseModel):
+    """
+    Geometric Brownian Motion model.
+
+    Fits a normal distribution to historical log-returns,
+    then simulates new returns using that distribution.
+    """
+
+    def fit(self):
+        log_returns = np.log1p(self.returns)
+        self.params_["mu"] = float(log_returns.mean())
+        self.params_["sigma"] = float(log_returns.std())
+
+    def sample(self, days, n_paths):
+        mu = self.params_["mu"]
+        sigma = self.params_["sigma"]
+
+        Z = np.random.standard_normal((days, n_paths))
+        log_returns = (mu - 0.5 * sigma**2) + sigma * Z
+        return np.expm1(log_returns)
+    
+    

pathforge-0.1.0/pathforge/models/jump_diffusion.py

@@ -0,0 +1,62 @@
+import numpy as np
+from pathforge.models.base import BaseModel
+
+
+class JumpDiffusionModel(BaseModel):
+    """
+    Merton Jump Diffusion model.
+
+    Extends GBM by adding a Poisson jump component to capture
+    sudden large price moves such as crashes or earnings surprises.
+
+    Parameters
+    ----------
+    returns : pd.Series
+        Daily simple returns.
+    jump_threshold : float
+        Number of standard deviations beyond which a historical
+        return is classified as a jump. Default is 3.
+    """
+
+    def __init__(self, returns, jump_threshold=3.0):
+        super().__init__(returns)
+        self.jump_threshold = jump_threshold
+
+    def fit(self):
+        # Step 1 — fit the GBM component on normal days
+        std = self.returns.std()
+        jump_mask = np.abs(self.returns) > self.jump_threshold * std
+
+        normal_returns = self.returns[~jump_mask]
+        jump_returns = self.returns[jump_mask]
+
+        log_normal = np.log1p(normal_returns)
+        self.params_["mu"] = float(log_normal.mean())
+        self.params_["sigma"] = float(log_normal.std())
+
+        # Step 2 — fit the jump component
+        n_days = len(self.returns)
+        self.params_["lambda"] = float(len(jump_returns) / n_days)
+        self.params_["mu_j"] = float(jump_returns.mean()) if len(jump_returns) > 0 else 0.0
+        self.params_["sigma_j"] = float(jump_returns.std()) if len(jump_returns) > 1 else 0.01
+
+    
+    def sample(self, days, n_paths):
+        mu = self.params_["mu"]
+        sigma = self.params_["sigma"]
+        lam = self.params_["lambda"]
+        mu_j = self.params_["mu_j"]
+        sigma_j = self.params_["sigma_j"]
+
+        # GBM component
+        Z = np.random.standard_normal((days, n_paths))
+        log_returns = (mu - 0.5 * sigma**2) + sigma * Z
+
+        # Jump component
+        jumps_occur = np.random.poisson(lam, (days, n_paths))
+        jump_sizes = np.random.normal(mu_j, sigma_j, (days, n_paths))
+        jump_component = jumps_occur * jump_sizes
+
+        return np.expm1(log_returns + jump_component)
+    
+    

pathforge-0.1.0/pathforge/result.py

@@ -0,0 +1,96 @@
+import numpy as np
+import pandas as pd
+
+
+class SimulationResult:
+    """
+    The output of a PathForge simulation.
+
+    Attributes
+    ----------
+    paths : np.ndarray, shape (days+1, n_paths)
+        Simulated price paths. Row 0 is the starting price.
+    """
+
+    def __init__(self, paths, historical_prices=None, model_name=""):
+        self.paths = paths
+        self.historical_prices = historical_prices
+        self.model_name = model_name
+
+    def to_dataframe(self):
+        """Return simulated paths as a pandas DataFrame."""
+        n_paths = self.paths.shape[1]
+        columns = [f"path_{i}" for i in range(n_paths)]
+        return pd.DataFrame(self.paths, columns=columns)
+
+    def summary(self):
+        """Print a statistical summary of the simulated paths."""
+        start = self.paths[0, 0]
+        final = self.paths[-1, :]
+        returns = (final - start) / start
+
+        print(f"Paths         : {self.paths.shape[1]}")
+        print(f"Days          : {self.paths.shape[0] - 1}")
+        print(f"Start price   : {start:.4f}")
+        print(f"")
+        print(f"Final price distribution:")
+        print(f"  Mean        : {final.mean():.4f}")
+        print(f"  Median      : {np.median(final):.4f}")
+        print(f"  Std         : {final.std():.4f}")
+        print(f"  5th pct     : {np.percentile(final, 5):.4f}")
+        print(f"  95th pct    : {np.percentile(final, 95):.4f}")
+        print(f"")
+        print(f"Return distribution:")
+        print(f"  Mean        : {returns.mean():.2%}")
+        print(f"  Median      : {np.median(returns):.2%}")
+        print(f"  5th pct     : {np.percentile(returns, 5):.2%}")
+        print(f"  95th pct    : {np.percentile(returns, 95):.2%}")
+
+    def plot(self, max_paths=50):
+        """
+        Plot simulated price paths.
+
+        Parameters
+        ----------
+        max_paths : int
+            Maximum number of paths to draw. Defaults to 50.
+        """
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError:
+            raise ImportError("Install matplotlib to use .plot(): pip install matplotlib")
+
+        n = min(max_paths, self.paths.shape[1])
+        fig, ax = plt.subplots(figsize=(12, 6))
+
+        for i in range(n):
+            ax.plot(self.paths[:, i], alpha=0.3, lw=0.8, color="steelblue")
+
+        median_path = np.median(self.paths, axis=1)
+        ax.plot(median_path, color="darkblue", lw=2, label="Median path")
+
+        p5 = np.percentile(self.paths, 5, axis=1)
+        p95 = np.percentile(self.paths, 95, axis=1)
+        ax.fill_between(range(len(p5)), p5, p95, alpha=0.15, color="steelblue", label="5–95th percentile")
+
+        if self.historical_prices is not None:
+            hist = self.historical_prices[-126:]
+            hist_normalised = hist / hist.iloc[-1] * self.paths[0, 0]
+            ax.plot(
+                range(-len(hist), 0),
+                hist_normalised.values,
+                color="red",
+                lw=1.5,
+                label="Historical",
+                zorder=5
+            )
+
+        ax.set_title(f"PathForge Simulation — {self.model_name} ({self.paths.shape[1]} paths)")
+        ax.set_xlabel("Days")
+        ax.set_ylabel("Price")
+        ax.grid()
+        ax.legend()
+        plt.tight_layout()
+        plt.show()
+
+    

pathforge-0.1.0/pathforge.egg-info/PKG-INFO

@@ -0,0 +1,3 @@
+Metadata-Version: 2.4
+Name: pathforge
+Version: 0.1.0

pathforge-0.1.0/pathforge.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+pathforge/__init__.py
+pathforge/forge.py
+pathforge/result.py
+pathforge.egg-info/PKG-INFO
+pathforge.egg-info/SOURCES.txt
+pathforge.egg-info/dependency_links.txt
+pathforge.egg-info/top_level.txt
+pathforge/models/__init__.py
+pathforge/models/base.py
+pathforge/models/bootstrap.py
+pathforge/models/garch.py
+pathforge/models/gbm.py
+pathforge/models/jump_diffusion.py
+tests/test_pathforge.py

pathforge-0.1.0/pathforge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pathforge-0.1.0/pathforge.egg-info/top_level.txt

@@ -0,0 +1 @@
+pathforge

pathforge-0.1.0/pyproject.toml

@@ -0,0 +1,11 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pathforge"
+version = "0.1.0"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pathforge*"]

pathforge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pathforge-0.1.0/tests/test_pathforge.py

@@ -0,0 +1,77 @@
+import numpy as np
+import pandas as pd
+import pytest
+import pathforge as pf
+
+
+@pytest.fixture
+def price_series():
+    np.random.seed(0)
+    returns = np.random.normal(0.0005, 0.015, 500)
+    prices = 100 * np.cumprod(1 + returns)
+    dates = pd.date_range("2020-01-01", periods=500, freq="B")
+    return pd.Series(prices, index=dates)
+
+def test_accepts_series(price_series):
+    forge = pf.PathForge(price_series)
+    assert len(forge._prices) == 500
+
+
+def test_accepts_dataframe(price_series):
+    df = pd.DataFrame({"close": price_series, "other": price_series * 1.1})
+    forge = pf.PathForge(df)
+    assert len(forge._prices) == 500
+
+
+def test_simulate_before_fit_raises(price_series):
+    forge = pf.PathForge(price_series)
+    with pytest.raises(RuntimeError):
+        forge.simulate()
+
+
+def test_invalid_model_raises(price_series):
+    forge = pf.PathForge(price_series)
+    with pytest.raises(ValueError):
+        forge.fit(model="nonexistent")
+
+
+@pytest.mark.parametrize("model", ["gbm", "garch", "bootstrap", "jump_diffusion"])
+def test_output_shape(price_series, model):
+    forge = pf.PathForge(price_series)
+    forge.fit(model=model)
+    sim = forge.simulate(days=252, n_paths=10, seed=42)
+    assert sim.paths.shape == (253, 10)
+
+
+@pytest.mark.parametrize("model", ["gbm", "garch", "bootstrap", "jump_diffusion"])
+def test_prices_always_positive(price_series, model):
+    forge = pf.PathForge(price_series)
+    forge.fit(model=model)
+    sim = forge.simulate(days=252, n_paths=10, seed=42)
+    assert np.all(sim.paths > 0)
+
+
+def test_reproducibility(price_series):
+    forge = pf.PathForge(price_series)
+    forge.fit(model="gbm")
+    sim1 = forge.simulate(days=100, n_paths=10, seed=1)
+    sim2 = forge.simulate(days=100, n_paths=10, seed=1)
+    np.testing.assert_array_equal(sim1.paths, sim2.paths)
+
+
+def test_start_price(price_series):
+    forge = pf.PathForge(price_series)
+    forge.fit(model="gbm")
+    sim = forge.simulate(days=10, n_paths=5, start_price=500.0, seed=0)
+    assert np.all(sim.paths[0] == 500.0)
+
+
+def test_to_dataframe(price_series):
+    forge = pf.PathForge(price_series)
+    forge.fit(model="gbm")
+    sim = forge.simulate(days=50, n_paths=5, seed=0)
+    df = sim.to_dataframe()
+    assert df.shape == (51, 5)
+    assert list(df.columns) == [f"path_{i}" for i in range(5)]
+
+