Status: Pre-Alpha — repository foundation phase. ForecastForge does not yet implement any machine learning functionality. No data ingestion, no feature engineering, no model training, no serving, and no monitoring exist yet. This repository currently contains the project scaffolding, package structure, documentation skeleton, CI, and developer tooling on which that functionality will be built.
ForecastForge aims to be an open-source, production-grade platform for building, evaluating, and operating time-series forecasting systems at scale. Concretely, the project is working toward:
- A composable pipeline that takes raw data through ingestion, feature engineering, model training/evaluation, and serving as independently testable stages.
- A reproducible experimentation workflow, where every training run is tracked, versioned, and comparable against prior runs.
- A maintainable codebase that a distributed group of open-source contributors — not just its original authors — can safely extend.
- A deployable serving layer that exposes trained models through a documented, versioned API.
- Built-in observability, so that data drift and model degradation in production are detected rather than discovered by users.
- Reproducibility — deterministic environments, pinned tooling, and versioned experiment artifacts.
- Observability — structured logging and experiment tracking as first-class citizens, not afterthoughts.
- Maintainability — strict linting, static typing, automated testing, and a documented architectural decision record (ADR) trail so the project remains legible as it grows and as contributors change.
- Composability — a pipeline-oriented architecture where ingestion, feature engineering, modeling, and serving are independently testable and independently deployable stages.
- Openness — a governance and contribution model (see CONTRIBUTING.md and CODE_OF_CONDUCT.md) that welcomes external maintainers, not just a single team.
- Incrementalism — each phase of the project is scoped narrowly so the engineering foundation is solid before higher-risk, higher-complexity work (data ingestion, feature engineering, and modeling) begins.
The diagram below shows the intended target architecture. It describes where functionality will live once implemented — it does not describe anything that exists in the codebase today. Every stage other than the package/tooling scaffold itself is currently unimplemented.
flowchart TD
subgraph sources["Data Sources"]
A[Raw & External Data]
end
subgraph pipeline["ForecastForge Pipeline (not yet implemented)"]
B["Ingestion<br/>(forecastforge.data)"]
C["Feature Engineering<br/>(forecastforge.features)"]
D["Model Training & Evaluation<br/>(forecastforge.models,<br/>forecastforge.evaluation)"]
E["Experiment Tracking<br/>(forecastforge.tracking)"]
F["Serving / Inference API<br/>(forecastforge.serving)"]
end
subgraph ops["Operations (not yet implemented)"]
G["Monitoring<br/>(forecastforge.monitoring)"]
end
A --> B --> C --> D --> F
D <--> E
F --> G
G -. feedback .-> B
classDef planned fill:#f5f5f5,stroke:#999,stroke-dasharray: 4 3,color:#555;
class B,C,D,E,F,G planned;
Design principles guiding future implementation phases:
- Each stage will be a separately testable, independently importable
subpackage under
src/forecastforge/(see Repository Layout below), orchestrated by pipeline definitions underpipelines/. - Configuration will be environment-driven (
configs/,.env) and validated withpydantic, rather than scattered as magic constants. Seeconfigs/development.toml,configs/testing.toml, andconfigs/production.tomlfor the environment overlay structure. - Experiment and run artifacts will be tracked under
mlruns/, with raw, interim, processed, and external datasets kept in clearly separateddata/subdirectories to prevent accidental mutation of source data. - Containerization (
docker/,docker-compose.yml) will formalize the runtime environment once services exist to containerize. - Significant, hard-to-reverse architectural choices are recorded as
ADRs under
docs/adr/— see 0001-use-src-layout.md for the first example.
Full architectural documentation (currently a skeleton, to be filled in as each stage is designed) lives in docs/architecture.md.
forecastforge/
├── .github/
│ └── workflows/
│ └── ci.yml # Lint, type-check, test on push/PR
├── src/
│ └── forecastforge/ # Installable Python package (src-layout)
│ ├── config/ # Settings loading & validation (planned)
│ ├── core/ # Shared domain types & interfaces (planned)
│ ├── common/ # Cross-cutting, dependency-light helpers (planned)
│ ├── utils/ # General-purpose utility functions (planned)
│ ├── data/ # Data ingestion & access layer (planned)
│ ├── features/ # Feature engineering framework (planned)
│ ├── models/ # Model definitions & training (planned)
│ ├── evaluation/ # Model evaluation & metrics (planned)
│ ├── tracking/ # Experiment tracking integration (planned)
│ ├── serving/ # Inference API layer (planned)
│ ├── monitoring/ # Runtime & model monitoring (planned)
│ ├── pipelines/ # Pipeline orchestration (planned)
│ └── schemas/ # Shared data/config schemas (planned)
├── tests/ # Automated test suite (pytest)
├── docs/ # Project documentation
│ ├── architecture.md
│ ├── development.md
│ ├── data-pipeline.md
│ ├── feature-engineering.md
│ ├── model-comparison.md
│ ├── serving.md
│ ├── monitoring.md
│ └── adr/ # Architectural Decision Records
├── pipelines/ # Pipeline/orchestration definitions (future)
├── notebooks/ # Exploratory notebooks (not for production code)
├── docker/ # Container build contexts (placeholders)
│ ├── app/Dockerfile
│ ├── mlflow/Dockerfile
│ └── monitor/Dockerfile
├── scripts/ # Developer & operational scripts
│ ├── bootstrap.sh # Local setup (POSIX)
│ └── bootstrap.ps1 # Local setup (Windows/PowerShell)
├── configs/ # Application & logging configuration
│ ├── settings.toml # Base settings
│ ├── development.toml # Development overrides
│ ├── testing.toml # Testing overrides
│ ├── production.toml # Production overrides
│ └── logging.yaml # Logging configuration
├── data/ # Local data workspace (git-ignored contents)
│ ├── raw/ # Immutable, original data
│ ├── interim/ # Intermediate, partially processed data
│ ├── processed/ # Final, model-ready datasets
│ └── external/ # Data sourced from third parties
├── models/ # Serialized model artifacts (git-ignored)
├── mlruns/ # Experiment tracking store (git-ignored)
├── pyproject.toml # Packaging, dependency, and tool configuration
├── Makefile # Common developer workflows
├── docker-compose.yml # Local service orchestration (placeholder)
├── .pre-commit-config.yaml # Pre-commit hook configuration
├── CONTRIBUTING.md # Contribution guide
├── CODE_OF_CONDUCT.md # Contributor Covenant v2.1
├── SECURITY.md # Vulnerability reporting process
├── CHANGELOG.md # Keep a Changelog-formatted history
└── VERSION # Current project version
Every subpackage under src/forecastforge/ currently contains only an
__init__.py with a module docstring describing its future
responsibility — no functionality is implemented in any of them yet.
This repository is in the foundation phase. What exists today:
- A
src-layout Python package (forecastforge) with its full planned subpackage structure stubbed out, and no modeling, feature engineering, or ingestion logic implemented in any of them. - A modern
pyproject.toml-based build (Hatchling) targeting Python 3.12+. - Linting and formatting via Ruff.
- Static type checking via MyPy in strict mode.
- A test harness via pytest with coverage reporting configured.
- Pre-commit hooks enforcing formatting, linting, and basic file hygiene.
- Continuous integration (
.github/workflows/ci.yml) running Ruff, MyPy, and pytest on every push and pull request. - A documentation skeleton under
docs/and a first ADR recording why the project usessrc-layout. - Community health files:
CONTRIBUTING.md,CODE_OF_CONDUCT.md,SECURITY.md,CHANGELOG.md. - Environment-specific configuration overlays (
configs/development.toml,configs/testing.toml,configs/production.toml) layered overconfigs/settings.toml. - Placeholder Docker build contexts (
docker/app,docker/mlflow,docker/monitor) reserving the future service layout. - Bootstrap scripts (
scripts/bootstrap.sh,scripts/bootstrap.ps1) automating local environment setup.
What does not exist yet (by design, for this phase):
- Data ingestion connectors or schemas.
- Feature engineering logic.
- Model training, evaluation, or inference code.
- A serving/API layer.
- Monitoring or alerting logic.
- Built Docker images (Dockerfiles are placeholders only).
# Clone the repository
git clone https://github.com/forecastforge/forecastforge.git
cd forecastforge
# One-shot environment setup: creates a venv, installs the package and
# dev dependencies, installs the pre-commit hook, and copies .env.example
# to .env if it doesn't already exist.
./scripts/bootstrap.sh # macOS / Linux
# or
./scripts/bootstrap.ps1 # Windows / PowerShell
# Activate the environment in new shells
source .venv/bin/activate # macOS / Linux
# or
. .venv/Scripts/Activate.ps1 # Windows / PowerShellDay-to-day commands, all defined in the Makefile:
| Command | Purpose |
|---|---|
make install |
Editable-install the package with dev + docs dependencies, install pre-commit hook |
make lint |
Run Ruff lint checks |
make format |
Auto-format code with Ruff |
make typecheck |
Run MyPy in strict mode |
make test |
Run the pytest suite with coverage |
make run-precommit |
Run all pre-commit hooks against the whole repo |
make clean |
Remove caches, build artifacts, and coverage output |
Before opening a pull request, run:
make lint typecheck test run-precommitSee CONTRIBUTING.md for the full contribution workflow, including branching strategy, commit conventions, and the pull request checklist, and docs/development.md for the (currently skeletal) extended development guide.
| Phase | Scope | Status |
|---|---|---|
| 0 | Repository foundation, package structure, tooling, CI, OSS hygiene | ✅ In progress (this phase) |
| 1 | Configuration & logging framework implementation | ⏳ Planned |
| 2 | Data ingestion interfaces and connectors | ⏳ Planned |
| 3 | Feature engineering framework | ⏳ Planned |
| 4 | Model training & evaluation framework | ⏳ Planned |
| 5 | Experiment tracking & model registry integration | ⏳ Planned |
| 6 | Serving layer / inference API | ⏳ Planned |
| 7 | Containerized deployment & orchestration | ⏳ Planned |
| 8 | Observability, alerting, and SLOs | ⏳ Planned |
This roadmap will evolve; significant architectural choices will be
captured as ADRs under docs/adr/ as they are made.
No phase beyond Phase 0 has been started.
ForecastForge is intended to be maintained by multiple contributors. Please read CONTRIBUTING.md for the branching strategy, commit message convention (Conventional Commits), pull request checklist, and coding standards, and CODE_OF_CONDUCT.md (Contributor Covenant v2.1) for community expectations. Security issues should be reported per SECURITY.md rather than filed as public issues.
ForecastForge is licensed under the MIT License.