algotrading-core 0.1.0__tar.gz

algotrading_core-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+.uv/
+uv.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Cursor
+.cursor/
+
+# Testing / coverage
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+
+# Environment
+.env
+.env.local
+*.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/

algotrading_core-0.1.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: algotrading-core
+Version: 0.1.0
+Summary: Shared core package: schemas, preprocessing, features, and utils for the algorithmic trading platform
+Requires-Python: <4,>=3.11
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: pandas<3,>=2.0
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pyyaml<7,>=6.0
+Description-Content-Type: text/markdown
+
+# 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](../CODE_STRUCTURE_GUIDE.md) (Core Layer) and [source/DEVELOPMENT_PHASES_GUIDE.md](../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)
+
+```bash
+uv add /path/to/algotrading-core
+# or
+pip install -e /path/to/algotrading-core
+```
+
+### From Git
+
+```bash
+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](#publishing-to-private-pypi) for index URL and auth), then:
+
+```bash
+pip install algotrading-core==0.1.0
+```
+
+---
+
+## 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:
+
+```bash
+git tag v0.2.0
+```
+
+### 2. Build the package
+
+```bash
+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`:
+
+```ini
+[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**
+
+```bash
+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
+
+```bash
+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.
+
+```python
+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
+
+```bash
+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.0` in research/backend `pyproject.toml`.
+
+---
+
+## Phases related to algotrading-core
+
+The following phases from [source/DEVELOPMENT_PHASES_GUIDE.md](../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**:
+1. **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.)
+
+2. **Publish core package**
+   - Publish to private PyPI (see [Publishing to private PyPI](#publishing-to-private-pypi)), or document Git URL for pip install
+   - Use semantic versioning (e.g. `1.0.0`) for releases
+
+3. **Set up consumer repositories**
+   - In `algotrading-research` and `algotrading-backend`: add dependency on `algotrading-core` in `pyproject.toml` (version range or Git URL)
+   - Configure development tools (black, ruff, pytest) in each repo
+
+4. **Implement core utilities** (in this repo)
+   - Date/time utilities
+   - Path utilities
+   - Logging setup
+   - Configuration loaders
+
+5. **Create data schemas** (in this repo)
+   - `Candle` schema (OHLCV data)
+   - `Feature` schema
+   - `Signal` schema
+   - `Config` schemas
+
+**Deliverables**:
+- ✅ `algotrading-core` package with schemas and utilities, published (private index or Git)
+- ✅ Research and backend depend on `algotrading-core` via 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**:
+1. **Implement preprocessing functions**
+   - Candle preprocessing (validation, cleaning)
+   - Future contract adjustments
+   - Data aggregation logic
+   - Data transformation pipelines
+
+2. **Create data validation layer**
+   - Schema validation
+   - Data quality checks
+   - Missing data handling
+
+3. **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](../source/DEVELOPMENT_PHASES_GUIDE.md).
+
+---
+
+## References
+
+- [CODE_STRUCTURE_GUIDE.md](../CODE_STRUCTURE_GUIDE.md) — Layered architecture, Core Layer, phases.
+- [source/DEVELOPMENT_PHASES_GUIDE.md](../source/DEVELOPMENT_PHASES_GUIDE.md) — Platform repos, Phase 1–2 tasks, repository layout.
+- [.cursor/rules/algotrading-standards.mdc](.cursor/rules/algotrading-standards.mdc) — Code style, SOLID, testing (when opened in Cursor).

algotrading_core-0.1.0/README.md

@@ -0,0 +1,303 @@
+# 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](../CODE_STRUCTURE_GUIDE.md) (Core Layer) and [source/DEVELOPMENT_PHASES_GUIDE.md](../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)
+
+```bash
+uv add /path/to/algotrading-core
+# or
+pip install -e /path/to/algotrading-core
+```
+
+### From Git
+
+```bash
+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](#publishing-to-private-pypi) for index URL and auth), then:
+
+```bash
+pip install algotrading-core==0.1.0
+```
+
+---
+
+## 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:
+
+```bash
+git tag v0.2.0
+```
+
+### 2. Build the package
+
+```bash
+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`:
+
+```ini
+[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**
+
+```bash
+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
+
+```bash
+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.
+
+```python
+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
+
+```bash
+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.0` in research/backend `pyproject.toml`.
+
+---
+
+## Phases related to algotrading-core
+
+The following phases from [source/DEVELOPMENT_PHASES_GUIDE.md](../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**:
+1. **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.)
+
+2. **Publish core package**
+   - Publish to private PyPI (see [Publishing to private PyPI](#publishing-to-private-pypi)), or document Git URL for pip install
+   - Use semantic versioning (e.g. `1.0.0`) for releases
+
+3. **Set up consumer repositories**
+   - In `algotrading-research` and `algotrading-backend`: add dependency on `algotrading-core` in `pyproject.toml` (version range or Git URL)
+   - Configure development tools (black, ruff, pytest) in each repo
+
+4. **Implement core utilities** (in this repo)
+   - Date/time utilities
+   - Path utilities
+   - Logging setup
+   - Configuration loaders
+
+5. **Create data schemas** (in this repo)
+   - `Candle` schema (OHLCV data)
+   - `Feature` schema
+   - `Signal` schema
+   - `Config` schemas
+
+**Deliverables**:
+- ✅ `algotrading-core` package with schemas and utilities, published (private index or Git)
+- ✅ Research and backend depend on `algotrading-core` via 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**:
+1. **Implement preprocessing functions**
+   - Candle preprocessing (validation, cleaning)
+   - Future contract adjustments
+   - Data aggregation logic
+   - Data transformation pipelines
+
+2. **Create data validation layer**
+   - Schema validation
+   - Data quality checks
+   - Missing data handling
+
+3. **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](../source/DEVELOPMENT_PHASES_GUIDE.md).
+
+---
+
+## References
+
+- [CODE_STRUCTURE_GUIDE.md](../CODE_STRUCTURE_GUIDE.md) — Layered architecture, Core Layer, phases.
+- [source/DEVELOPMENT_PHASES_GUIDE.md](../source/DEVELOPMENT_PHASES_GUIDE.md) — Platform repos, Phase 1–2 tasks, repository layout.
+- [.cursor/rules/algotrading-standards.mdc](.cursor/rules/algotrading-standards.mdc) — Code style, SOLID, testing (when opened in Cursor).

algotrading_core-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "algotrading-core"
+version = "0.1.0"
+description = "Shared core package: schemas, preprocessing, features, and utils for the algorithmic trading platform"
+readme = "README.md"
+requires-python = ">=3.11,<4"
+dependencies = [
+    "pandas>=2.0,<3",
+    "numpy>=1.24,<3",
+    "pydantic>=2.0,<3",
+    "pyyaml>=6.0,<7",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/algotrading_core"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/algotrading_core"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "--strict-markers -v"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[dependency-groups]
+dev = [
+    "black>=26.1.0",
+    "build>=1.2.0",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.14",
+    "twine>=6.0.0",
+]

algotrading_core-0.1.0/src/algotrading_core/features/__init__.py

@@ -0,0 +1,7 @@
+"""Feature engineering for algorithmic trading."""
+
+from algotrading_core.features.levels import generate_levels_feature
+
+__all__ = [
+    "generate_levels_feature",
+]

algotrading_core-0.1.0/src/algotrading_core/features/levels.py

@@ -0,0 +1,297 @@
+"""Support and resistance levels feature generation."""
+
+import logging
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from scipy.signal import argrelextrema
+
+logger = logging.getLogger(__name__)
+
+_REQUIRED_OHLC_COLUMNS = ["open", "high", "low", "close"]
+
+
+def _validate_ohlc_columns(df: pd.DataFrame, context: str = "") -> None:
+    """Validate DataFrame has required OHLC columns.
+
+    Args:
+        df: DataFrame to validate.
+        context: Optional context for error message.
+
+    Raises:
+        ValueError: If any required column is missing.
+    """
+    missing = set(_REQUIRED_OHLC_COLUMNS) - set(df.columns)
+    if missing:
+        raise ValueError(
+            f"❌ Missing required columns: {sorted(missing)}\n"
+            f"   Available columns: {sorted(df.columns)}\n"
+            f"   Context: {context or 'levels feature'}"
+        )
+
+
+def _levels_dict_to_dataframe(levels_dict: dict) -> pd.DataFrame:
+    """Convert levels dict to DataFrame with start_date, end_date, level.
+
+    Args:
+        levels_dict: Dict mapping start_date -> (level, end_date).
+
+    Returns:
+        DataFrame with columns start_date, end_date, level, sorted by start_date.
+    """
+    levels_df = pd.DataFrame.from_dict(levels_dict, orient="index", columns=["level", "end_date"])
+    levels_df.index.name = "start_date"
+    levels_df = levels_df.reset_index().sort_values(by="start_date")
+    return levels_df
+
+
+def _compute_is_support_per_level(df: pd.DataFrame, levels_df: pd.DataFrame) -> pd.Series:
+    """Compute whether each level acts as support (True) or resistance (False).
+
+    A level is support when more closes in its range are above the level than below.
+
+    Args:
+        df: OHLC DataFrame with datetime index.
+        levels_df: DataFrame with columns start_date, end_date, level.
+
+    Returns:
+        Boolean Series indexed by levels_df index (True = support, False = resistance).
+    """
+    is_support_list = []
+    for row in levels_df.itertuples():
+        end = row.end_date if pd.notna(row.end_date) else df.index[-1]
+        valid_close = df.loc[row.start_date : end, "close"]
+        below = (valid_close <= row.level).sum()
+        above = (valid_close > row.level).sum()
+        is_support_list.append(below < above)
+    return pd.Series(is_support_list, index=levels_df.index)
+
+
+def _assign_levels_vectorized(
+    df: pd.DataFrame,
+    levels_df: pd.DataFrame,
+    column_name: str,
+) -> pd.DataFrame:
+    """Assign support/resistance level to each row using merge_asof (vectorized).
+
+    Args:
+        df: OHLC DataFrame; modified in place with new columns.
+        levels_df: DataFrame with start_date, end_date, level, is_support.
+        column_name: Base name for output columns (e.g. closest_level_10th_order).
+
+    Returns:
+        df with columns {column_name}_support and {column_name}_resistance added.
+    """
+    support_col = f"{column_name}_support"
+    resistance_col = f"{column_name}_resistance"
+    df[support_col] = np.nan
+    df[resistance_col] = np.nan
+
+    if levels_df.empty:
+        return df
+
+    levels_sorted = levels_df.sort_values("start_date").copy()
+    df_sorted = df.sort_index()
+    merged = pd.merge_asof(
+        df_sorted,
+        levels_sorted,
+        left_index=True,
+        right_on="start_date",
+        direction="backward",
+    )
+    in_range = (merged.index >= merged["start_date"]) & (
+        merged["end_date"].isna() | (merged.index <= merged["end_date"])
+    )
+    merged[support_col] = np.where(merged["is_support"] & in_range, merged["level"], np.nan)
+    merged[resistance_col] = np.where(~merged["is_support"] & in_range, merged["level"], np.nan)
+    df[support_col] = merged[support_col].reindex(df.index).values
+    df[resistance_col] = merged[resistance_col].reindex(df.index).values
+    return df
+
+
+def generate_levels_feature(
+    df: pd.DataFrame,
+    order: int,
+) -> pd.DataFrame:
+    """Create support and resistance level features.
+
+    Args:
+        df: DataFrame containing OHLC candle data with datetime index.
+        order: Order for local extrema (number of candles per side).
+
+    Returns:
+        DataFrame with added columns {column_name}_support and {column_name}_resistance,
+        where column_name is closest_level_{order}th_order.
+    """
+    _validate_ohlc_columns(df, context="generate_levels_feature")
+    column_name = f"closest_level_{order}th_order"
+    levels_dict = _build_levels(df, order)
+    if not levels_dict:
+        logger.debug("🔄 No levels found for order=%d, leaving support/resistance empty", order)
+        df[f"{column_name}_support"] = np.nan
+        df[f"{column_name}_resistance"] = np.nan
+        return df
+
+    levels_df = _levels_dict_to_dataframe(levels_dict)
+    levels_df["is_support"] = _compute_is_support_per_level(df, levels_df)
+    return _assign_levels_vectorized(df, levels_df, column_name)
+
+
+def _detect_levels(df: pd.DataFrame, order: int = 10) -> dict[Any, tuple[float, Any | None]]:
+    """Detect support and resistance levels using local extrema.
+
+    Identifies local minima (support) and maxima (resistance) in price data.
+    Ensures intercalation of support and resistance levels.
+
+    Args:
+        df: DataFrame with at least 'low' and 'high' and datetime index.
+        order: Number of candles to consider for local extrema.
+
+    Returns:
+        Dict mapping start_date -> (price_level, None). None reserved for end_date.
+    """
+    _validate_ohlc_columns(df, context="_detect_levels")
+    low_prices = df["low"].to_numpy()
+    high_prices = df["high"].to_numpy()
+    dates = df.index.to_numpy()
+
+    local_minima = argrelextrema(low_prices, np.less, order=order)[0]
+    local_maxima = argrelextrema(high_prices, np.greater, order=order)[0]
+
+    levels = np.concatenate(
+        [
+            np.column_stack((local_minima, low_prices[local_minima], np.zeros(len(local_minima)))),
+            np.column_stack((local_maxima, high_prices[local_maxima], np.ones(len(local_maxima)))),
+        ]
+    )
+    levels = levels[levels[:, 0].argsort()]
+
+    valid_indices = (levels[:, 0] >= order) & (levels[:, 0] < len(df) - order)
+    levels = levels[valid_indices.astype(bool)]
+
+    intercalated_levels = _intercalate_levels(levels, low_prices, high_prices)
+    if not intercalated_levels.size:
+        return {}
+
+    return {dates[int(idx)]: (float(price), None) for idx, price, _ in intercalated_levels}
+
+
+def _intercalate_levels(
+    levels: np.ndarray,
+    low_prices: np.ndarray,
+    high_prices: np.ndarray,
+) -> np.ndarray:
+    """Ensure support and resistance levels alternate by inserting intermediate levels.
+
+    Args:
+        levels: Array of (index, price, type) with type 0=support, 1=resistance.
+        low_prices: Full low price array.
+        high_prices: Full high price array.
+
+    Returns:
+        Array of intercalated (index, price, type).
+    """
+    intercalated: list[list[float]] = []
+    for i in range(len(levels) - 1):
+        current_type = levels[i, 2]
+        next_type = levels[i + 1, 2]
+        if current_type == next_type:
+            start_idx, end_idx = int(levels[i, 0]), int(levels[i + 1, 0])
+            if current_type == 0:
+                intermediate_idx = np.argmax(high_prices[start_idx:end_idx]) + start_idx
+                intercalated.append([float(intermediate_idx), high_prices[intermediate_idx], 1.0])
+            else:
+                intermediate_idx = np.argmin(low_prices[start_idx:end_idx]) + start_idx
+                intercalated.append([float(intermediate_idx), low_prices[intermediate_idx], 0.0])
+        intercalated.append(levels[i].tolist())
+    if levels.shape[0] > 0:
+        intercalated.append(levels[-1].tolist())
+    return np.array(intercalated)
+
+
+def _compute_level_end_dates(
+    df: pd.DataFrame,
+    levels: dict[Any, tuple[float, Any | None]],
+) -> dict[Any, tuple[float, Any | None]]:
+    """Compute end date for each level (first price crossing).
+
+    Filters levels by subsequent price action: end_date is when price first
+    crosses the level, or None if it never does.
+
+    Args:
+        df: DataFrame with 'open' and 'close' and datetime index.
+        levels: Dict mapping start_date -> (price_level, None).
+
+    Returns:
+        Dict mapping start_date -> (price_level, end_date). end_date is when
+        price first crosses the level, or None if never.
+    """
+    _validate_ohlc_columns(df, context="_compute_level_end_dates")
+    open_prices = df["open"].to_numpy()
+    close_prices = df["close"].to_numpy()
+    dates = df.index.to_numpy()
+
+    filtered_levels: dict[Any, tuple[float, Any | None]] = {}
+    for date, (price, _) in levels.items():
+        idx = np.searchsorted(dates, date)
+        future_open = open_prices[idx + 1 :]
+        future_close = close_prices[idx + 1 :]
+        crossing = (future_open > price) & (future_close < price) | (
+            (future_open < price) & (future_close > price)
+        )
+        filtered_idx = np.argmax(crossing) if crossing.any() else None
+        filtered_date = dates[idx + 1 + filtered_idx] if filtered_idx is not None else None
+        filtered_levels[date] = (price, filtered_date)
+    return filtered_levels
+
+
+def _offset_levels(
+    df: pd.DataFrame,
+    levels: dict[Any, tuple[float, Any | None]],
+    order: int,
+) -> dict[Any, tuple[float, Any | None]]:
+    """Offset level start dates by order candles.
+
+    Args:
+        df: DataFrame with datetime index.
+        levels: Dict mapping start_date -> (price_level, end_date).
+        order: Number of candles to offset.
+
+    Returns:
+        Dict mapping (offset) start_date -> (price_level, end_date).
+    """
+    dates = df.index.to_numpy()
+    result: dict[Any, tuple[float, Any | None]] = {}
+    previous_end_date: Any | None = None
+
+    for start_date, (value, end_date) in levels.items():
+        idx = np.searchsorted(dates, start_date)
+        offset_idx = min(idx + order, len(dates) - 1)
+        offset_date = dates[offset_idx]
+
+        if previous_end_date is not None and offset_date > previous_end_date:
+            result[previous_end_date] = (value, end_date)
+        else:
+            result[offset_date] = (value, end_date)
+        previous_end_date = end_date
+    return result
+
+
+def _build_levels(df: pd.DataFrame, order: int = 10) -> dict[Any, tuple[float, Any | None]]:
+    """Build levels pipeline: detect, compute end dates, then offset.
+
+    Args:
+        df: DataFrame with OHLC and datetime index.
+        order: Order for local extrema and offset.
+
+    Returns:
+        Dict mapping start_date -> (price_level, end_date). Empty dict if no levels.
+    """
+    _validate_ohlc_columns(df, context="_build_levels")
+    levels_dict = _detect_levels(df, order)
+    if not levels_dict:
+        return {}
+    levels_dict = _compute_level_end_dates(df, levels_dict)
+    levels_dict = _offset_levels(df, levels_dict, order)
+    return levels_dict

algotrading_core-0.1.0/src/algotrading_core/schemas/__init__.py

@@ -0,0 +1,7 @@
+"""Shared schemas for algotrading-core."""
+
+from algotrading_core.schemas.candle import Candle
+
+__all__ = [
+    "Candle",
+]

algotrading_core-0.1.0/src/algotrading_core/schemas/candle.py

@@ -0,0 +1,26 @@
+"""Candle (OHLCV) schema."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class Candle(BaseModel):
+    """Single candlestick: timestamp and OHLCV.
+
+    Matches CSV format with columns: date, open, high, low, close, volume.
+    """
+
+    date: datetime = Field(..., description="Candle timestamp (e.g. 2012-07-02 09:00:00)")
+    open: float = Field(..., gt=0, description="Open price")
+    high: float = Field(..., gt=0, description="High price")
+    low: float = Field(..., gt=0, description="Low price")
+    close: float = Field(..., gt=0, description="Close price")
+    volume: float = Field(..., ge=0, description="Trading volume")
+
+    @model_validator(mode="after")
+    def high_not_below_low(self) -> "Candle":
+        """Ensure high >= low."""
+        if self.high < self.low:
+            raise ValueError(f"❌ high ({self.high}) must be >= low ({self.low})")
+        return self

algotrading_core-0.1.0/src/algotrading_core/utils/__init__.py

@@ -0,0 +1,15 @@
+"""Shared utilities for algotrading-core."""
+
+from algotrading_core.utils.path_utils import (
+    add_project_to_sys_path,
+    get_project_root,
+    get_project_subpath,
+)
+from algotrading_core.utils.setup_logger import setup_logger
+
+__all__ = [
+    "add_project_to_sys_path",
+    "get_project_root",
+    "get_project_subpath",
+    "setup_logger",
+]

algotrading_core-0.1.0/src/algotrading_core/utils/path_utils.py

@@ -0,0 +1,97 @@
+"""Path utilities for algotrading projects.
+
+Works for any project that has pyproject.toml at the root. Supports:
+- algotrading-core: src layout (use subpath=\"src\" when adding to sys.path).
+- algotrading-research, algotrading-backend, algotrading-execution: package
+  dirs at project root (use subpath=None when adding to sys.path).
+"""
+
+import sys
+from pathlib import Path
+
+_PYPROJECT_FILENAME = "pyproject.toml"
+
+
+def get_project_root() -> Path:
+    """Return the project root directory (directory containing pyproject.toml).
+
+    Walks up from this file's location until pyproject.toml is found.
+    Works when run from an installed package or from source.
+
+    Returns:
+        Absolute path to project root.
+
+    Raises:
+        FileNotFoundError: If pyproject.toml is not found in any parent directory.
+    """
+    current = Path(__file__).resolve().parent
+    for parent in current.parents:
+        if (parent / _PYPROJECT_FILENAME).exists():
+            return parent
+    raise FileNotFoundError(
+        f"❌ '{_PYPROJECT_FILENAME}' not found in any parent of {current}\n"
+        "   Run from the project tree."
+    )
+
+
+def get_project_subpath(relative_path: str = "") -> Path:
+    """Return a path under project root.
+
+    Use for any project layout: e.g. "src/algotrading_core", "ml", "backend",
+    "execution_agent". Empty string returns project root.
+
+    Args:
+        relative_path: Path relative to project root (forward slashes). Use ""
+            for project root.
+
+    Returns:
+        Absolute path: project_root / relative_path.
+
+    Raises:
+        FileNotFoundError: If relative_path is non-empty and the resolved path
+            does not exist.
+    """
+    root = get_project_root()
+    if not relative_path:
+        return root
+    resolved = (root / relative_path).resolve()
+    if not resolved.exists():
+        raise FileNotFoundError(
+            f"❌ Path not found: {resolved}\n   Relative to project root: {relative_path!r}"
+        )
+    return resolved
+
+
+def add_project_to_sys_path(subpath: str | None = None) -> str:
+    """Prepend a path under project root to sys.path if not already present.
+
+    Use so that top-level packages are importable without installing.
+    Idempotent.
+
+    - algotrading-core (src layout): use subpath=\"src\" so ``import algotrading_core`` works.
+    - algotrading-research, algotrading-backend, algotrading-execution (packages
+      at root): use subpath=None so ``import ml``, ``import backend``, etc. work.
+
+    Args:
+        subpath: Path relative to project root to add (e.g. "src"). None adds
+            project root.
+
+    Returns:
+        The path that was ensured in sys.path (as string).
+
+    Raises:
+        FileNotFoundError: If subpath is given and that directory does not exist.
+    """
+    root = get_project_root()
+    if subpath is None:
+        path_to_add = root
+    else:
+        path_to_add = root / subpath
+        if not path_to_add.is_dir():
+            raise FileNotFoundError(
+                f"❌ Directory not found: {path_to_add}\n   Subpath: {subpath!r}"
+            )
+    path_str = str(path_to_add)
+    if path_str not in sys.path:
+        sys.path.insert(0, path_str)
+    return path_str

algotrading_core-0.1.0/src/algotrading_core/utils/setup_logger.py

@@ -0,0 +1,83 @@
+"""Logging setup for algotrading-core."""
+
+import logging
+import os
+import sys
+from datetime import datetime
+
+_DEFAULT_LOG_FOLDER = "log"
+_DEFAULT_LOG_LEVEL = logging.INFO
+
+
+def _make_log_path(log_folder: str) -> str:
+    """Build full path for today's log file.
+
+    Args:
+        log_folder: Directory to write log files into.
+
+    Returns:
+        Full path: log_folder/YYYY-MM-DD_HH-MM-SS.log
+    """
+    now = datetime.now()
+    log_filename = f"{now.strftime('%Y-%m-%d_%H-%M-%S')}.log"
+    return os.path.join(log_folder, log_filename)
+
+
+def _create_formatter() -> logging.Formatter:
+    """Create standard log formatter."""
+    return logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+
+def _add_handlers(
+    logger: logging.Logger,
+    log_path: str,
+    log_level: int,
+    formatter: logging.Formatter,
+) -> None:
+    """Add file and console handlers to root logger if none present.
+
+    Args:
+        logger: Root logger to configure.
+        log_path: Full path for the log file.
+        log_level: Level for handlers.
+        formatter: Formatter for both handlers.
+    """
+    file_handler = logging.FileHandler(log_path)
+    file_handler.setFormatter(formatter)
+    file_handler.setLevel(log_level)
+    logger.addHandler(file_handler)
+
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(formatter)
+    console_handler.setLevel(log_level)
+    logger.addHandler(console_handler)
+
+
+def setup_logger(
+    log_folder: str = _DEFAULT_LOG_FOLDER,
+    log_level: int = _DEFAULT_LOG_LEVEL,
+) -> tuple[logging.Logger, str]:
+    """Configure root logger with file and console handlers.
+
+    Creates log_folder if it does not exist. Uses a timestamped log filename.
+    Handlers are added only if the root logger has no handlers yet (idempotent).
+
+    Args:
+        log_folder: Directory for log files. Defaults to "log".
+        log_level: Logging level (e.g. logging.INFO). Defaults to INFO.
+
+    Returns:
+        Tuple of (root logger, log filename only, e.g. "2025-01-29_12-00-00.log").
+    """
+    log_path = _make_log_path(log_folder)
+    log_filename = os.path.basename(log_path)
+    os.makedirs(log_folder, exist_ok=True)
+
+    logger = logging.getLogger()
+    logger.setLevel(log_level)
+
+    if not logger.handlers:
+        formatter = _create_formatter()
+        _add_handlers(logger, log_path, log_level, formatter)
+
+    return logger, log_filename