algotrading-core
Shared core package for the algorithmic trading platform: schemas, preprocessing, feature engineering, and utilities. Single source of truth consumed by algotrading-research and algotrading-backend via pip—no duplicated core logic.
Aligned with CODE_STRUCTURE_GUIDE.md (Core Layer) and source/DEVELOPMENT_PHASES_GUIDE.md (Phases 1–2).
Role in the platform
The platform uses a multi-repository layout:
| Repository | Role | Depends on core |
|---|---|---|
| algotrading-core | Schemas, preprocessing, features, utils | — |
| algotrading-research | Offline research, training, backtesting | ✅ |
| algotrading-backend | Signals, inference, API | ✅ |
| algotrading-execution | MT5 execution (signals only) | ❌ |
Core is versioned and published (private PyPI or Git). Research and backend pin a version and use the same feature logic for training and live inference.
Package structure
src/algotrading_core/
├── schemas/ # Pydantic data models (Phase 1)
│ ├── candle.py # OHLCV candle schema
│ ├── feature.py # Feature schema
│ ├── model.py # Model artifact schema
│ └── (config) # Configuration schemas
├── preprocessing/ # Data validation & transformation (Phase 2)
│ ├── candles.py # Candle validation, cleaning
│ ├── adjustments.py # Future contract adjustments
│ └── transformers.py # Aggregation, pipelines
├── features/ # Feature engineering (Phase 2)
│ ├── base.py # Base feature generator (abstract)
│ ├── levels.py # Support/resistance levels
│ ├── time_features.py # Time-based (e.g. trig encoding)
│ ├── volatility.py # Volatility features
│ └── aggregated.py # Aggregated timeframe features
└── utils/ # Shared utilities (Phase 1)
├── datetime_utils.py
└── path_utils.py
- Phase 1 (Foundation): schemas + utils + config loaders.
- Phase 2 (Data & preprocessing): preprocessing + feature base and concrete generators.
Installation
Requires: Python ≥3.11.
From local path (development)
uv add /path/to/algotrading-core
# or
pip install -e /path/to/algotrading-core
From Git
uv add "algotrading-core @ git+https://github.com/org/algotrading-core.git@v0.1.0"
From private PyPI
Configure your private index (see Publishing to private PyPI for index URL and auth), then:
pip install algotrading-core==0.1.0
From public PyPI (recommended for CI)
Published as algotrading-core on PyPI. In consumer pyproject.toml:
dependencies = [
"algotrading-core>=0.2.0,<1.0.0",
# ...
]
No extra index URL is required for public packages.
CI / uv: Distribution not found at .../algotrading-core
If GitHub Actions (or any CI) fails with something like:
algotrading-core @ editable+../algotrading-core / Distribution not found at: file:///.../algotrading-core
then uv.lock was generated while algotrading-core was linked as a local path (e.g. uv add --editable ../algotrading-core). The runner only checks out the consumer repo, so ../algotrading-core does not exist.
Fix in the consumer repo (e.g. algotrading-research):
- In
pyproject.toml, use a PyPI version only, e.g."algotrading-core>=0.2.0,<1.0.0". - Remove any
[tool.uv.sources]block that setsalgotrading-coreto apath(or delete only that table entry). - Regenerate the lockfile:
uv lock(from the consumer repo root). - Commit
pyproject.tomlanduv.lock.
After that, uv sync in CI resolves algotrading-core from PyPI. For local work on both repos side by side, reinstall editable core only on your machine (e.g. uv pip install -e ../algotrading-core after sync) or use a git dependency on a branch—do not commit a lockfile that points at ../algotrading-core if CI must use PyPI.
Publishing to private PyPI
The package uses semantic versioning (e.g. 1.0.0). To publish a release to a private PyPI server:
1. Bump version
Edit version in pyproject.toml (e.g. 0.1.0 → 0.2.0). Tag the release in Git:
git tag v0.2.0
2. Build the package
make build
# or: uv run python -m build
This produces dist/algotrading-core-<version>.tar.gz and dist/algotrading_core-<version>-py3-none-any.whl.
3. Configure credentials for your private index
Option A — .pypirc (recommended)
Create or edit ~/.pypirc:
[distutils]
index-servers =
private
[private]
repository = https://your-private-pypi.example.com/pypi/
username = your-username
password = your-password-or-token
Option B — Environment variables
export TWINE_USERNAME=your-username
export TWINE_PASSWORD=your-password-or-token
export TWINE_REPOSITORY_URL=https://your-private-pypi.example.com/pypi/
4. Upload
make publish
# Uses .pypirc repo name "private" by default. Override: make publish REPO=myrepo
# Or use URL directly: make publish REPO_URL=https://your-private-pypi.example.com/pypi/
Replace your-private-pypi.example.com with your actual private PyPI host (e.g. CodeArtifact, Artifactory, or self-hosted PyPI).
Consumers of the package must configure pip to use the same index (e.g. pip.conf or pip install --index-url https://.../pypi/ algotrading-core).
Usage
Consumers import from the package; no copy-paste of core code.
from algotrading_core.schemas import Candle, Feature
from algotrading_core.preprocessing.candles import preprocess_candles
from algotrading_core.features.base import FeatureGenerator
from algotrading_core.features.levels import LevelsFeatureGenerator
from algotrading_core.utils.datetime_utils import parse_interval
Research uses these for training and backtesting; the backend uses the same code for live feature generation and inference.
Development
Setup
cd algotrading-core
uv sync
Commands (Makefile)
| Target | Action |
|---|---|
make lint |
Ruff + black check |
make format |
Black + ruff --fix |
make test |
Pytest |
make coverage |
Pytest with coverage (≥75%) |
make check |
Lint + test (CI gate) |
Versioning
Use semantic versioning (e.g. 0.1.0, 1.0.0). Tag releases so consumers can pin:
algotrading-core>=0.1.0,<1.0.0in research/backendpyproject.toml.
Phases related to algotrading-core
The following phases from source/DEVELOPMENT_PHASES_GUIDE.md are implemented in this repository. Full guide: discovery tips, code examples, and phase-by-phase implementation.
Phase 1: Foundation & Core Package Setup
Goal: Establish shared core package as its own repository and project infrastructure.
Duration: 1–2 weeks.
Tasks:
-
Create core repository (
algotrading-core)- Dedicated repo with installable package structure:
src/algotrading_core/(src layout) - Set up schemas, preprocessing, features, utils
- Define Pydantic schemas for all data types
- Create base classes and interfaces
- Configure
pyproject.toml(package name, version, dependencies: pandas, numpy, pydantic, etc.)
- Dedicated repo with installable package structure:
-
Publish core package
- Publish to private PyPI (see Publishing to private PyPI), or document Git URL for pip install
- Use semantic versioning (e.g.
1.0.0) for releases
-
Set up consumer repositories
- In
algotrading-researchandalgotrading-backend: add dependency onalgotrading-coreinpyproject.toml(version range or Git URL) - Configure development tools (black, ruff, pytest) in each repo
- In
-
Implement core utilities (in this repo)
- Date/time utilities
- Path utilities
- Logging setup
- Configuration loaders
-
Create data schemas (in this repo)
Candleschema (OHLCV data)FeatureschemaSignalschemaConfigschemas
Deliverables:
- ✅
algotrading-corepackage with schemas and utilities, published (private index or Git) - ✅ Research and backend depend on
algotrading-corevia pip; no copied core code - ✅ Working dependency management in all repos
- ✅ Logging infrastructure
- ✅ Configuration system
Files to create (Phase 1):
algotrading-core/
├── src/algotrading_core/
│ ├── schemas/
│ │ ├── candle.py
│ │ ├── feature.py
│ │ ├── model.py
│ │ └── config.py
│ └── utils/
│ ├── datetime_utils.py
│ ├── path_utils.py
│ └── config_loader.py
Phase 2: Data Layer & Preprocessing
Goal: Implement data ingestion, validation, and preprocessing.
Duration: 2–3 weeks.
Tasks:
-
Implement preprocessing functions
- Candle preprocessing (validation, cleaning)
- Future contract adjustments
- Data aggregation logic
- Data transformation pipelines
-
Create data validation layer
- Schema validation
- Data quality checks
- Missing data handling
-
Implement feature engineering base
- Base feature generator class
- Support/resistance level calculation
- Time-based features (trigonometric encoding)
- Volatility features
- Aggregated timeframe features
Deliverables:
- ✅ Preprocessing functions
- ✅ Data validation
- ✅ Feature generation functions
- ✅ Unit tests for all functions
Files to create (Phase 2, under src/algotrading_core/):
src/algotrading_core/
├── preprocessing/
│ ├── candles.py
│ ├── adjustments.py
│ └── transformers.py
└── features/
├── base.py
├── levels.py
├── time_features.py
├── volatility.py
└── aggregated.py
For discovering what to put in core (extract from existing app vs start minimal), code examples, and the rest of the platform phases, see source/DEVELOPMENT_PHASES_GUIDE.md.
References
- CODE_STRUCTURE_GUIDE.md — Layered architecture, Core Layer, phases.
- source/DEVELOPMENT_PHASES_GUIDE.md — Platform repos, Phase 1–2 tasks, repository layout.
- .cursor/rules/algotrading-standards.mdc — Code style, SOLID, testing (when opened in Cursor).
Support/resistance contract (0.6.0)
generate_levels_feature and generate_latest_levels_feature use identical
structural semantics. Every confirmed high is resistance and every low is support,
including inserted extrema. Later closes never reclassify a level. The public
function signatures and feature column names remain unchanged, but the values and
breakout event population change from 0.5.0.
- Natural extrema become available after
orderconfirming bars. An opposite extremum inserted between two same-type natural extrema becomes available when the second natural extremum is confirmed. - Simultaneous natural extrema are ordered by candle index, then low before high. Same-side discovery ties prefer the most recent extremum, then a natural candidate over an inserted duplicate of that extremum. Ties between equal prices inside an insertion interval select the earliest candle.
- A strict candle-body crossing in either direction after the extremum breaks a level. Wick touches, equality and gaps without a body straddle do not break it. A candidate broken before or on discovery is excluded. A later crossing is included in its lifetime: the breaking row retains the level for bar-close breakout detection, and subsequent rows clear it.
- Each new valid same-side discovery supersedes its predecessor. Expiration does not resurrect the older candidate. Appending unchanged-source candles cannot revise previously available levels or breakout events.
Indices identify bar opens; close-based decisions occur after that bar closes. Prefix invariance assumes earlier OHLC values and their adjusted price domain are unchanged. Source revisions or rebuilding futures adjustments are separate data changes, not future-candle appends.
The October 5, 2026 WIN regression at 09:20 discovers natural support 197270 and inserted resistance 197895, in the saved release's adjusted price domain. The 0.5.0 future-close vote classified both as support.
Rebuild feature stores and retrain/evaluate models with this version before promotion. Existing 0.5.0 feature stores and fitted models retain their old contract; changing the package alone does not migrate them. Publish the 0.6.0 artifact, then update and lock both research/backend consumers together. A local source import during verification is not a deployed dependency update.
Metadata
Release files for algotrading-core 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| algotrading_core-0.6.0.tar.gz | 14.4 kB | With provenance | Details for algotrading_core-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| algotrading_core-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for algotrading_core-0.6.0-py3-none-any.whl |
Total release size: 33.7 kB
Release files / algotrading_core-0.6.0.tar.gz
| Download URL | algotrading_core-0.6.0.tar.gz |
|---|---|
| Size | 14.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
11db67bc4c9a4cc969a77dd2e1d70482d4e8d1c9f75b52ff677836e3d7cb28b0
|
|
BLAKE2b-256 checksum How to use checksums |
7ed1b67c74394dc60845c9aefe8d85f9ddde9418ac0e8c40cf8fffa75eb13d86
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logRelease files / algotrading_core-0.6.0-py3-none-any.whl
| Download URL | algotrading_core-0.6.0-py3-none-any.whl |
|---|---|
| Size | 19.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
78dac6f8ca0a2b442ded30f99bf8dee4694d069826d0dabdf2b7ca56f66f4327
|
|
BLAKE2b-256 checksum How to use checksums |
57b6b5c8c6418072a7fbddd0601af1b1746e718999ca7c938f78badf0e39efc6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logSecurity for algotrading-core 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for algotrading_core-0.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.