views_pipeline_core 2.3.0

No project description provided

        

A modular Python framework for end‑to‑end conflict forecasting: data ingestion, transformation, drift monitoring, model and ensemble management, evaluation, reconciliation, mapping, reporting, packaging, and artifact governance.

Acknowledgements

---

[!CAUTION]

🚨 ATTENTION: MANDATORY EXPLICIT CONFIGURATION (Tier 3)

As of February 2026, the pipeline enforces Explicit Intent Declaration. Legacy keys (targets, metrics) are deprecated and will trigger large warning banners.

1. Targets are MANDATORY: You must declare at least one target or the pipeline will hard-stop. 2. Be Explicit: Use task-specific prefixes (regression_ or classification_). 3. Split Metrics: Clearly separate Point metrics from Sample-based (Uncertainty) metrics.

Category	Tier 3: Best Practice (Explicit)	Legacy (Deprecated)
Targets	regression_targets, classification_targets	targets
Metrics	regression_point_metrics regression_sample_metrics classification_point_metrics classification_sample_metrics	regression_metrics classification_metrics metrics

Misspelled or unrecognized keys (e.g., regression_target without the 's') will trigger a hard stop with helpful hints.

---

Table of Contents

1. Conceptual Overview
2. High‑Level Architecture
3. Core Pipeline Stages
4. Managers (Orchestration Layer)
5. Modules (Functional Layer)
6. Data Layer & Querysets
7. Evaluation & Metrics
8. Reconciliation (Hierarchical Consistency)
9. Reporting & Mapping
10. CLI & Argument System
11. Configuration & Partitioning
12. Package Management
13. Logging & Monitoring
14. Development Workflow
15. Quick Start
16. FAQ

---

1. Conceptual Overview

The pipeline transforms raw geo‑temporal data into validated, reconciled, and documented forecasts. Key features include:

• Deterministic data preparation (queryset + transformation replay)
• Strict naming & artifact conventions
• Partition-aware evaluation (calibration/validation/forecasting)
• Multi-model ensembling & hierarchical reconciliation
• Automated HTML reporting and spatial visualization
• Reproducible configuration merging and logging
• Optional integration with Weights & Biases (WandB) and prediction store

---

2. High‑Level Architecture

         ┌────────────────────────────────────────┐
         │            ConfigurationManager        │
         │  (deployment + hyperparameters + meta) │
         └───────────────┬────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────┐
│                 ViewsDataLoader                  │
│  Queryset → Raw Fetch → Drift Check → Update     │
│  → Transformation Replay → Partition Slice       │
└───────────────┬──────────────────────────────────┘
                │  DataFrame (month_id, entity_id)
                ▼
      ┌─────────────────────────────────────────┐
      │   ForecastingModelManager (thin façade)  │
      │   Routes to independently testable stages│
      │                                         │
      │   ┌─────────────┐  ┌──────────────────┐ │
      │   │TrainingStage│  │ EvaluationStage  │ │
      │   └─────────────┘  └──────────────────┘ │
      │   ┌───────────────┐ ┌────────────────┐  │
      │   │ForecastingStage│ │ReportingStage │  │
      │   └───────────────┘ └────────────────┘  │
      │   ┌───────────────────────┐              │
      │   │  PredictionIOManager  │              │
      │   └───────────────────────┘              │
      └────────────┬────────────────────────────┘
                   │ Predictions
                   ▼
         ┌────────────────────────┐
         │ ReconciliationModule   │
         │ (Country ↔ Priogrid)   │
         └────────────┬───────────┘
                      │ Reconciled Predictions
                      ▼
         ┌───────────────────────────┐
         │ Reporting & Mapping       │
         │ HTML, Tables, Choropleths │
         └───────────────────────────┘

Architecture note (April 2026): ForecastingModelManager has been decomposed from a 3049-LOC monolith into a ~1960-LOC thin façade that delegates to 5 independently testable stage classes. Each stage receives a frozen context object (immutable dataclass) rather than reaching into the manager's internals. ModelPathManager has been relocated from managers/ to data/ to fix dependency inversion. All existing import paths continue to work via re-export shims. See ADR-045 for the full design rationale.

---

3. Core Pipeline Stages

Stage	Output	Key Component
Data Fetch	Partitioned feature/target frame	ViewsDataLoader
Train	Artifact (model file)	TrainingStage (via ForecastingModelManager / EnsembleManager)
Evaluate	Metrics + eval predictions	EvaluationStage (via ForecastingModelManager)
Forecast	Future horizon predictions	ForecastingStage (via ForecastingModelManager)
Reconcile	Grid ↔ country consistency	ReconciliationModule
Report	HTML summaries	ReportingStage (via ForecastingModelManager)
Package	Poetry-compliant project	PackageManager

---

4. Managers (Orchestration Layer)

Manager / Stage	Purpose
ModelPathManager	Path + artifact resolution for a model (canonical location: data/)
ModelManager	Abstract training/evaluation/forecast flow control
ForecastingModelManager	Thin façade — routes to pipeline stages below
EvaluationStage	Metrics orchestration (DF + PF paths, step mappings, evaluator integration)
ReportingStage	Forecast + evaluation HTML report generation
ForecastingStage	Post-processing, validation, and persistence of forecast predictions
TrainingStage	Training log creation and WandB alerts
PredictionIOManager	Save/load predictions, evaluations, and evaluation tables
EnsemblePathManager	Paths for multi-model ensemble
EnsembleManager	Aggregation + optional reconciliation
ExtractorPathManager	External raw data ingestion paths
ExtractorManager	Download → preprocess → save for external datasets
PostprocessorPathManager	Downstream transformation stage paths
PostprocessorManager	Read → transform → validate → save
PackageManager	Create/validate Poetry packages
ConfigurationManager	Merge + validate layered configuration

Each stage receives an immutable frozen context object and is independently unit-testable. See ADR-045 for architecture details.

---

5. Modules (Functional Layer)

Module	Role
dataloaders	Partition-aware data retrieval + drift detection + incremental update
transformations	Dataset transformation undo/management
reconciliation	Hierarchical grid ↔ country alignment
reports	Tailwind-styled HTML evaluation/forecast report generation
mapping	Static + interactive choropleth maps (matplotlib / Plotly)
logging	Central logging configuration injection
statistics	Forecast reconciliation math (proportional scaling)
wandb	Alerts, artifact logging, run lifecycle
model validation	Structural & logical integrity checks (sniffer pattern, ADR-041)
ensemble validation	Structural & logical integrity checks

---

5.1 Intermediate Modules

Module	Role
cli	CLI parsing and validation
dataset	Spatio-temporal dataset handler with country and priogrid level support

---

6. Data Layer & Querysets

• Querysets define feature/target extraction logic + transformation chains.
• Incremental updates replace raw slices (GED / ACLED) and replay transformations (UpdateViewser).
• MultiIndex structure: (month_id, entity_id) for time-spatial operations.
• Data types normalized (float64 for numeric integrity).
• Partitions defined via month ranges (train/test or forecast horizon).

---

7. Evaluation & Metrics

Evaluation produces:

• Step-wise metrics (per forecast horizon)
• Month-wise metrics (temporal slices)
• Time-series metrics (sequence performance trajectory)

Conflict type auto-inferred from target tokens (sb / ns / os). Files named per ADR conventions (artifact/output naming).

---

8. Reconciliation (Hierarchical Consistency)

Ensures priogrid sums align with authoritative country totals while preserving relative spatial pattern and zero inflation. Parallelizable across countries × time × targets. Integrated into ensembles or model forecast postprocessing.

---

9. Reporting & Mapping

Component	Feature
ReportModule	Headings, paragraphs, Markdown, tables, images, grids
MappingModule	Country & priogrid choropleths (static + interactive animation)
Templates	Forecast + evaluation report skeletons
CSS	Tailwind subset embedded for portability

Reports embed:

• Metrics tables
• Key–value configuration summaries
• Spatial animations (Plotly)
• Artifact provenance (timestamps, versions)

---

10. CLI & Argument System

Dataclass-driven (ForecastingModelArgs):

• Flags: --train, --evaluate, --forecast, --report, --sweep, --prediction_store, --monthly
• Validation prevents illegal combinations (e.g., evaluate with forecasting run type).
• Monthly shortcut auto-configures production cycle.

---

11. Configuration & Partitioning

ConfigurationManager merges:

1. Deployment
2. Hyperparameters
3. Meta
4. Partition dictionary
5. Runtime overrides (highest priority)

Forecast partitions dynamically adjusted by override_timestep. Validation enforces structural integrity and target specification.

---

12. Package Management

PackageManager:

• Validates naming (organization-prefix-*)
• Creates Poetry skeleton (Python version constraint)
• Adds dependencies (including views-pipeline-core)
• Fetches latest release (tags or GitHub API)
• Runs poetry check

---

13. Logging & Monitoring

• YAML-driven configuration (handlers, levels, formatters).
• Dedicated model/ensemble logging directories.
• Standard separation: main log, error log.
• WandB alerts for stage transitions, failures, reconciliation completeness.

---

14. Development Workflow

Task	Command
Run model	./run.sh --run_type calibration --train --evaluate --report --saved
Run ensemble	./run.sh --ensemble hybrid_lynx --forecast --report
Update raw data	Use --update_viewser
Generate report only	Use --evaluate --report or --forecast --report

Refer to documentation/development_guidelines.md for coding standards and docstring_guidelines.md for formatting.

---

15. Quick Start

1. Run build_model_scaffold.py or build_ensemble_scaffold.py found in the views-models repository.

2. Update config_deployment.py, config_hyperparameters.py, config_queryset.py, config_meta.py.

3. Run calibration:

   python main.py --run_type calibration --train --evaluate --report
   

4. Run forecasting:

   python main.py --run_type forecasting --train --forecast --report
   

5. View artifacts: models/<name>/artifacts/

---

16. FAQ

Question	Answer
Do I need WandB?	Optional; disable notifications to run offline.
Can I reconcile single-model forecasts?	Yes—apply ReconciliationModule manually after forecast stage.
How do I add a new transformation?	Register callable in transformation mapping and ensure replay compatibility.
Are forecasts stored transformed or raw?	Temporarily reversed to raw scale before saving (pending ADR finalization).
Can I aggregate probabilistic outputs?	Current ensemble aggregation expects scalar or single-element lists.

---