ForexGrand Strategy Modelling Core

ForexGrand Strategy Modelling Core is a Python package for building forex strategy modelling workflows. It includes utilities for loading market data from Cloudflare R2, preparing TFRecord datasets, training models, evaluating model quality, and packaging trained models for deployment.

The distribution name is fg-strategy-modelling-core; the Python import package is forexgrand_core.

Features

• Cloudflare R2-backed storage access through the S3-compatible API.
• A runtime configuration helper so users do not have to manually export environment variables.
• Data loading and local caching for symbol market data.
• Dataset generation utilities for train, evaluation, and test workflows.
• Training pipelines for neural-network, KNN, XGBoost, and no-train target models.
• Model evaluation, performance checks, and model publishing helpers.
• Extensible preprocessing classes for custom feature pipelines.

Installation

Install from PyPI:

pip install fg-strategy-modelling-core

Install from source for development:

git clone https://github.com/forexgrand/fg-strategy-modelling-core.git
cd fg-strategy-modelling-core
pip install -e ".[dev]"

Command Line Interface

Installing the package provides an fg_core command with data workflow subcommands:

fg_core download_data EURUSD forex --bucket forexgrand-data --source mt5
fg_core generate_train_data EURUSD forex --sequence-length 2800 --stride 100
fg_core preprocess_data prices.parquet preprocess.py --output data/processed.pkl.gz

preprocess.py must define preprocess_fn(dataframe). The input can be CSV, Parquet, or a pickle file, and the preprocessing result is saved as a gzip-compressed pickle. Each command prints a JSON object containing its output path and summary information. Storage credentials and other runtime settings use the same environment variables as the Python API.

Configure Cloudflare R2

The package currently supports Cloudflare R2 storage. Configure it at the start of your script with configure_r2:

from forexgrand_core import configure_r2

settings = configure_r2(
    account_id="your-cloudflare-account-id",
    access_key_id="your-r2-access-key-id",
    secret_access_key="your-r2-secret-access-key",
    bucket_name="forexgrand-data",
    train_bucket_name="forexgrand-train",
    eval_bucket_name="forexgrand-eval",
    test_bucket_name="forexgrand-test",
    model_upload_bucket="forexgrand-models",
)

You can pass endpoint="https://<account-id>.r2.cloudflarestorage.com" instead of account_id if you already have the full endpoint.

configure_r2 sets these environment variables for the current Python process and returns a fresh Settings object:

If bucket-specific names are omitted, bucket_name is reused for all buckets.

Load Market Data

from forexgrand_core import configure_r2
from forexgrand_core.data_manager import DataManager

configure_r2(
    account_id="your-cloudflare-account-id",
    access_key_id="your-r2-access-key-id",
    secret_access_key="your-r2-secret-access-key",
    bucket_name="forexgrand-data",
)

manager = DataManager(base_bucket_name="forexgrand-data")
df, properties = manager.load_data(
    symbol_pair="EURUSD",
    instrument_group="forex",
)

Generate Training Data

import tensorflow as tf
from forexgrand_core import configure_r2
from forexgrand_core.pipeline.no_train_trainer import NoTrainTrainer
from forexgrand_core.pipeline.preprocessing.base_preprocessor import PreprocessBase
from forexgrand_core.schemas import SymbolIn, TimeBasedTarget


class Preprocess(PreprocessBase):
    def preprocess(self, data, training=False):
        return {"direction": tf.zeros(tf.shape(data["close"])[0], dtype=tf.int64)}

    def features_metadata(self):
        return {"direction": tf.io.FixedLenFeature([], tf.int64)}

configure_r2(
    account_id="your-cloudflare-account-id",
    access_key_id="your-r2-access-key-id",
    secret_access_key="your-r2-secret-access-key",
    bucket_name="forexgrand-data",
)

trainer = NoTrainTrainer(
    symbols=[SymbolIn(symbol="EURUSD", group="forex")],
    sequence_length=2800,
    preprocessor_class=Preprocess,
    target_model_type=TimeBasedTarget(stop_minutes=60, mode="prices"),
    run_performance_test=False,
    hot_reload_data=False,
    upload_models=True,
    target_percentile=99,
    use_dataframe_format=False,
)
results = trainer.run()

For data generation APIs, pass source explicitly when the data is not under the DATA_SOURCE environment value:

data_gen.load_single_data(..., source="metaquotes")
data_gen.load_data(..., source="metaquotes")

Validate Configuration

Configuration is not validated on package import, so import forexgrand_core works before credentials are available. Validate explicitly when you want a clear setup error:

from forexgrand_core.env_validator import validate_environment_on_import

validate_environment_on_import()

Build And Publish To PyPI

Install build tools:

python -m pip install --upgrade build twine

Build the source distribution and wheel:

python -m build

Check the package:

python -m twine check dist/*

Upload to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Upload to PyPI:

python -m twine upload dist/*

Development

Run tests:

pytest

Build locally:

python -m build

Check imports:

import forexgrand_core
from forexgrand_core import configure_r2, Settings

License

MIT