tam-quant 0.1.0__tar.gz

tam_quant-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: tam-quant
+Version: 0.1.0
+Summary: Config, data ingestion, and event-driven backtesting for stocks/indices
+Project-URL: Homepage, https://github.com/Huddie/Tam
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Requires-Dist: yfinance>=0.2
+Requires-Dist: plotly>=5.20
+Requires-Dist: pydantic>=2.6
+Requires-Dist: tulipy>=0.4.0
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: live
+Requires-Dist: dash>=2.17; extra == "live"
+Provides-Extra: llm
+Requires-Dist: mlx-lm>=0.31.3; extra == "llm"
+Provides-Extra: notebook
+Requires-Dist: dash>=2.17; extra == "notebook"
+
+# tam
+
+Config-driven event backtesting for stocks/indices: YAML in, an interactive
+HTML dashboard out. Strategies (moving-average, MA crossover, trend rotation,
+online-learning ML, local-LLM) are all pluggable — `examples/backtest.py`
+doesn't import any strategy directly, it builds whatever's listed in the
+config's `strategies:` section by name.
+
+Published on PyPI as `tam-quant` (`pip install tam-quant`; `import tam` either
+way). Running in Google Colab or Jupyter instead of this repo's own CLI? See
+[NOTEBOOK.md](NOTEBOOK.md).
+
+## Setup
+
+Requires [`uv`](https://docs.astral.sh/uv/) and Python 3.11 (pinned in
+`.python-version` — `uv` will fetch it automatically if you don't have it).
+
+```
+uv sync --extra dev
+```
+
+This creates `.venv/` and installs everything, including dev dependencies
+(pytest). Run any command below with `uv run ...` so it uses that environment
+— no need to activate the venv manually.
+
+If you want to use the FMP data provider instead of the (no-key-needed)
+yfinance default, copy `.env.example` to `.env` and fill in `FMP_API_KEY`.
+
+## Running the examples
+
+Each example is a YAML config passed to the same runner:
+
+```
+uv run python -m examples.backtest examples/moving_average_config.yaml
+uv run python -m examples.backtest examples/ma_crossover_config.yaml
+uv run python -m examples.backtest examples/trend_rotation_config.yaml
+```
+
+These three work out of the box — no extra setup, no external services. Each
+run prints a summary table (returns, Sharpe, drawdown, etc. per strategy)
+with a live progress bar, and writes an interactive HTML dashboard to
+`examples/output/<name>_report.html` — open that in a browser to see the
+equity curves, drawdown, and per-trade markers (toggle with the "Show
+Trades" button).
+
+`examples/llm_trading_config.yaml` is different: it drives a strategy that
+queries a local language model each simulated day, and by default also
+periodically LoRA fine-tunes it (both via `mlx-lm`, Apple Silicon only). The
+first run downloads the base model from Hugging Face (needs network once).
+Because it calls the model every simulated day, this one is much slower than
+the others — try a short date range first (edit `start`/`end` in the config)
+before running the full period. See the comments in that file for how to
+point it at Ollama or another server instead, or turn LoRA fine-tuning off.
+
+Want to try your own mix of strategies? Copy one of the configs and edit its
+`strategies:` list — see `tam/strategy/*.py` for what's registered and what
+params each one takes.
+
+## Running the tests
+
+```
+uv run pytest
+```
+
+No network access or external services required — everything is tested
+against fakes/mocks (fake data providers, a stubbed LLM client, etc.).

tam_quant-0.1.0/README.md

@@ -0,0 +1,66 @@
+# tam
+
+Config-driven event backtesting for stocks/indices: YAML in, an interactive
+HTML dashboard out. Strategies (moving-average, MA crossover, trend rotation,
+online-learning ML, local-LLM) are all pluggable — `examples/backtest.py`
+doesn't import any strategy directly, it builds whatever's listed in the
+config's `strategies:` section by name.
+
+Published on PyPI as `tam-quant` (`pip install tam-quant`; `import tam` either
+way). Running in Google Colab or Jupyter instead of this repo's own CLI? See
+[NOTEBOOK.md](NOTEBOOK.md).
+
+## Setup
+
+Requires [`uv`](https://docs.astral.sh/uv/) and Python 3.11 (pinned in
+`.python-version` — `uv` will fetch it automatically if you don't have it).
+
+```
+uv sync --extra dev
+```
+
+This creates `.venv/` and installs everything, including dev dependencies
+(pytest). Run any command below with `uv run ...` so it uses that environment
+— no need to activate the venv manually.
+
+If you want to use the FMP data provider instead of the (no-key-needed)
+yfinance default, copy `.env.example` to `.env` and fill in `FMP_API_KEY`.
+
+## Running the examples
+
+Each example is a YAML config passed to the same runner:
+
+```
+uv run python -m examples.backtest examples/moving_average_config.yaml
+uv run python -m examples.backtest examples/ma_crossover_config.yaml
+uv run python -m examples.backtest examples/trend_rotation_config.yaml
+```
+
+These three work out of the box — no extra setup, no external services. Each
+run prints a summary table (returns, Sharpe, drawdown, etc. per strategy)
+with a live progress bar, and writes an interactive HTML dashboard to
+`examples/output/<name>_report.html` — open that in a browser to see the
+equity curves, drawdown, and per-trade markers (toggle with the "Show
+Trades" button).
+
+`examples/llm_trading_config.yaml` is different: it drives a strategy that
+queries a local language model each simulated day, and by default also
+periodically LoRA fine-tunes it (both via `mlx-lm`, Apple Silicon only). The
+first run downloads the base model from Hugging Face (needs network once).
+Because it calls the model every simulated day, this one is much slower than
+the others — try a short date range first (edit `start`/`end` in the config)
+before running the full period. See the comments in that file for how to
+point it at Ollama or another server instead, or turn LoRA fine-tuning off.
+
+Want to try your own mix of strategies? Copy one of the configs and edit its
+`strategies:` list — see `tam/strategy/*.py` for what's registered and what
+params each one takes.
+
+## Running the tests
+
+```
+uv run pytest
+```
+
+No network access or external services required — everything is tested
+against fakes/mocks (fake data providers, a stubbed LLM client, etc.).

tam_quant-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "tam-quant"
+version = "0.1.0"
+description = "Config, data ingestion, and event-driven backtesting for stocks/indices"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pandas>=2.0",
+    "pyarrow>=14.0",
+    "pyyaml>=6.0",
+    "requests>=2.31",
+    "yfinance>=0.2",
+    "plotly>=5.20",
+    "pydantic>=2.6",
+    "tulipy>=0.4.0",
+    "scikit-learn>=1.7.2",
+    "rich>=13.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/Huddie/Tam"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+live = ["dash>=2.17"]
+# mlx-lm/mlx are Apple-Silicon-only (Metal) -- a hard dependency here would
+# make `pip install tam-quant` fail outright on Linux/Colab/Windows, not just
+# leave an unusable feature installed. Only tam.strategy.mlx_lora_client
+# needs this; every other strategy works fine without it (see
+# tam/strategy/__init__.py, which registers strategies defensively so a
+# missing optional dependency skips just that one strategy, not the whole
+# package).
+llm = ["mlx-lm>=0.31.3"]
+# Convenience bundle for a from-scratch notebook environment (Colab/Jupyter,
+# always Linux or a container -- never Apple Silicon in practice), so a user
+# doesn't have to separately learn about `live`: `pip install "tam-quant[notebook]"`.
+notebook = ["dash>=2.17"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[[tool.uv.index]]
+url = "https://pypi.apple.com/simple"
+default = true
+
+[tool.setuptools.packages.find]
+include = ["tam*"]

tam_quant-0.1.0/setup.cfg

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

tam_quant-0.1.0/tam/backtest/config.py

@@ -0,0 +1,29 @@
+"""Builds every strategy+portfolio in a backtest run from a config-driven list.
+
+Each entry in `backtest.strategies` names a strategy registered under
+(Strategy, name) in tam.registry.Registry, plus its own params — so which
+strategies run, and what they're compared against, is a config change, not a
+code change. New strategies just need one @Registry.register(Strategy, "name")
+adapter function (see tam/strategy/buy_and_hold.py for an example).
+"""
+from __future__ import annotations
+
+from typing import List, Tuple
+
+from ..data.repository import DataRepository
+from ..portfolio.portfolio import Portfolio
+from ..registry import Registry
+from ..strategy.base import Strategy
+
+
+def build_strategies(
+    repository: DataRepository, specs, default_cash: float
+) -> Tuple[List[Strategy], dict]:
+    strategies = []
+    portfolios = {}
+    for spec in specs:
+        cash = float(spec.cash) if "cash" in spec else default_cash
+        strategy = Registry.create(Strategy, spec.strategy, repository, spec.portfolio_id, spec.params, cash)
+        strategies.append(strategy)
+        portfolios[spec.portfolio_id] = Portfolio(spec.portfolio_id, cash=cash)
+    return strategies, portfolios

tam_quant-0.1.0/tam/backtest/harness.py

@@ -0,0 +1,168 @@
+"""Wires strategies, portfolios, and market data into a day-by-day event loop."""
+from __future__ import annotations
+
+import os
+import pickle
+import tempfile
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Sequence
+
+from ..data.repository import DataRepository
+from ..data.schema import CLOSE, OPEN
+from ..events.bus import EventBus
+from ..events.clock import Clock
+from ..events.types import ANNOTATION_TOPIC, State
+from ..portfolio.orders import PriceBasis
+from ..portfolio.portfolio import Portfolio
+from ..portfolio.registry import PortfolioRegistry
+from ..strategy.base import Strategy
+from ..trading.gateway import TradeGateway
+from .report import Report
+
+
+@dataclass(frozen=True)
+class Progress:
+    """How far a run has gotten: day_index is 1-based, so day_index == total_days
+    on the final simulated day."""
+
+    day_index: int
+    total_days: int
+    current_date: date
+
+    @property
+    def fraction(self) -> float:
+        return self.day_index / self.total_days if self.total_days else 1.0
+
+
+OnProgress = Callable[[Progress], None]
+
+
+class BacktestHarness:
+    def __init__(
+        self,
+        repository: DataRepository,
+        strategies: Sequence[Strategy],
+        portfolios: Dict[str, Portfolio],
+        dates: Sequence[date],
+    ):
+        self._repository = repository
+        self._bus = EventBus()
+        self._annotations: List[dict] = []
+        self._bus.subscribe(ANNOTATION_TOPIC, self._on_annotation)
+        self._portfolios = PortfolioRegistry(portfolios)
+        self._trader = TradeGateway(self._portfolios, self._price_on)
+        self._strategies = list(strategies)
+        for strategy in self._strategies:
+            strategy.bind(self._bus, self._trader, self._portfolios)
+        self._clock = Clock(dates, self._bus)
+
+    def _on_annotation(self, event) -> None:
+        self._annotations.append(dict(event.payload))
+
+    def _price_on(self, ticker: str, as_of: date, basis: PriceBasis = PriceBasis.CLOSE) -> float:
+        history = self._repository.query(ticker, end=as_of)
+        if history.empty:
+            raise LookupError(f"no price data for {ticker} on or before {as_of}")
+        column = OPEN if basis is PriceBasis.OPEN else CLOSE
+        return float(history.iloc[-1][column])
+
+    def run(
+        self,
+        on_progress: Optional[OnProgress] = None,
+        checkpoint_path: Optional[str] = None,
+        checkpoint_every: int = 1,
+    ) -> Report:
+        """Run the full date range. If checkpoint_path is given: resume from it if
+        it already exists (skipping every day already completed), and write a
+        fresh checkpoint every `checkpoint_every` completed days -- so a crash
+        (bad data, a flaky external model server, anything) loses at most that
+        many days of work, not the whole run. The checkpoint is removed on a
+        clean finish, since it exists purely to resume an interrupted run of
+        THIS exact strategies/portfolios/dates configuration -- rerunning the
+        same config from scratch after success should start fresh, not replay
+        a stale checkpoint from a previous, unrelated run.
+        """
+        snapshots: List[dict] = []
+        completed_days = 0
+        if checkpoint_path is not None and Path(checkpoint_path).exists():
+            completed_days, snapshots, self._annotations = self._load_checkpoint(checkpoint_path)
+
+        for strategy in self._strategies:
+            strategy.state_change(State.START)
+        for strategy in self._strategies:
+            strategy.state_change(State.RUNNING)
+
+        total_days = len(self._clock.dates)
+        for day_index, current_date in enumerate(self._clock.dates, start=1):
+            if day_index <= completed_days:
+                continue
+            self._trader.current_date = current_date
+            self._clock.tick(current_date)
+            snapshots.extend(self._snapshot(current_date))
+            if on_progress is not None:
+                on_progress(Progress(day_index, total_days, current_date))
+            if checkpoint_path is not None and day_index % checkpoint_every == 0:
+                self._write_checkpoint(checkpoint_path, day_index, snapshots)
+
+        for strategy in self._strategies:
+            strategy.state_change(State.END)
+
+        if checkpoint_path is not None:
+            Path(checkpoint_path).unlink(missing_ok=True)
+
+        return Report(snapshots, self._trades(), self._annotations)
+
+    def _write_checkpoint(self, checkpoint_path: str, day_index: int, snapshots: List[dict]) -> None:
+        state = {
+            "day_index": day_index,
+            "snapshots": snapshots,
+            "annotations": list(self._annotations),
+            "portfolios": {portfolio_id: p.get_state() for portfolio_id, p in self._portfolios.items()},
+            "strategies": [s.get_state() for s in self._strategies],
+        }
+        path = Path(checkpoint_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # Write-then-rename so a crash mid-write can't corrupt the last good checkpoint.
+        fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.")
+        with os.fdopen(fd, "wb") as handle:
+            pickle.dump(state, handle)
+        os.replace(tmp_name, path)
+
+    def _load_checkpoint(self, checkpoint_path: str) -> tuple[int, List[dict], List[dict]]:
+        with open(checkpoint_path, "rb") as handle:
+            state = pickle.load(handle)
+        for portfolio_id, portfolio_state in state["portfolios"].items():
+            self._portfolios[portfolio_id].load_state(portfolio_state)
+        for strategy, strategy_state in zip(self._strategies, state["strategies"]):
+            strategy.load_state(strategy_state)
+        return state["day_index"], state["snapshots"], state.get("annotations", [])
+
+    def _trades(self) -> List[dict]:
+        return [
+            {
+                "date": trade.date,
+                "portfolio": portfolio_id,
+                "ticker": trade.ticker,
+                "side": trade.side,
+                "qty": trade.qty,
+                "price": trade.price,
+            }
+            for portfolio_id, portfolio in self._portfolios.items()
+            for trade in portfolio.trades
+        ]
+
+    def _snapshot(self, as_of: date) -> List[dict]:
+        rows = []
+        for portfolio_id, portfolio in self._portfolios.items():
+            prices = {ticker: self._price_on(ticker, as_of) for ticker in portfolio.tickers}
+            rows.append(
+                {
+                    "date": as_of,
+                    "portfolio": portfolio_id,
+                    "cash": portfolio.cash,
+                    "value": portfolio.market_value(prices),
+                }
+            )
+        return rows

tam_quant-0.1.0/tam/backtest/live.py

@@ -0,0 +1,124 @@
+"""Live-updating view of an in-progress backtest.
+
+Polls the same checkpoint file BacktestHarness.run(checkpoint_path=...) already
+writes every `checkpoint_every` days -- the backtest loop itself needs zero
+awareness that anything is watching it. Kept out of visualization.py/report.py
+so those stay dependency-light; this module needs the `live` extra
+(`uv sync --extra live`, adds `dash`) since most runs just want the static
+HTML report from write_html and shouldn't need Dash installed for that.
+"""
+from __future__ import annotations
+
+import logging
+import pickle
+from pathlib import Path
+from typing import Dict, Optional
+
+import pandas as pd
+
+from .report import Report
+from .visualization import render
+
+
+def report_from_checkpoint(checkpoint_path: str) -> Optional[Report]:
+    """Reconstruct a partial Report from whatever's in the checkpoint right
+    now, or None if it doesn't exist yet (e.g. day 1 hasn't completed)."""
+    path = Path(checkpoint_path)
+    if not path.exists():
+        return None
+    with path.open("rb") as handle:
+        state = pickle.load(handle)
+
+    trades = [
+        {**trade, "portfolio": portfolio_id}
+        for portfolio_id, portfolio_state in state["portfolios"].items()
+        for trade in portfolio_state["trades"]
+    ]
+    return Report(state["snapshots"], trades, state.get("annotations", []))
+
+
+def serve(
+    checkpoint_path: str,
+    title: str = "Backtest (live)",
+    poll_seconds: float = 3.0,
+    port: int = 8050,
+    verbose: bool = False,
+    ticker_colors: Optional[Dict[str, str]] = None,
+    prices: Optional[Dict[str, "pd.Series"]] = None,
+    jupyter_mode: Optional[str] = None,
+) -> None:
+    """Blocking (unless `jupyter_mode` says otherwise -- see below): serves a
+    dashboard at http://127.0.0.1:<port> that re-reads the checkpoint every
+    `poll_seconds` and redraws the same figure visualization.render() would
+    produce for the final report -- just from whatever's completed so far.
+    Keeps showing the last good read after the checkpoint is removed on a
+    clean finish, rather than reverting to blank.
+
+    `jupyter_mode`: passed straight through to Dash's own `app.run()` --
+    None (default) behaves exactly as before (blocks, serves a normal HTTP
+    dashboard for a separate browser tab); "inline" renders the live-updating
+    dashboard directly in the current notebook cell's output instead, and
+    (like Dash's own inline mode) does NOT block -- `serve()` returns once
+    the server starts, while the dashboard keeps polling/updating
+    asynchronously in the output area. Use "external" if "inline" renders
+    blank (some notebook hosts, including Colab in certain configurations,
+    sandbox iframes in a way inline mode doesn't tolerate) -- it prints a
+    clickable link instead of embedding an iframe.
+
+    `prices`, if given, is the same already-fetched historical price data
+    write_html()'s optional top panel supports -- passed in whole, but
+    render() itself truncates each series to whatever date the equity/
+    drawdown panels have reached so far, so the price panel builds up in
+    lockstep with them instead of spoiling the ending upfront.
+
+    Flask/Werkzeug's per-request access log (one line per poll, forever) is
+    silenced by default -- it drowns out the rich progress display the
+    backtest itself is drawing in the same terminal. Pass verbose=True (or
+    --log-level verbose on the CLI) to see it, e.g. while debugging the live
+    server itself."""
+    try:
+        import dash
+        from dash import dcc, html
+        from dash.dependencies import Input, Output
+    except ImportError as exc:
+        raise ImportError(
+            "`--mode live` needs the `live` extra: run `uv sync --extra live` (adds dash) and retry. "
+            "In a notebook, install the `notebook` extra instead (`pip install \"tam-quant[notebook]\"`)."
+        ) from exc
+
+    if not verbose:
+        logging.getLogger("werkzeug").setLevel(logging.ERROR)
+
+    app = dash.Dash(__name__)
+    app.layout = html.Div(
+        [
+            html.Div(id="status", style={"fontFamily": "monospace", "padding": "8px"}),
+            dcc.Graph(id="figure", style={"height": "95vh"}),
+            dcc.Interval(id="tick", interval=int(poll_seconds * 1000)),
+        ]
+    )
+    last_report: dict = {"value": None}
+
+    @app.callback(Output("figure", "figure"), Output("status", "children"), Input("tick", "n_intervals"))
+    def _refresh(_):
+        fresh = report_from_checkpoint(checkpoint_path)
+        if fresh is not None:
+            last_report["value"] = fresh
+        report = last_report["value"]
+
+        if report is None or not report.snapshots:
+            return {}, "waiting for the first completed day..."
+
+        fig = render(report, title=title, ticker_colors=ticker_colors, prices=prices)
+        frame = report.to_frame()
+        last_date = frame["date"].max()
+        day_count = frame["date"].nunique()
+        status = f"through {last_date} — day {day_count}"
+        if not Path(checkpoint_path).exists():
+            status += " -- backtest finished, showing final state"
+        return fig, status
+
+    run_kwargs = {"port": port, "debug": False, "threaded": True}
+    if jupyter_mode is not None:
+        run_kwargs["jupyter_mode"] = jupyter_mode
+    app.run(**run_kwargs)