pineforge-data 0.2.0__tar.gz → 0.3.0__tar.gz

pineforge_data-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[dev,ccxt,release]'
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest
+      - if: matrix.python-version == '3.13'
+        run: python -m build
+      - if: matrix.python-version == '3.13'
+        run: python -m twine check --strict dist/*
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+      - run: PINEFORGE_DOCKER_TEST=1 pytest tests/test_docker_integration.py
+
+  database-e2e:
+    runs-on: ubuntu-latest
+    services:
+      mysql:
+        image: mysql:8.4
+        env:
+          MYSQL_DATABASE: pineforge
+          MYSQL_USER: pineforge
+          MYSQL_PASSWORD: pineforge
+          MYSQL_ROOT_PASSWORD: pineforge-root
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping --host=127.0.0.1 --user=pineforge --password=pineforge --silent"
+          --health-interval=2s
+          --health-timeout=5s
+          --health-retries=30
+          --health-start-period=15s
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: pineforge
+          POSTGRES_USER: pineforge
+          POSTGRES_PASSWORD: pineforge
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready --username=pineforge --dbname=pineforge"
+          --health-interval=2s
+          --health-timeout=5s
+          --health-retries=30
+          --health-start-period=10s
+    env:
+      PINEFORGE_DATABASE_E2E: "1"
+      PINEFORGE_CORPUS_OHLCV: tests/fixtures/corpus_ohlcv_ETH-USDT-USDT_1m_sample.csv
+      PINEFORGE_MYSQL_URL: mysql+pymysql://pineforge:pineforge@127.0.0.1:3306/pineforge
+      PINEFORGE_POSTGRES_URL: postgresql+psycopg://pineforge:pineforge@127.0.0.1:5432/pineforge
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[dev,database-e2e]'
+      - run: pytest tests/test_database_e2e.py

{pineforge_data-0.2.0 → pineforge_data-0.3.0}/CONTRIBUTING.md

@@ -77,6 +77,20 @@ python -m twine check dist/*
 PINEFORGE_DOCKER_TEST=1 pytest tests/test_docker_integration.py
 ```
 
+Database-provider changes must also pass the corpus-backed database suite:
+
+```bash
+python -m pip install -e '.[dev,database-e2e]'
+./scripts/run_database_e2e.sh
+```
+
+The harness starts disposable MySQL and PostgreSQL containers and creates a
+temporary SQLite database. If the sibling engine corpus exists, it streams the
+first requested rows from
+`../pineforge-engine/corpus/data/ohlcv_ETH-USDT-USDT_1m.csv`; otherwise it uses
+the provenance-pinned sample under `tests/fixtures/`. Override the source or
+row count with `PINEFORGE_CORPUS_OHLCV` and `PINEFORGE_DATABASE_E2E_ROWS`.
+
 Maintainers should follow the version, tag, artifact, and Trusted Publishing
 steps in the [release guide](docs/releasing.md). Contributors cannot publish a
 package from a pull request.

pineforge_data-0.3.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: pineforge-data
+Version: 0.3.0
+Summary: Provider-neutral market data adapters and raw-PineScript backtest harness for PineForge
+Project-URL: Homepage, https://github.com/pineforge-4pass/pineforge-data
+Project-URL: Documentation, https://pineforge-4pass.github.io/pineforge-data/
+Project-URL: Issues, https://github.com/pineforge-4pass/pineforge-data/issues
+Project-URL: Source, https://github.com/pineforge-4pass/pineforge-data
+Author: PineForge contributors
+License: Apache-2.0
+License-File: LICENSE
+Keywords: backtesting,market-data,pinescript
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: ccxt
+Requires-Dist: ccxt<5,>=4.5.64; extra == 'ccxt'
+Provides-Extra: database
+Requires-Dist: sqlalchemy<3,>=2.0; extra == 'database'
+Provides-Extra: database-e2e
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'database-e2e'
+Requires-Dist: pymysql<2,>=1.1; extra == 'database-e2e'
+Requires-Dist: sqlalchemy<3,>=2.0; extra == 'database-e2e'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: fastapi<0.140,>=0.139; extra == 'dev'
+Requires-Dist: httpx2<2.6,>=2.5; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: sqlalchemy<3,>=2.0; extra == 'dev'
+Requires-Dist: uvicorn<0.52,>=0.51; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.7; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings-python<3,>=2.0; extra == 'docs'
+Requires-Dist: ruff>=0.8; extra == 'docs'
+Provides-Extra: release
+Requires-Dist: build<2,>=1.2; extra == 'release'
+Requires-Dist: twine<8,>=7; extra == 'release'
+Provides-Extra: server
+Requires-Dist: fastapi<0.140,>=0.139; extra == 'server'
+Requires-Dist: uvicorn<0.52,>=0.51; extra == 'server'
+Description-Content-Type: text/markdown
+
+# PineForge Data
+
+[![PyPI](https://img.shields.io/pypi/v/pineforge-data.svg)](https://pypi.org/project/pineforge-data/)
+[![Python](https://img.shields.io/pypi/pyversions/pineforge-data.svg)](https://pypi.org/project/pineforge-data/)
+[![CI](https://github.com/pineforge-4pass/pineforge-data/actions/workflows/ci.yml/badge.svg)](https://github.com/pineforge-4pass/pineforge-data/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://pineforge-4pass.github.io/pineforge-data/)
+
+Fetch normalized market data and run raw PineScript strategies through
+PineForge.
+
+PineForge Data provides Python adapters for exchanges, CSV files, SQLite, and
+SQLAlchemy-compatible databases. Its backtest harness sends normalized OHLCV
+to the `pineforge-release` container, which transpiles the PineScript, compiles
+it, and runs `pineforge-engine`.
+
+```text
+exchange / CSV / database
+          ↓
+    pineforge-data
+          ↓
+ pineforge-release container
+          ↓
+     backtest report
+```
+
+The provider layer is Python-only. You do not need a C++ compiler, Git
+submodules, or local engine and codegen checkouts.
+
+## Quick start
+
+You need Python 3.11 or newer. Docker is required only for backtests; fetching
+and normalizing data does not use Docker.
+
+### 1. Install an exchange provider
+
+```bash
+python -m pip install 'pineforge-data[ccxt]'
+```
+
+### 2. Fetch confirmed OHLCV
+
+```python
+import asyncio
+
+from pineforge_data import BarRequest, CcxtProvider
+
+
+async def main() -> None:
+    async with CcxtProvider("bitstamp") as provider:
+        market = await provider.resolve_market("BTC/USD")
+        bars = await provider.fetch_bars(
+            BarRequest(
+                instrument=market.instrument,
+                timeframe="15m",
+                start_ms=1_751_328_000_000,
+                end_ms=1_751_414_400_000,
+            )
+        )
+        print(bars[-1])
+
+
+asyncio.run(main())
+```
+
+Symbols are resolved through the provider catalog. For example, CCXT spot
+`BTC/USDT` and linear swap `BTC/USDT:USDT` are distinct instruments with
+different contract metadata.
+
+### 3. Backtest raw PineScript
+
+Save a strategy as `strategy.pine`:
+
+```pinescript
+//@version=6
+strategy("SMA cross", initial_capital=10000, default_qty_type=strategy.percent_of_equity, default_qty_value=10)
+
+fast = ta.sma(close, 2)
+slow = ta.sma(close, 4)
+
+if ta.crossover(fast, slow)
+    strategy.entry("Long", strategy.long)
+
+if ta.crossunder(fast, slow)
+    strategy.close("Long")
+```
+
+Then run:
+
+```bash
+pineforge-backtest \
+  --pine strategy.pine \
+  --provider ccxt \
+  --venue bitstamp \
+  --symbol BTC/USD \
+  --timeframe 15m \
+  --start 2025-07-01T00:00:00Z \
+  --end 2025-07-08T00:00:00Z \
+  --warmup-bars 100 \
+  --output report.json \
+  --pretty
+```
+
+The first run pulls the digest-pinned `pineforge-release` 1.0.0 image (engine
+1.0.0, codegen 1.0.0). Results can differ between releases, notably for scripts
+that omit their capital or order size; the
+[runtime image policy](https://pineforge-4pass.github.io/pineforge-data/backtesting/#runtime-image-policy)
+explains why and how to pin another release with `--runtime-image`.
+The JSON report includes trades, performance
+statistics, the equity curve, data provenance, and exact runtime versions. The
+strategy is compiled inside an isolated Docker container; the provider and its
+credentials remain on the host.
+
+## Bring your own data
+
+PineForge does not require a fixed table definition. Local providers inspect
+headers or reflected database columns at runtime, infer common OHLCV names,
+and accept an explicit mapping when your schema uses different names.
+
+| Source | Install | Guide |
+|---|---|---|
+| CSV | `pip install pineforge-data` | [CSV API](https://pineforge-4pass.github.io/pineforge-data/providers/csv/) |
+| SQLite | `pip install pineforge-data` | [SQLite API](https://pineforge-4pass.github.io/pineforge-data/providers/sqlite/) |
+| SQLAlchemy database | `pip install 'pineforge-data[database]'` plus a database driver | [SQLAlchemy API](https://pineforge-4pass.github.io/pineforge-data/providers/sqlalchemy/) |
+| CCXT exchange | `pip install 'pineforge-data[ccxt]'` | [CCXT API](https://pineforge-4pass.github.io/pineforge-data/providers/ccxt/) |
+
+The same `pineforge-backtest` command supports `--provider csv`, `sqlite`, and
+`sqlalchemy`. See the [backtesting guide](https://pineforge-4pass.github.io/pineforge-data/backtesting/)
+for provider configuration, warmup behavior, strategy inputs, reports, and
+local versus remote execution.
+
+## Documentation
+
+| I want to… | Read… |
+|---|---|
+| Install and run the first request | [Getting started](https://pineforge-4pass.github.io/pineforge-data/getting-started/) |
+| Look up Python classes and signatures | [API reference](https://pineforge-4pass.github.io/pineforge-data/api/) |
+| Choose or configure a provider | [Provider catalog](https://pineforge-4pass.github.io/pineforge-data/providers/) |
+| Understand instruments, contracts, and bars | [Data model](https://pineforge-4pass.github.io/pineforge-data/data-model/) |
+| Run and reproduce backtests | [Backtesting](https://pineforge-4pass.github.io/pineforge-data/backtesting/) |
+| Deploy the concurrent compile/backtest service | [FastAPI server](https://pineforge-4pass.github.io/pineforge-data/server/) |
+| Implement a broker or exchange adapter | [Provider contract](https://pineforge-4pass.github.io/pineforge-data/provider-contract/) |
+
+## Contributing
+
+Community providers are welcome. Keep vendor SDKs and schemas inside the
+adapter, resolve instruments through the upstream market catalog, normalize
+timestamps to Unix milliseconds, and add deterministic offline tests.
+
+```bash
+git clone https://github.com/pineforge-4pass/pineforge-data.git
+cd pineforge-data
+python -m pip install -e '.[dev,ccxt,database-e2e,server,docs,release]'
+ruff check .
+mypy src
+pytest
+mkdocs build --strict
+```
+
+Run `./scripts/run_database_e2e.sh` to seed corpus OHLCV into disposable
+SQLite, MySQL, and PostgreSQL databases and verify the public provider API
+against all three.
+
+Read [CONTRIBUTING.md](https://github.com/pineforge-4pass/pineforge-data/blob/main/CONTRIBUTING.md)
+for the provider contract, entry points, security rules, and full validation
+checklist.
+
+Apache-2.0 licensed.

pineforge_data-0.3.0/README.md

@@ -0,0 +1,167 @@
+# PineForge Data
+
+[![PyPI](https://img.shields.io/pypi/v/pineforge-data.svg)](https://pypi.org/project/pineforge-data/)
+[![Python](https://img.shields.io/pypi/pyversions/pineforge-data.svg)](https://pypi.org/project/pineforge-data/)
+[![CI](https://github.com/pineforge-4pass/pineforge-data/actions/workflows/ci.yml/badge.svg)](https://github.com/pineforge-4pass/pineforge-data/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://pineforge-4pass.github.io/pineforge-data/)
+
+Fetch normalized market data and run raw PineScript strategies through
+PineForge.
+
+PineForge Data provides Python adapters for exchanges, CSV files, SQLite, and
+SQLAlchemy-compatible databases. Its backtest harness sends normalized OHLCV
+to the `pineforge-release` container, which transpiles the PineScript, compiles
+it, and runs `pineforge-engine`.
+
+```text
+exchange / CSV / database
+          ↓
+    pineforge-data
+          ↓
+ pineforge-release container
+          ↓
+     backtest report
+```
+
+The provider layer is Python-only. You do not need a C++ compiler, Git
+submodules, or local engine and codegen checkouts.
+
+## Quick start
+
+You need Python 3.11 or newer. Docker is required only for backtests; fetching
+and normalizing data does not use Docker.
+
+### 1. Install an exchange provider
+
+```bash
+python -m pip install 'pineforge-data[ccxt]'
+```
+
+### 2. Fetch confirmed OHLCV
+
+```python
+import asyncio
+
+from pineforge_data import BarRequest, CcxtProvider
+
+
+async def main() -> None:
+    async with CcxtProvider("bitstamp") as provider:
+        market = await provider.resolve_market("BTC/USD")
+        bars = await provider.fetch_bars(
+            BarRequest(
+                instrument=market.instrument,
+                timeframe="15m",
+                start_ms=1_751_328_000_000,
+                end_ms=1_751_414_400_000,
+            )
+        )
+        print(bars[-1])
+
+
+asyncio.run(main())
+```
+
+Symbols are resolved through the provider catalog. For example, CCXT spot
+`BTC/USDT` and linear swap `BTC/USDT:USDT` are distinct instruments with
+different contract metadata.
+
+### 3. Backtest raw PineScript
+
+Save a strategy as `strategy.pine`:
+
+```pinescript
+//@version=6
+strategy("SMA cross", initial_capital=10000, default_qty_type=strategy.percent_of_equity, default_qty_value=10)
+
+fast = ta.sma(close, 2)
+slow = ta.sma(close, 4)
+
+if ta.crossover(fast, slow)
+    strategy.entry("Long", strategy.long)
+
+if ta.crossunder(fast, slow)
+    strategy.close("Long")
+```
+
+Then run:
+
+```bash
+pineforge-backtest \
+  --pine strategy.pine \
+  --provider ccxt \
+  --venue bitstamp \
+  --symbol BTC/USD \
+  --timeframe 15m \
+  --start 2025-07-01T00:00:00Z \
+  --end 2025-07-08T00:00:00Z \
+  --warmup-bars 100 \
+  --output report.json \
+  --pretty
+```
+
+The first run pulls the digest-pinned `pineforge-release` 1.0.0 image (engine
+1.0.0, codegen 1.0.0). Results can differ between releases, notably for scripts
+that omit their capital or order size; the
+[runtime image policy](https://pineforge-4pass.github.io/pineforge-data/backtesting/#runtime-image-policy)
+explains why and how to pin another release with `--runtime-image`.
+The JSON report includes trades, performance
+statistics, the equity curve, data provenance, and exact runtime versions. The
+strategy is compiled inside an isolated Docker container; the provider and its
+credentials remain on the host.
+
+## Bring your own data
+
+PineForge does not require a fixed table definition. Local providers inspect
+headers or reflected database columns at runtime, infer common OHLCV names,
+and accept an explicit mapping when your schema uses different names.
+
+| Source | Install | Guide |
+|---|---|---|
+| CSV | `pip install pineforge-data` | [CSV API](https://pineforge-4pass.github.io/pineforge-data/providers/csv/) |
+| SQLite | `pip install pineforge-data` | [SQLite API](https://pineforge-4pass.github.io/pineforge-data/providers/sqlite/) |
+| SQLAlchemy database | `pip install 'pineforge-data[database]'` plus a database driver | [SQLAlchemy API](https://pineforge-4pass.github.io/pineforge-data/providers/sqlalchemy/) |
+| CCXT exchange | `pip install 'pineforge-data[ccxt]'` | [CCXT API](https://pineforge-4pass.github.io/pineforge-data/providers/ccxt/) |
+
+The same `pineforge-backtest` command supports `--provider csv`, `sqlite`, and
+`sqlalchemy`. See the [backtesting guide](https://pineforge-4pass.github.io/pineforge-data/backtesting/)
+for provider configuration, warmup behavior, strategy inputs, reports, and
+local versus remote execution.
+
+## Documentation
+
+| I want to… | Read… |
+|---|---|
+| Install and run the first request | [Getting started](https://pineforge-4pass.github.io/pineforge-data/getting-started/) |
+| Look up Python classes and signatures | [API reference](https://pineforge-4pass.github.io/pineforge-data/api/) |
+| Choose or configure a provider | [Provider catalog](https://pineforge-4pass.github.io/pineforge-data/providers/) |
+| Understand instruments, contracts, and bars | [Data model](https://pineforge-4pass.github.io/pineforge-data/data-model/) |
+| Run and reproduce backtests | [Backtesting](https://pineforge-4pass.github.io/pineforge-data/backtesting/) |
+| Deploy the concurrent compile/backtest service | [FastAPI server](https://pineforge-4pass.github.io/pineforge-data/server/) |
+| Implement a broker or exchange adapter | [Provider contract](https://pineforge-4pass.github.io/pineforge-data/provider-contract/) |
+
+## Contributing
+
+Community providers are welcome. Keep vendor SDKs and schemas inside the
+adapter, resolve instruments through the upstream market catalog, normalize
+timestamps to Unix milliseconds, and add deterministic offline tests.
+
+```bash
+git clone https://github.com/pineforge-4pass/pineforge-data.git
+cd pineforge-data
+python -m pip install -e '.[dev,ccxt,database-e2e,server,docs,release]'
+ruff check .
+mypy src
+pytest
+mkdocs build --strict
+```
+
+Run `./scripts/run_database_e2e.sh` to seed corpus OHLCV into disposable
+SQLite, MySQL, and PostgreSQL databases and verify the public provider API
+against all three.
+
+Read [CONTRIBUTING.md](https://github.com/pineforge-4pass/pineforge-data/blob/main/CONTRIBUTING.md)
+for the provider contract, entry points, security rules, and full validation
+checklist.
+
+Apache-2.0 licensed.

{pineforge_data-0.2.0 → pineforge_data-0.3.0}/docker/server.Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1@sha256:87999aa3d42bdc6bea60565083ee17e86d1f3339802f543c0d03998580f9cb89
 
-ARG PINEFORGE_RELEASE_IMAGE=ghcr.io/pineforge-4pass/pineforge-release:0.1.12@sha256:312b9d908390b828484617472c749d5815feb75507da87eae2f6902cfe3d47b1
+ARG PINEFORGE_RELEASE_IMAGE=ghcr.io/pineforge-4pass/pineforge-release:1.0.0@sha256:b271873d0e91a9eeeb4595daaded9bdfbdbcd3925d3ec1300a833395e2004c86
 
 FROM python:3.11-slim-bookworm@sha256:f5cf0344c9886ff24d34797578d5d7dd6e8911ae0fe5962bb55d0f89603ec361 AS server-builder
 RUN python -m pip install --no-cache-dir --target /opt/pineforge-server-deps \

pineforge_data-0.3.0/docs/api/backtesting.md

@@ -0,0 +1,50 @@
+# Backtesting
+
+## Runtime options and reports
+
+::: pineforge_data.backtest.BacktestOptions
+
+::: pineforge_data.backtest.MagnifierDistribution
+
+::: pineforge_data.backtest.BacktestReport
+
+`PineForgeBacktestRunner` runs a compiled strategy library in-process. It
+accepts libraries that report PineForge C ABI 4, which engine 1.x builds. It
+refuses any other library before any strategy call, with an
+`EngineBacktestError` that says what to do. Libraries without
+`pf_abi_version` (engine v0.10.1 or earlier), ABI 2 (engine v0.10.2 through
+v0.12.3) and ABI 3 (engine v0.13.x) need a rebuild with engine 1.x;
+pineforge-data 0.2.0 still reads ABI 2. A newer ABI needs a newer
+pineforge-data. The release container and the FastAPI server do not use this
+class.
+
+A trade's `max_runup` and `max_drawdown` are whole-trade excursions in account
+currency, net of entry fees, as engine 1.0's `pineforge.h` documents them.
+Headers before 1.0 described them as price travel per unit of quantity, but the
+values did not change: on the README quick start, engines 0.11.0 and 1.0.0
+report identical excursions for the 88 trades both report. A trade whose
+`open_at_end` is true closes a position still open after the final bar, at that
+bar's close rounded to the tick size, without slippage. Engine 0.11.0 reports no
+such row, so the README quick start has 88 trades on it and 89 on engine 1.0.0.
+
+::: pineforge_data.backtest.PineForgeBacktestRunner
+
+::: pineforge_data.backtest.EngineBacktestError
+
+## Published release container
+
+::: pineforge_data.docker_runtime.DockerBacktestRuntime
+
+::: pineforge_data.docker_runtime.DockerPrerequisiteError
+
+::: pineforge_data.docker_runtime.DockerExecutionError
+
+::: pineforge_data.release_contract.DEFAULT_RELEASE_IMAGE
+
+::: pineforge_data.release_contract.ReleaseContractError
+
+## Remote FastAPI client
+
+::: pineforge_data.server_client.FastApiBacktestClient
+
+::: pineforge_data.server_client.BacktestServerError

{pineforge_data-0.2.0 → pineforge_data-0.3.0}/docs/api/server.md

@@ -1,8 +1,10 @@
 # Server components
 
-Most users run the packaged `pineforge-backtest-server` command or submit work
-through `FastApiBacktestClient`. These objects support applications that embed
-the service or manage its compiled-strategy cache directly.
+Most users run the server image built from `docker/server.Dockerfile` or submit
+work through `FastApiBacktestClient`. The packaged `pineforge-backtest-server`
+command reports ready only where the `pineforge-release` toolchain is
+installed, as in that image. These objects support applications that embed the
+service or manage its compiled-strategy cache directly.
 
 ::: pineforge_data.server.create_app
 

{pineforge_data-0.2.0 → pineforge_data-0.3.0}/docs/backtesting.md

@@ -29,7 +29,7 @@ are documented in the [server guide](server.md).
 pineforge-backtest \
   --pine strategy.pine \
   --provider ccxt \
-  --venue kraken \
+  --venue bitstamp \
   --symbol BTC/USD \
   --timeframe 15m \
   --start 2025-07-01T00:00:00Z \
@@ -60,7 +60,7 @@ strategy to place orders during that earlier interval:
 pineforge-backtest \
   --pine strategy.pine \
   --provider ccxt \
-  --venue kraken \
+  --venue bitstamp \
   --symbol BTC/USD \
   --timeframe 15m \
   --start 2025-07-01T00:00:00Z \
@@ -132,9 +132,29 @@ guides.
 
 ## Runtime image policy
 
-The package default is an exact `pineforge-release` version and OCI digest. The
-`missing` pull policy downloads it only when absent; `never` supports offline
-runs; `always` refreshes a tag before running.
+The package default is an exact `pineforge-release` version and OCI digest:
+1.0.0, which bundles engine 1.0.0 and codegen 1.0.0. The `missing` pull
+policy downloads it only when absent; `never` supports offline runs; `always`
+refreshes a tag before running.
+
+The previous default, release 0.1.12 (engine 0.11.0, codegen 0.9.0), accepts the
+same inputs. To reproduce results made with it, pin it by digest:
+
+```bash
+--runtime-image ghcr.io/pineforge-4pass/pineforge-release:0.1.12@sha256:312b9d908390b828484617472c749d5815feb75507da87eae2f6902cfe3d47b1
+```
+
+Results can differ between releases: the README quick start reports 89 trades
+on 1.0.0 and 88 on 0.1.12. The first 88 are the same trades; 1.0.0 adds the
+close of the position still open after the last bar, marked `open_at_end`.
+
+Order sizes differ too when a script omits `initial_capital`,
+`default_qty_type` or `default_qty_value`. Codegen 1.0 gives them TradingView's
+Pine v6 defaults: 100000, `strategy.percent_of_equity` and 100. Release 0.1.12
+used 1000000, `strategy.fixed` and 1. At 100% of equity, the default 100% margin
+refuses an entry that fills above its signal price, so such a script can trade
+less on 1.0.0. Declare all three settings, as the README strategy does, to size
+orders the same way on both releases.
 
 The rolling channel is explicit:
 
@@ -155,13 +175,13 @@ The harness combines provider provenance with the release report:
   "schema_version": 1,
   "request_id": null,
   "provider": {
-    "name": "ccxt:kraken",
+    "name": "ccxt:bitstamp",
     "adapter": "ccxt",
-    "venue": "kraken",
+    "venue": "bitstamp",
     "source_timeframe": "15m",
     "market": {
       "symbol": "BTC/USD",
-      "provider_id": "XXBTZUSD",
+      "provider_id": "btcusd",
       "market_type": "spot",
       "contract": null
     }
@@ -169,8 +189,8 @@ The harness combines provider provenance with the release report:
   "data": {
     "requested_start_ms": 1751328000000,
     "requested_end_ms": 1751932800000,
-    "provider_start_ms": 1746828000000,
-    "first_bar_ms": 1746828000000,
+    "provider_start_ms": 1750878000000,
+    "first_bar_ms": 1750878000000,
     "last_bar_ms": 1751931900000,
     "bars": 1172,
     "requested_bars": 672,
@@ -178,6 +198,11 @@ The harness combines provider provenance with the release report:
     "warmup_bars_loaded": 500,
     "trade_start_time_ms": 1751328000000
   },
+  "strategy": {
+    "pine": "/path/to/strategy.pine",
+    "input_timeframe": "15",
+    "script_timeframe": "15"
+  },
   "runtime": {
     "mode": "local-container",
     "release_image": "ghcr.io/...@sha256:..."

{pineforge_data-0.2.0 → pineforge_data-0.3.0}/docs/data-model.md

@@ -61,8 +61,8 @@ swap = Instrument(
 ```
 
 `ContractSpec` can also carry `expiry_ms`, `strike`, and `option_type`. A
-contract cannot be both linear and inverse, and numeric contract terms must be
-finite and positive.
+contract cannot be both linear and inverse, and contract size and strike must
+be finite and positive.
 
 ## Market listings and discovery