quantred 2.4.0__tar.gz

quantred-2.4.0/.dockerignore

@@ -0,0 +1,23 @@
+# An allowlist, not a denylist: the Dockerfile copies the build context, and a
+# checkout holds things that must never reach an image - `.env` (broker credentials),
+# the gitignored `specs/`, `configs/` and `logs/` (a campaign's private strategy
+# evidence and journal), `cache/`, `.git`, virtual environments and node_modules.
+# A denylist misses the next one somebody adds; this names only what the image runs.
+*
+
+!pyproject.toml
+!uv.lock
+!README.md
+!LICENSE
+!main.py
+!quantred/
+!example/
+
+# Even inside the allowed trees.
+**/__pycache__
+**/*.pyc
+**/.pytest_cache
+**/.ruff_cache
+**/.DS_Store
+**/.env
+**/.venv

quantred-2.4.0/.env.example

@@ -0,0 +1,27 @@
+# Copy this file to .env and fill in your Alpaca credentials.
+# .env is gitignored, so your keys are never committed.
+#
+# Get free paper-trading keys at https://app.alpaca.markets/
+#   -> Paper Account -> API Keys
+#
+# (No keys needed just to explore — run `make demo` for an offline walkthrough.)
+
+APCA_API_KEY_ID=<APCA_API_KEY_ID>
+APCA_API_SECRET_KEY=<APCA_API_SECRET_KEY>
+
+# Keep this true until you are absolutely sure you want to trade real money.
+PAPER_TRADE=true
+
+
+# --- Optional: AI research agent (`python main.py research`) -----------------
+# Only needed if you run the research agent. Set the key for the provider you
+# use (or export it as a normal environment variable — either works). Ollama
+# runs locally and needs no key.
+#
+#   --provider anthropic (default):  ANTHROPIC_API_KEY   (needs the `ai` extra)
+#   --provider openai:               OPENAI_API_KEY      (needs the `openai` extra)
+#   --provider ollama (local):       no key; optional OLLAMA_BASE_URL
+#
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OLLAMA_BASE_URL=http://localhost:11434

quantred-2.4.0/.github/pull_request_template.md

@@ -0,0 +1,22 @@
+<!-- Keep PRs small and focused on one layer/concern where possible. -->
+
+## What & why
+
+<!-- What does this change do, and why? Link any issue. -->
+
+## How
+
+<!-- Notable implementation choices, especially anything affecting a layer boundary. -->
+
+## Checklist
+
+- [ ] `make test` passes (offline; no keys needed)
+- [ ] `uv run ruff check .` and `uv run ruff format --check .` are clean
+- [ ] New/changed behavior is covered by tests
+- [ ] No vendor SDK (`alpaca`, ...) imported above the broker layer
+- [ ] Touches one concern per layer (see [Separation of concerns](../docs/content/engineering/separation-of-concerns.md))
+- [ ] Docs updated if usage or architecture changed (README / `docs/content`)
+
+## Screenshots / output
+
+<!-- e.g. a backtest report, scan output, or relevant logs. Optional. -->

quantred-2.4.0/.github/scripts/require_published_dependency.py

@@ -0,0 +1,65 @@
+"""Fail unless the engine version the transition package requires is already on PyPI.
+
+The transition release of the old distribution name depends on ``quantred``. PyPI never
+lets a version be replaced, so publishing it before a satisfying ``quantred`` exists would
+leave a permanent release whose dependency cannot be installed. The tag order is a human
+convention; this makes it a check.
+
+Usage: require_published_dependency.py <pyproject.toml> [<releases.json>]
+Without the second argument the release list is fetched from PyPI.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import urllib.error
+import urllib.request
+
+import tomllib
+from packaging.requirements import Requirement
+from packaging.version import Version
+
+TARGET = "quantred"
+
+
+def satisfied(pyproject_text: str, releases: dict) -> str:
+    """The newest un-yanked release meeting the dependency, or raise SystemExit."""
+    deps = tomllib.loads(pyproject_text)["project"]["dependencies"]
+    wanted = [r for r in map(Requirement, deps) if r.name == TARGET]
+    if not wanted:
+        raise SystemExit(f"the transition package declares no dependency on {TARGET}")
+    spec = wanted[0].specifier
+    live = [
+        version
+        for version, files in releases.items()
+        if files and not all(f.get("yanked") for f in files) and version in spec
+    ]
+    if not live:
+        raise SystemExit(
+            f"{TARGET}{spec} is not on PyPI yet; publish it before the transition package "
+            "(a published release cannot be replaced)"
+        )
+    return str(max(map(Version, live)))
+
+
+def main(argv: list[str]) -> int:
+    with open(argv[1], encoding="utf-8") as handle:
+        text = handle.read()
+    if len(argv) > 2:
+        with open(argv[2], encoding="utf-8") as handle:
+            data = json.load(handle)
+    else:
+        try:
+            with urllib.request.urlopen(f"https://pypi.org/pypi/{TARGET}/json", timeout=30) as response:
+                data = json.load(response)
+        except urllib.error.HTTPError as exc:
+            if exc.code != 404:
+                raise
+            data = {"releases": {}}  # no such project yet: nothing satisfies the dependency
+    print(f"found {TARGET} {satisfied(text, data['releases'])}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

quantred-2.4.0/.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  # Every branch, not just main: the secret scan below is only useful if it sees a
+  # push that has no pull request behind it. The expensive job stays gated to
+  # main + PRs via its own `if` — see lint-and-test.
+  push:
+  pull_request:
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    # Unchanged behavior: pull requests, and pushes to main. A push to a topic
+    # branch with a PR open would otherwise run the whole suite twice.
+    if: github.event_name == 'pull_request' || github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      # The example pack registers through the same entry-point groups a user's own
+      # pack does. Installing it here is what makes CI exercise that path end to end -
+      # real packaging, real discovery, real contract compliance - rather than only the
+      # monkeypatched fakes the registry unit tests use.
+      - name: Install the example pack (exercises entry-point discovery)
+        run: uv pip install --no-deps -e example
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Docs link check
+        # Relative links and heading anchors across the docs site and top-level
+        # Markdown, and no tracked link into the gitignored specs/.
+        run: uv run python scripts/check_links.py
+
+      - name: Compose config validates
+        # Cheap and daemon-free: catches a malformed compose file on every PR. The
+        # behavioral checks (state survives `down`, live never starts, volumes are
+        # host-readable) need a daemon and live in scripts/compose_smoke.sh, run
+        # locally and recorded in the PR.
+        run: docker compose config --quiet
+
+      - name: Tests (pytest)
+        run: uv run pytest -q
+
+  secret-scan:
+    # The repository is public, so a committed key is disclosed the moment it
+    # lands. Unlike lint-and-test this runs on *every* branch push, not only main
+    # and PRs — a secret pushed to a topic branch is already public whether or not
+    # anyone opens a pull request. A branch with a PR open therefore scans twice
+    # (push + pull_request); at half a second a run that is not worth avoiding.
+    #
+    # GitHub's own secret scanning + push protection is enabled on the repo and
+    # catches known provider formats before a push lands. This is the second
+    # layer — it runs on forks, and it fails the build rather than only alerting
+    # the owner.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Everything reachable from this ref, not just the diff: a secret deleted
+          # in a later commit is still readable in the one that added it, and the
+          # default shallow clone hides exactly those commits.
+          fetch-depth: 0
+
+      - name: Install gitleaks
+        # Pinned to an exact release rather than an action, so a scan is
+        # reproducible and no third-party code runs with the workflow token.
+        env:
+          GITLEAKS_VERSION: 8.30.1
+        run: |
+          curl -sSfL -o /tmp/gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          tar -xzf /tmp/gitleaks.tar.gz -C /usr/local/bin gitleaks
+          gitleaks version
+
+      - name: Scan history for secrets
+        # --redact keeps any match out of the public build log; the finding is in
+        # the uploaded report. Exits non-zero when anything is found.
+        run: gitleaks git --no-banner --redact --report-path gitleaks-report.json .
+
+      - name: Upload findings
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: gitleaks-report
+          path: gitleaks-report.json
+          if-no-files-found: ignore

quantred-2.4.0/.github/workflows/docs.yml

@@ -0,0 +1,110 @@
+name: Docs
+
+# Builds the documentation site on every PR (the Docusaurus production build compiles
+# every page and, with onBrokenLinks/onBrokenAnchors set to 'throw', fails on any dead
+# internal link or anchor) — and deploys it on main.
+#
+# The deploy exists because it did not: the site was published by hand, so it silently
+# fell behind the repository. A page could be written, reviewed, merged, and linked
+# from the README while 404ing for every reader.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install Node
+        uses: actions/setup-node@v7
+        with:
+          # .nvmrc is the single source: a contributor running `nvm use` and CI build
+          # on the same major, and there is no second place to forget to update.
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs (fails on broken links/anchors)
+        run: npm run build
+
+      - name: Upload the built site
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-site
+          path: docs/build/
+
+  deploy:
+    name: Deploy to Cloudflare
+    # Only from main, and only once the build above has actually succeeded.
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build-docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          # .nvmrc is the single source: a contributor running `nvm use` and CI build
+          # on the same major, and there is no second place to forget to update.
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - run: npm ci
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: docs-site
+          path: docs/build/
+
+      # Fail with an explanation, not a bare exit code. Without this, a missing
+      # secret surfaces as `wrangler` exiting 1 with nothing to act on — the reader
+      # has to guess that a credential is the problem.
+      - name: Check the deploy credentials exist
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          if [ -z "$CLOUDFLARE_API_TOKEN" ]; then
+            echo "::error title=Missing deploy credentials::CLOUDFLARE_API_TOKEN is not set."
+            echo ""
+            echo "The docs site cannot deploy without it, so tradeflow.mk-dir.com will"
+            echo "keep serving whatever was last published by hand."
+            echo ""
+            echo "Add it at: Settings -> Secrets and variables -> Actions"
+            echo "  CLOUDFLARE_API_TOKEN    a token with the Workers Scripts:Edit permission"
+            echo "  CLOUDFLARE_ACCOUNT_ID   optional; only if the account is ambiguous"
+            echo ""
+            echo "To publish once by hand in the meantime:"
+            echo "  cd docs && npx wrangler login && npm run deploy"
+            exit 1
+          fi
+
+      - name: Deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: npx wrangler deploy

quantred-2.4.0/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed. Two properties matter here:
+#
+#   1. The tests run first, and a failure stops the publish. A release is the one
+#      moment a broken build becomes someone else's problem permanently — PyPI
+#      versions cannot be replaced, only yanked.
+#   2. No API token is stored anywhere. Publishing uses PyPI's trusted publishing
+#      (OIDC), so the only thing that can release is this workflow, from this
+#      repository, on a tag. A leaked secret cannot publish because there is no
+#      secret.
+#
+# Set up once at https://pypi.org/manage/project/quantred/settings/publishing/ (a new
+# project name needs its own trusted publisher; the one registered for the previous
+# distribution name does not carry over)
+#   owner: makedirectory   repository: quantred
+#   workflow: release.yml  environment: pypi
+#
+# A tag `v*` publishes the engine from the repository root. A tag `tradeflow-engine-v*`
+# publishes the final transition release of the old distribution name from
+# packaging/tradeflow-engine instead. That project's trusted publisher must name the
+# repository as it is now called (`quantred`, renamed from the old one) and the same
+# workflow `release.yml` and environment `pypi`.
+
+on:
+  push:
+    tags: ["v*", "tradeflow-engine-v*"]
+  workflow_dispatch:
+
+jobs:
+  verify:
+    name: Test before publishing
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q
+
+  build:
+    name: Build the distribution
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Build the engine (tag v*, or a manual run)
+        if: ${{ !startsWith(github.ref, 'refs/tags/tradeflow-engine-v') }}
+        run: uv build
+      - name: Build the transition package (tag tradeflow-engine-v*)
+        if: startsWith(github.ref, 'refs/tags/tradeflow-engine-v')
+        run: uv build packaging/tradeflow-engine -o dist
+      # Catches a malformed README or bad metadata before it is permanent.
+      - run: uvx twine check dist/*
+      # The tag and the packaged version must agree, or the release notes describe
+      # something other than what was published.
+      - name: Tag matches the packaged version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          BUILT=$(ls dist/*.tar.gz | sed -E 's/.*-([0-9][^-]*)\.tar\.gz/\1/')
+          echo "tag=$TAG built=$BUILT"
+          test "$TAG" = "$BUILT"
+      - name: Tag matches the transition package's version
+        if: startsWith(github.ref, 'refs/tags/tradeflow-engine-v')
+        run: |
+          TAG="${GITHUB_REF_NAME#tradeflow-engine-v}"
+          BUILT=$(ls dist/tradeflow_engine-*.tar.gz | sed -E 's/.*-([0-9][^-]*)\.tar\.gz/\1/')
+          echo "tag=$TAG built=$BUILT"
+          test "$TAG" = "$BUILT"
+      # PyPI cannot replace a version. Publishing this before the engine release it
+      # requires exists would leave a permanent release whose dependency cannot be
+      # installed, so the order of the two tags is checked, not remembered.
+      - name: The engine release this requires is on PyPI
+        if: startsWith(github.ref, 'refs/tags/tradeflow-engine-v')
+        run: uv run --no-project --with packaging python .github/scripts/require_published_dependency.py packaging/tradeflow-engine/pyproject.toml
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # the OIDC token trusted publishing exchanges for an upload
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

quantred-2.4.0/.gitignore

@@ -0,0 +1,171 @@
+# Generated artifacts
+optimization_results.csv
+walkforward_results.csv
+
+# Saved strategy configs (a human promotes these; never auto-applied).
+# Anchored to the repo root: unanchored, this matched a `configs/` at *any* depth and
+# silently excluded the example pack's own config — so a fresh clone got a pack missing
+# the artefact its README tells you to run.
+/configs/
+
+# MCP audit log, research journal, and run artifacts. Anchored for the same reason.
+/logs/
+
+# Persistent bar cache - derived from Alpaca, safe to delete. Anchored for the same reason.
+/cache/
+
+# Docs site (Docusaurus)
+docs/node_modules/
+docs/build/
+docs/.docusaurus/
+
+# Mongo Data
+/data/db
+
+# Below is a standard to gitignore file for Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# macOS
+.DS_Store
+
+# VS Code settings
+.vscode/
+
+# Ruff
+.ruff_cache/
+
+# Specs
+specs/

quantred-2.4.0/.gitleaksignore

@@ -0,0 +1,5 @@
+# Fake API keys in test fixtures, already in history. Each test plants one to check that
+# a key is never printed or written; neither has ever been a real credential. The lines
+# themselves now carry `gitleaks:allow`, which covers them from here on.
+27eb2eebf0dbce4dda8ed77f70f6be45f763dcef:tests/test_setup.py:generic-api-key:640
+c8a28fbac456371971c76681942d2a36c7c9cabf:tests/test_model_probe.py:generic-api-key:18

quantred-2.4.0/.nvmrc

@@ -0,0 +1 @@
+24

quantred-2.4.0/AGENTS.md

@@ -0,0 +1,53 @@
+# Working on QuantRed
+
+Topic rules live in `.claude/rules/`; the cycle a change goes through, and the gate it
+has to pass, are in [how a change gets built here](.claude/rules/build-process.md). The
+procedures that cycle names are skills — `review-gate`, `consolidation-pass`,
+`dependency-truth` — and `/ship-check` reports what the definition of done is missing.
+This file is only what is true in every session.
+
+## The one invariant
+
+**Two clocks.** The research clock (backtest, optimize, walk-forward, analytics, the
+AI agent) is slow, exploratory, and only ever *proposes*. The trade clock
+(`quantred/engine/live.py`, `quantred/execution/`) is deterministic and imports
+**nothing** from `services/`, `analytics/`, `optimization/`, or `research/`.
+Promotion between them is a manual human step.
+
+A change that blurs this is wrong regardless of how well it works.
+
+## Verify, don't assert
+
+The rule that has caught the most real defects here — every one of them looked
+correct in the source:
+
+- **Run the thing.** Installing the published package into a clean venv found four
+  onboarding dead ends that passed every test. An MCP dependency that every test and
+  lockfile agreed was fine shipped broken.
+- **Check the environment, not the config.** Confirm an action tag resolves before
+  pushing it, a URL serves before linking it, a dependency's *resolved* version
+  rather than what the lockfile pinned.
+- **Say what you actually verified**, and what you did not.
+
+## Commands
+
+```bash
+uv run ruff check . && uv run ruff format --check .   # exactly what CI runs
+make test                                             # offline, no keys
+make check-links                                      # tracked docs; specs/ never linked
+make release-check                                    # build + install into a clean venv
+```
+
+## Definition of done
+
+Per [build-process](.claude/rules/build-process.md), none of it optional: right layer · offline deterministic tests via
+`tests/fakes.py` · every applicable surface wired (CLI, MCP tool, Makefile) · docs
+updated · all four commands above clean.
+
+## Git
+
+- Branch off `main`; never commit to it directly.
+- **Commit as you go.** Reconstructing per-change commits afterwards is impossible
+  once edits to shared files interleave.
+- Messages explain the *why* and any deviation from plan; end with
+  `Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>`.

quantred-2.4.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md