synthetic-ohlcv 0.1.0__tar.gz

synthetic_ohlcv-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.vscode/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+*.egg-info/
+*.py[cod]
+.DS_Store
+exports/*

synthetic_ohlcv-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: synthetic-ohlcv
+Version: 0.1.0
+Summary: Interactive synthetic OHLCV kline generator for learnable trading experiments.
+Keywords: fastapi,klines,ohlcv,synthetic-data,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.136.1
+Requires-Dist: numpy<3,>=2.3.0
+Requires-Dist: polars>=1.40.1
+Requires-Dist: pydantic>=2.13.3
+Requires-Dist: uvicorn>=0.46.0
+Description-Content-Type: text/markdown
+
+# Synthetic Klines
+
+Standalone synthetic OHLCV kline generator for learnable trading experiments.
+
+Requires Python 3.11 or newer.
+
+## Installation
+
+Install from PyPI with `pip`:
+
+```bash
+python -m pip install synthetic-ohlcv
+```
+
+Or install with `uv`:
+
+```bash
+uv pip install synthetic-ohlcv
+```
+
+## Run The App
+
+After installation, run:
+
+```bash
+synthetic-ohlcv
+```
+
+Open `http://127.0.0.1:8100`.
+
+For local development, you can also run:
+
+```bash
+uv run synthetic-ohlcv
+```
+
+Use a custom port when needed:
+
+```bash
+uv run synthetic-ohlcv --port 8110
+```
+
+## Python API
+
+```python
+from synthetic_ohlcv import SyntheticKlinesConfig, make_synthetic_ohlcv
+
+frame = make_synthetic_ohlcv(SyntheticKlinesConfig(rows=4_000, seed=43))
+```
+
+Generated datasets contain exactly:
+
+```text
+timestamp, open, high, low, close, volume, turnover
+```

synthetic_ohlcv-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Synthetic Klines
+
+Standalone synthetic OHLCV kline generator for learnable trading experiments.
+
+Requires Python 3.11 or newer.
+
+## Installation
+
+Install from PyPI with `pip`:
+
+```bash
+python -m pip install synthetic-ohlcv
+```
+
+Or install with `uv`:
+
+```bash
+uv pip install synthetic-ohlcv
+```
+
+## Run The App
+
+After installation, run:
+
+```bash
+synthetic-ohlcv
+```
+
+Open `http://127.0.0.1:8100`.
+
+For local development, you can also run:
+
+```bash
+uv run synthetic-ohlcv
+```
+
+Use a custom port when needed:
+
+```bash
+uv run synthetic-ohlcv --port 8110
+```
+
+## Python API
+
+```python
+from synthetic_ohlcv import SyntheticKlinesConfig, make_synthetic_ohlcv
+
+frame = make_synthetic_ohlcv(SyntheticKlinesConfig(rows=4_000, seed=43))
+```
+
+Generated datasets contain exactly:
+
+```text
+timestamp, open, high, low, close, volume, turnover
+```

synthetic_ohlcv-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling>=1.28"]
+build-backend = "hatchling.build"
+
+[project]
+name = "synthetic-ohlcv"
+version = "0.1.0"
+description = "Interactive synthetic OHLCV kline generator for learnable trading experiments."
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["ohlcv", "synthetic-data", "trading", "klines", "fastapi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "fastapi>=0.136.1",
+    "numpy>=2.3.0,<3",
+    "polars>=1.40.1",
+    "pydantic>=2.13.3",
+    "uvicorn>=0.46.0",
+]
+
+[project.scripts]
+synthetic-ohlcv = "synthetic_ohlcv.server:main"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.12",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/README.md",
+    "/src",
+    "/tests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/synthetic_ohlcv"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "RUF"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = [
+    "--cov=synthetic_ohlcv",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+
+[tool.coverage.report]
+exclude_also = [
+    "if __name__ == .__main__.:",
+]

synthetic_ohlcv-0.1.0/src/synthetic_ohlcv/__init__.py

@@ -0,0 +1,44 @@
+"""Independent synthetic OHLCV kline generator and local preview app."""
+
+from synthetic_ohlcv.config import (
+    CycleComponent,
+    JumpShockConfig,
+    MeanReversionConfig,
+    RegimeShiftConfig,
+    SyntheticKlinesConfig,
+    VolatilityClusterConfig,
+)
+from synthetic_ohlcv.controls import (
+    CONFIG_CONTROL_PATHS,
+    ControlGroup,
+    ControlOption,
+    ControlSpec,
+    control_schema,
+    control_schema_payload,
+)
+from synthetic_ohlcv.generator import (
+    KLINE_COLUMNS,
+    make_synthetic_ohlcv,
+    make_synthetic_ohlcv_with_metadata,
+)
+from synthetic_ohlcv.io import SaveResult, save_synthetic_ohlcv
+
+__all__ = [
+    "CONFIG_CONTROL_PATHS",
+    "KLINE_COLUMNS",
+    "ControlGroup",
+    "ControlOption",
+    "ControlSpec",
+    "CycleComponent",
+    "JumpShockConfig",
+    "MeanReversionConfig",
+    "RegimeShiftConfig",
+    "SaveResult",
+    "SyntheticKlinesConfig",
+    "VolatilityClusterConfig",
+    "control_schema",
+    "control_schema_payload",
+    "make_synthetic_ohlcv",
+    "make_synthetic_ohlcv_with_metadata",
+    "save_synthetic_ohlcv",
+]

synthetic_ohlcv-0.1.0/src/synthetic_ohlcv/config.py

@@ -0,0 +1,94 @@
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+DEFAULT_INTERVAL_MS = 15 * 60 * 1000
+DEFAULT_START_TIMESTAMP = 1_609_459_200_000
+DEFAULT_EXPORT_DIR = Path("exports")
+
+CycleKind = Literal["sine", "cosine"]
+
+
+class BaseConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class CycleComponent(BaseConfig):
+    kind: CycleKind = "sine"
+    amplitude: float = Field(default=0.0014, ge=0.0)
+    period: int = Field(default=96, ge=2)
+    phase: float = 0.0
+    decay: float = Field(default=0.0, ge=0.0)
+
+
+class RegimeShiftConfig(BaseConfig):
+    enabled: bool = False
+    count: int = Field(default=3, ge=1, le=20)
+    amplitude: float = Field(default=0.00025, ge=0.0)
+    transition_steps: int = Field(default=48, ge=1)
+
+
+class VolatilityClusterConfig(BaseConfig):
+    enabled: bool = False
+    strength: float = Field(default=0.35, ge=0.0)
+    persistence: float = Field(default=0.92, ge=0.0, lt=1.0)
+
+
+class JumpShockConfig(BaseConfig):
+    enabled: bool = False
+    probability: float = Field(default=0.002, ge=0.0, le=1.0)
+    scale: float = Field(default=0.006, ge=0.0)
+
+
+class MeanReversionConfig(BaseConfig):
+    enabled: bool = False
+    strength: float = Field(default=0.025, ge=0.0, le=1.0)
+    window: int = Field(default=96, ge=2)
+
+
+def default_cycles() -> list[CycleComponent]:
+    return [
+        CycleComponent(kind="sine", amplitude=0.0014, period=96, phase=0.0),
+        CycleComponent(kind="cosine", amplitude=0.00045, period=672, phase=0.75),
+    ]
+
+
+class SyntheticKlinesConfig(BaseConfig):
+    rows: int = Field(default=4_000, ge=2, le=100_000)
+    seed: int = 43
+    base_price: float = Field(default=10_000.0, gt=0.0)
+    start_timestamp: int = Field(default=DEFAULT_START_TIMESTAMP, ge=0)
+    interval_ms: int = Field(default=DEFAULT_INTERVAL_MS, gt=0)
+
+    linear_bias: float = 0.00002
+    noise_std: float = Field(default=0.0008, ge=0.0)
+    gap_noise_std: float = Field(default=0.00012, ge=0.0)
+    wick_scale: float = Field(default=0.55, ge=0.0)
+    range_multiplier: float = Field(default=1.35, ge=0.0)
+
+    base_volume: float = Field(default=1_000.0, gt=0.0)
+    volume_noise_std: float = Field(default=0.12, ge=0.0)
+    volume_return_sensitivity: float = Field(default=0.35, ge=0.0)
+    volume_range_sensitivity: float = Field(default=0.20, ge=0.0)
+    volume_volatility_sensitivity: float = Field(default=0.20, ge=0.0)
+
+    cycles: list[CycleComponent] = Field(default_factory=default_cycles)
+    regime_shift: RegimeShiftConfig = Field(default_factory=RegimeShiftConfig)
+    volatility_cluster: VolatilityClusterConfig = Field(default_factory=VolatilityClusterConfig)
+    jump_shocks: JumpShockConfig = Field(default_factory=JumpShockConfig)
+    mean_reversion: MeanReversionConfig = Field(default_factory=MeanReversionConfig)
+
+    @field_validator("linear_bias")
+    @classmethod
+    def validate_finite_linear_bias(cls, value: float) -> float:
+        if not -1.0 < value < 1.0:
+            raise ValueError("linear_bias must be between -1.0 and 1.0")
+        return value
+
+    @model_validator(mode="after")
+    def validate_component_scale(self) -> "SyntheticKlinesConfig":
+        max_cycle_amplitude = max((cycle.amplitude for cycle in self.cycles), default=0.0)
+        if max_cycle_amplitude >= 1.0:
+            raise ValueError("cycle amplitude must be smaller than 1.0")
+        return self