koval-engine 0.9.0__tar.gz

koval_engine-0.9.0/.cursor/rules/koval-engine.mdc

@@ -0,0 +1,9 @@
+---
+description: koval-engine 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: no real-money code path, no backtrader import, no new
+runtime dependencies, never run git write commands.

koval_engine-0.9.0/.github/CODEOWNERS

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

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

@@ -0,0 +1,65 @@
+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-engine/blob/main/SECURITY.md) for private reporting.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you observe? Paste the full error or the incorrect output.
+    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 if one is involved. A reproduction that runs against the 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: engine-version
+    attributes:
+      label: koval-engine version
+      description: Output of `koval --version`.
+      placeholder: "0.9.0"
+    validations:
+      required: true
+
+  - type: input
+    id: adapter-version
+    attributes:
+      label: Backtest engine package and version
+      description: e.g. package-name 1.2.3, or "none" if the problem does not involve a backtest.
+    validations:
+      required: false
+
+  - 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_engine-0.9.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/koval-finance/koval-engine/security/advisories/new
+    about: Report privately through GitHub. Never open a public issue for a security problem.

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

@@ -0,0 +1,42 @@
+name: Feature request
+description: Suggest a capability the 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.
+
+        Note that real-money trading is permanently out of scope: the engine is built so that no code path reaches a real-money endpoint, and requests to add one will be closed.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do that the engine 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 affects a public contract — a block's parameters, an entity on a graph edge, the engine protocol — say so explicitly.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What you tried, or why an existing block or a custom 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_engine-0.9.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## 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
+- [ ] `pytest -m "not backtrader" -q` passes
+- [ ] `ruff check .` and `ruff format --check .` are clean
+- [ ] Every commit is signed off (`git commit -s`) — CI enforces this
+- [ ] No new runtime dependency (or the reason for one is explained above)
+- [ ] No file imports `backtrader` or `koval.adapters.backtrader`
+- [ ] `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_engine-0.9.0/.github/copilot-instructions.md

@@ -0,0 +1,5 @@
+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: no real-money code path, no
+`backtrader` import, no new runtime dependencies, and never run git write
+commands — suggest, do not commit.

koval_engine-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_engine-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 default suite — the
+      # same gates as the release workflow, pinned to it by
+      # tests/test_agents_docs.py. The licence-boundary, public-surface,
+      # public-language, and agent-docs 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_engine-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-engine.git"
+          git push gitlab refs/remotes/origin/main:refs/heads/main --tags

koval_engine-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 -m "not backtrader" -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_engine-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_engine-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_engine-0.9.0/AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md — koval-engine
+
+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-engine is the MIT-licensed core of a trading-strategy platform: a
+typed dataflow strategy engine, a block library, exchange data adapters, and
+sandbox brokers. It is published on PyPI as `koval-engine`; the import
+package is `koval`. There is no real-money trading path, by design and by
+test.
+
+## Non-negotiables
+
+Tests pin most of these; [agents_docs/invariants.md](agents_docs/invariants.md)
+says exactly which, and marks the rest as the reviewer's job instead. All six
+carry the same weight regardless of which enforces them.
+
+- **No real-money code path.** Only `paper` and `binance_sandbox` execution
+  modes exist. Never add, enable, or assume another.
+- **MIT only.** No file imports `backtrader` or any package derived from it.
+  Backtest engines are separate plugins found through the
+  `koval.backtest_engines` entry-point group.
+- **No new runtime dependencies.** The list is exactly: `numpy`, `pandas`,
+  `pyarrow`, `portalocker`, `pydantic`, `requests`. Open an issue before
+  proposing a seventh.
+- **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+.
+
+## Definition of done
+
+```bash
+./scripts/verify.sh
+```
+
+Exit code 0 means done: lint, formatting, and the full default test suite.
+Nothing else counts, and no prose argument substitutes for it.
+
+Do not install `backtrader` into this repository's virtualenv — tests marked
+`backtrader` belong to a separately distributed GPL plugin and are excluded
+by the default command.
+
+## Repository map
+
+```
+src/koval/
+├── engine/      backtest protocol, live engine, paper broker, metrics, account state
+├── strategy/
+│   ├── base/        DeclarativeStrategy ABC, TradeSetup, EntryConfig
+│   ├── helpers/     pure block functions — no framework, no state, no I/O
+│   ├── graph/       typed dataflow engine: entities, domains, ports, executor
+│   ├── nodes/       typed nodes wrapping the pure helpers
+│   ├── presets/     preset graph builders
+│   ├── registry.py  BLOCK_CATALOG and STRATEGY_REGISTRY
+│   └── schemas.py   Pydantic parameter models per block
+├── exchanges/   data adapters, OHLCV cache, sandbox brokers
+└── cli/         the `koval` console script
+```
+
+Tests mirror this layout under `tests/`.
+
+## 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. 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 |
+|---|---|
+| Add or change a block | [agents_docs/adding_a_block.md](agents_docs/adding_a_block.md) |
+| Graph engine or validation | [agents_docs/graph_contracts.md](agents_docs/graph_contracts.md) |
+| Exchanges, cache, or brokers | [agents_docs/exchanges_and_data.md](agents_docs/exchanges_and_data.md) |
+| Safety or licensing | [agents_docs/invariants.md](agents_docs/invariants.md) |
+| Everything else | [agents_docs/README.md](agents_docs/README.md) |

koval_engine-0.9.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [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). While the version is below 1.0, the public API may change in a minor release.
+
+## [Unreleased]
+
+## [0.9.0] - 2026-07-30
+
+First public release.
+
+### Added
+
+- **Typed dataflow strategy engine.** Strategies are JSON graphs of nodes across the FACT, STATE, POLICY, INTERPRETATION, and EXECUTION domains, with structural and entity validation.
+- **Block catalogue** of 26 blocks — signals, filters, entries, exits, dynamic exits, and risk — compiled onto 35 typed nodes. Block helpers are pure functions over numpy with no framework dependency.
+- **Pluggable backtest engine.** `BacktestEngineProtocol` plus discovery of independently distributed implementations through the `koval.backtest_engines` entry-point group, keeping this package MIT.
+- **Paper broker** with a documented bracket/OCO fill ruleset and pessimistic resolution of ambiguous bars.
+- **Non-production execution.** Binance Futures testnet supports fail-closed, market-entry-only execution with immediate bracket confirmation. WhiteBIT market data is read-only; execution is disabled because WhiteBIT has no verified public sandbox.
+- **Market data adapters** for Binance and WhiteBIT (read-only REST) with a local Parquet OHLCV cache.
+- **`koval` command-line interface** — `blocks`, `validate`, and `backtest`, the last against either a local CSV or fetched candles.
+- **Runnable examples** with bundled synthetic OHLCV data, so the quickstart works offline and deterministically.
+- **Typing.** The package ships a `py.typed` marker.
+- **Version introspection.** `koval.__version__` reports the installed distribution version, read from distribution metadata so that `pyproject.toml` stays the only source of truth.
+- **Agent-facing documentation.** A root `AGENTS.md` (read natively by most coding agents) with thin pointers for Claude Code, Gemini CLI, Cursor, and GitHub Copilot; a topic-per-file `agents_docs/` knowledge base; and `scripts/verify.sh`, the single command that reproduces CI. Cross-file consistency is pinned by `tests/test_agents_docs.py`.
+
+### Security
+
+- No code path reaches a real-money trading endpoint. Only `paper` and `binance_sandbox` are allowlisted execution modes; WhiteBIT execution fails closed. The invariant is pinned by `tests/safety/`.
+- The MIT/GPL boundary is enforced by a test rather than by convention: no file in this package may import Backtrader.
+- Releases are published to PyPI through Trusted Publishing (OIDC) with PEP 740 attestations. No long-lived PyPI credential is used in CI.
+
+[Unreleased]: https://github.com/koval-finance/koval-engine/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/koval-finance/koval-engine/releases/tag/v0.9.0

koval_engine-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.