koval-backtrader 0.9.0__tar.gz

koval_backtrader-0.9.0/.cursor/rules/koval-backtrader.mdc

@@ -0,0 +1,10 @@
+---
+description: koval-backtrader project context — always read AGENTS.md first
+alwaysApply: true
+---
+
+All project context lives in AGENTS.md at the repository root. Read it
+before making changes. The definition of done is `./scripts/verify.sh`
+exiting 0. Hard rules: GPL SPDX header on every source file, never import
+application code, never claim the `koval` import namespace, no real-money
+code path, never run git write commands.

koval_backtrader-0.9.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything in this repository.
+* @rostredko

koval_backtrader-0.9.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,76 @@
+name: Bug report
+description: Something behaves differently from what the documentation or the code says it should.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Do not report security vulnerabilities here. See [SECURITY.md](https://github.com/koval-finance/koval-backtrader/blob/main/SECURITY.md) for private reporting.
+
+        If `load_backtest_engine()` cannot find this package, reinstall it first (`pip install -e ".[dev]"` or `pip install --force-reinstall koval-backtrader`) — entry points come from installed metadata, which an older install can leave stale.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you observe? Paste the full error, or the incorrect trades, metrics, or equity curve.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: How to reproduce
+      description: The exact CLI command or Python snippet, plus the strategy graph JSON and the candles involved. A reproduction that runs against koval-engine's bundled example data is ideal.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+    validations:
+      required: true
+
+  - type: input
+    id: adapter-version
+    attributes:
+      label: koval-backtrader version
+      placeholder: "0.9.0"
+    validations:
+      required: true
+
+  - type: input
+    id: engine-version
+    attributes:
+      label: koval-engine version
+      description: Output of `koval --version`.
+      placeholder: "0.9.0"
+    validations:
+      required: true
+
+  - type: input
+    id: backtrader-version
+    attributes:
+      label: backtrader version
+      description: Output of `pip show backtrader | grep Version`.
+      placeholder: "1.9.78.123"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12.4"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 15.2 / Ubuntu 24.04"
+    validations:
+      required: true

koval_backtrader-0.9.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/koval-finance/koval-backtrader/security/advisories/new
+    about: Report privately through GitHub. Never open a public issue for a security problem.
+  - name: Strategy, block, or metric behaviour
+    url: https://github.com/koval-finance/koval-engine/issues
+    about: Blocks, graph semantics, and metric definitions live in koval-engine. File there so every backtest engine benefits.

koval_backtrader-0.9.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature request
+description: Suggest a capability this backtest engine does not have.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please open an issue before writing a large patch, so effort is not spent on an approach that will not be merged.
+
+        Two things are permanently out of scope. **Real-money trading:** this package replays historical candles through a simulated broker and will never open a venue connection. **Strategy logic:** blocks, graph semantics, and metric definitions belong to [koval-engine](https://github.com/koval-finance/koval-engine) — file those there, so every backtest engine benefits.
+
+        Execution modelling is fees-only today. Slippage, funding, and partial fills are in scope for this repository and are the changes most likely to be accepted.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do that this package makes difficult or impossible? Describe the situation, not the solution.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What you think should change. If it would change the shape of `BacktestResult`, the events emitted during a run, or anything else a consumer can observe, say so explicitly.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What you tried, or why writing a separate backtest engine plugin does not solve it.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: dependencies
+    attributes:
+      label: Dependencies
+      options:
+        - label: This would not require a new runtime dependency, or I have explained below why one is unavoidable.
+          required: false

koval_backtrader-0.9.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## What this changes
+
+<!-- One or two sentences. If it fixes an issue, write "Fixes #123". -->
+
+## Why
+
+<!-- The problem this solves. Skip if the linked issue already explains it. -->
+
+## Checklist
+
+- [ ] Tests added or updated, and they failed before the change
+- [ ] `./scripts/verify.sh` exits 0
+- [ ] Every commit is signed off (`git commit -s`) — CI enforces this
+- [ ] No new runtime dependency (or the reason for one is explained above)
+- [ ] Every new source file carries the GPL SPDX header
+- [ ] Nothing imports application code, and no `src/koval/` was created
+- [ ] If Backtrader was upgraded: the full suite was run and the OCO patch reviewed
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`, if this is user-visible
+
+## Notes for the reviewer
+
+<!-- Anything you are unsure about, or a decision worth a second opinion. Optional. -->

koval_backtrader-0.9.0/.github/copilot-instructions.md

@@ -0,0 +1,6 @@
+All project context for this repository lives in [AGENTS.md](../AGENTS.md).
+Read it before making changes. The definition of done is
+`./scripts/verify.sh` exiting 0. Hard rules: GPL SPDX header on every source
+file, never import application code, never claim the `koval` import
+namespace, no real-money code path, and never run git write commands —
+suggest, do not commit.

koval_backtrader-0.9.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

koval_backtrader-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      # verify.sh runs ruff, the format check, and the full suite — the same
+      # gates as the release workflow, pinned to it by
+      # tests/test_agents_docs.py. The entry-point, licence-header,
+      # packaging, public-surface, and public-language guards are pytest
+      # tests and run inside it.
+      - run: ./scripts/verify.sh
+
+  dco:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Require Signed-off-by on every commit
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          missing=$(git log --format='%H %s' --invert-grep --grep='^Signed-off-by: ' "$BASE_SHA..$HEAD_SHA")
+          if [ -n "$missing" ]; then
+            echo "Commits missing a DCO sign-off:"
+            echo "$missing"
+            echo "Fix with: git commit --amend -s   (or git rebase --signoff main)"
+            exit 1
+          fi
+          echo "All commits are signed off."

koval_backtrader-0.9.0/.github/workflows/mirror.yml

@@ -0,0 +1,31 @@
+name: Mirror to GitLab
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Push to GitLab
+        env:
+          GITLAB_TOKEN: ${{ secrets.GITLAB_MIRROR_TOKEN }}
+        run: |
+          # The mirror is a convenience, not infrastructure. When the token is
+          # not configured, skip quietly rather than failing every push to main.
+          if [ -z "$GITLAB_TOKEN" ]; then
+            echo "GITLAB_MIRROR_TOKEN is not set; skipping the mirror."
+            exit 0
+          fi
+          git remote add gitlab \
+            "https://oauth2:${GITLAB_TOKEN}@gitlab.com/koval-group/koval-backtrader.git"
+          git push gitlab refs/remotes/origin/main:refs/heads/main --tags

koval_backtrader-0.9.0/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install development dependencies
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Check formatting
+        run: ruff format --check .
+      - name: Test
+        run: pytest -q
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+      - name: Verify the tag matches the packaged version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python -c "import tomllib,pathlib;print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$tag" != "$version" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject version $version"
+            exit 1
+          fi
+      - name: Extract and validate the changelog entry
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v v="$version" '
+            $0 ~ "^## \\[" v "\\]" { found=1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+          if ! grep -q '[^[:space:]]' release-notes.md; then
+            echo "No changelog entry found for $version"
+            exit 1
+          fi
+      - name: Install build tooling
+        run: python -m pip install build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Validate distributions
+        run: twine check --strict dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-notes
+          path: release-notes.md
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      # Trusted Publishing (OIDC). v1.11.0+ attaches PEP 740 attestations
+      # automatically; no long-lived PyPI token is used.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-notes
+          path: .
+      - name: Create the GitHub release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --notes-file release-notes.md

koval_backtrader-0.9.0/.github/workflows/scorecard.yml

@@ -0,0 +1,31 @@
+name: Scorecard
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "27 5 * * 1"
+  push:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@f205ea1c3313d32999d8d6a48b4f6530d4437b38 # v4
+        with:
+          sarif_file: results.sarif

koval_backtrader-0.9.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+data_cache/
+
+# Maintainer-local context is never published.
+.private/
+.agents/
+.claude/
+agent_docs/
+docs/superpowers/

koval_backtrader-0.9.0/AGENTS.md

@@ -0,0 +1,115 @@
+# AGENTS.md — koval-backtrader
+
+Context for AI coding agents and their humans. Start here; depth lives in
+[agents_docs/README.md](agents_docs/README.md).
+
+## What this is
+
+koval-backtrader runs [koval-engine](https://github.com/koval-finance/koval-engine)
+strategy graphs through [Backtrader](https://github.com/mementum/backtrader).
+It is a plugin, not a framework: the engine defines `BacktestEngineProtocol`
+and discovers implementations through the `koval.backtest_engines` entry-point
+group, and this package is one.
+
+The engine is MIT and cannot import Backtrader, which is GPL-3.0. That is the
+entire reason this repository exists as a separate distribution. Installing
+`koval-engine` alone gives you a strategy engine that cannot run a backtest;
+installing this alongside it completes the picture.
+
+Distribution: `koval-backtrader`. Import package: `koval_backtrader`.
+
+## Non-negotiables
+
+[agents_docs/invariants.md](agents_docs/invariants.md) says which test pins
+each of these and which are the reviewer's job instead. They carry the same
+weight either way.
+
+- **GPL-3.0-or-later, and every source file says so.** Each `.py` under `src/`
+  starts with `# SPDX-License-Identifier: GPL-3.0-or-later`.
+- **The dependency arrow points one way.** This package imports `koval.engine`
+  and `koval.strategy` freely. Nothing here may import application code, and
+  nothing in the engine may import this. An import in the wrong direction
+  relicenses an MIT codebase by accident.
+- **Never claim the `koval` import namespace.** The engine ships
+  `koval/__init__.py` as a regular package; a second distribution adding to it
+  shadows unpredictably. This package is top-level `koval_backtrader`.
+- **No real-money code path.** Backtests are simulations over historical
+  candles. Never add an order path that reaches a live venue.
+- **English only** in code, comments, docstrings, tests, and docs.
+- **Agents never commit.** No commits, pushes, tags, rebases, merges, or
+  history rewrites. Prepare changes, run verification, suggest a commit
+  message, stop. All git actions belong to a human.
+- **When a guard test fails, fix the cause — never the guard.**
+
+## Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+```
+
+Requires Python 3.11+. Installing pulls `koval-engine` from PyPI.
+
+## Definition of done
+
+```bash
+./scripts/verify.sh
+```
+
+Exit code 0 means done: lint, formatting, and the full test suite. Nothing
+else counts, and no prose argument substitutes for it.
+
+Every test here needs Backtrader, so unlike the engine there is no marker to
+exclude and no partial run to defend.
+
+## Repository map
+
+```
+src/koval_backtrader/
+├── backtest_runner.py   BacktraderBacktestEngine and the create_engine factory
+├── bt_adapter.py        DeclarativeStrategy → bt.Strategy bridge, HTF injection
+├── bt_analyzers.py      equity-curve and closed-trade analyzers
+└── oco_patch.py         guard against a Backtrader OCO ghost-trade bug
+```
+
+`tests/` is flat and mirrors those module names.
+
+## The seam
+
+```toml
+[project.entry-points."koval.backtest_engines"]
+backtrader = "koval_backtrader.backtest_runner:create_engine"
+```
+
+`load_backtest_engine()` reads that group, takes the entry point named
+`backtrader`, imports it, and calls it. Installing the package is the whole
+configuration story — no environment variable, no import, no wiring. The
+`KOVAL_BACKTEST_ENGINE` variable exists as an override for development and
+takes a module path, not an entry-point name.
+
+`tests/test_entry_point.py` is the guard, and it is the most important file
+here: if it fails, `koval backtest` is broken for every user even when every
+other test is green.
+
+## How to work here
+
+1. Restate the task and name what is out of scope before editing anything.
+2. Write the failing test first and watch it fail. This package decides where
+   simulated orders fill; calculation or state-transition logic without a test
+   that was observed failing is not accepted.
+3. Implement the minimum that makes it pass. No drive-by refactoring.
+4. Run `./scripts/verify.sh`.
+5. Review your own diff, report, and stop before any git action.
+
+Full workflow: [agents_docs/agent_workflow.md](agents_docs/agent_workflow.md).
+
+## Where to read next
+
+| Task | Read first |
+|---|---|
+| Anything touching licensing or the seam | [agents_docs/invariants.md](agents_docs/invariants.md) |
+| Adapter internals, fills, event flow | [agents_docs/architecture.md](agents_docs/architecture.md) |
+| Test failure or unexpected behaviour | [agents_docs/troubleshooting.md](agents_docs/troubleshooting.md) |
+| Writing or changing tests | [agents_docs/testing.md](agents_docs/testing.md) |
+| Cutting a release | [agents_docs/release_process.md](agents_docs/release_process.md) |
+| Everything else | [agents_docs/README.md](agents_docs/README.md) |

koval_backtrader-0.9.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.9.0] - 2026-08-03
+
+First public release. Extracted from a private monorepo with a clean history.
+
+### Added
+
+- `BacktraderBacktestEngine`, an implementation of koval-engine's
+  `BacktestEngineProtocol` that runs typed strategy graphs through Backtrader's
+  `Cerebro` and returns plain metrics, closed trades, and an equity curve.
+- Registration under the `koval.backtest_engines` entry-point group as
+  `backtrader`, so installing the package is the entire configuration —
+  `load_backtest_engine()` finds it with no environment variable.
+- `BTStrategyAdapter` and the `make_bt_strategy_class` factory, bridging
+  `DeclarativeStrategy` to `bt.Strategy`: bar-window array injection, higher
+  timeframe feeds, bracket placement, trailing and breakeven exit updates, and
+  an engine-event stream that makes a run auditable after the fact.
+- `TradeListAnalyzer` and `EquityCurveAnalyzer` for result extraction.
+- `apply_oco_guard()`, fixing a Backtrader bug where a take-profit and a
+  stop-loss both eligible within one bar could both fill, producing a trade
+  that never happened.
+- Guard tests covering the entry-point seam, GPL SPDX headers, the published
+  package surface, and the release pipeline.
+
+### Security
+
+- No real-money code path. This package replays historical candles through a
+  simulated broker; it holds no credentials and opens no venue connection.
+- Releases publish to PyPI through Trusted Publishing (OIDC) with PEP 740
+  attestations. No long-lived PyPI credential is used.
+
+[0.9.0]: https://github.com/koval-finance/koval-backtrader/releases/tag/v0.9.0

koval_backtrader-0.9.0/CLAUDE.md

@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+Claude Code entry file for this repository.
+
+All project context lives in [AGENTS.md](AGENTS.md). Read it before doing
+anything else; the definition of done is `./scripts/verify.sh` exiting 0.
+
+Maintainer-only: if `.private/CONTEXT.md` exists in your checkout, read it
+too. Contributors will not have this file; its absence is normal.