Merge pull request #53 from dfeen87/jules-add-scoring-engine-11354591928326284294

Add Weighted Multi-Constraint Scoring Engine

Author: dfeen87

CITATION.cff

@@ -29,7 +29,7 @@ keywords:
   - risk mitigation
   - transparent reasoning
 
-version: "2.5.0"
+version: "3.0.0"
 license: non-commercial
 repository-code: https://github.com/dfeen87/CuraFrame
 url: https://github.com/dfeen87/CuraFrame
@@ -40,6 +40,6 @@ preferred-citation:
     - given-names: Don Michael
       family-names: Feeney Jr.
   title: CuraFrame
-  version: "2.5.0"
+  version: "3.0.0"
   year: 2026
   url: https://github.com/dfeen87/CuraFrame

README.md

@@ -799,7 +799,7 @@ If CuraFrame is used in research, publications, or technical reports, please cit
   title = {CuraFrame: Constraint-Driven Therapeutic Design Reasoning},
   author = {Feeney, Don Michael},
   year = {2026},
-  version = {2.5.0},
+  version = {3.0.0},
   url = {https://github.com/dfeen87/CuraFrame},
   license = {Non-Commercial}
 }

constraint_core/MultiBundleEvaluator.hpp

@@ -4,6 +4,8 @@
 #include "Candidate.hpp"
 #include "EvaluationReport.hpp"
 #include "ConstraintRegistry.hpp"
+#include "../scoring/ScoringPipeline.hpp"
+#include "../scoring/WeightProfile.hpp"
 #include <sstream>
 
 // Unified Evaluation Layer
@@ -46,6 +48,18 @@ class MultiBundleEvaluator {
         report.combined_narrative = combined_narrative.str();
         return report;
     }
+
+    // Pass evaluation results to the scoring engine using the default profile
+    ScoringReport score(const EvaluationReport& report) const {
+        ScoringPipeline pipeline(std::make_shared<DefaultResearchProfile>());
+        return pipeline.execute(report);
+    }
+
+    // Pass evaluation results to the scoring engine using a specific profile
+    ScoringReport score_with_profile(const EvaluationReport& report, std::shared_ptr<WeightProfile> profile) const {
+        ScoringPipeline pipeline(profile);
+        return pipeline.execute(report);
+    }
 };
 
 #endif // CURAFRAME_MULTI_BUNDLE_EVALUATOR_HPP

cura_frame/__init__.py

@@ -11,7 +11,7 @@
 See docs/PHILOSOPHY.md and docs/ETHICAL_USE.md for guiding principles.
 """
 
-__version__ = "2.5.0"
+__version__ = "3.0.0"
 
 from .core import (
     CuraFrame,

docs/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to the C++ parallel evaluation universe will be documented in this file.
 
+## [3.0.0] - Weighted Scoring Engine
+
+### Added
+- **Weighted Multi-Constraint Scoring Engine**: Introduced a unified scoring engine that computes a Composite Stability Score (0-100) from constraint bundle outputs.
+- **Scoring Pipeline & Reports**: Added `ScoringPipeline` and `ScoringReport` to aggregate penalties, bonuses, falsification impacts, and generate narrative summaries.
+- **Weight Profiles**: Introduced configurable `WeightProfile` abstractions, including `DefaultResearchProfile` and `HighSafetyProfile`, for dynamic domain and signal weighting.
+- **Integration**: Updated `MultiBundleEvaluator` to seamlessly pass evaluation reports into the scoring engine via `score` and `score_with_profile` methods without altering underlying constraint logic.
+- **Documentation**: Added `scoring_engine.md` and `weight_profiles.md` detailing the scoring architecture and weight profile designs.
+
+### Changed
+- Bumped project version to 3.0.0.
+
 ## [2.5.0] - Constraint-Bundle Universe
 
 ### Added

docs/scoring_engine.md

@@ -0,0 +1,36 @@
+# CuraFrame Weighted Multi-Constraint Scoring Engine (v3.0.0)
+
+## Overview
+
+The Weighted Multi-Constraint Scoring Engine is a subsystem added in v3.0.0 that sits above the existing constraint bundles. It takes the output (signals, falsifications, and narrative summaries) from all bundles and distills them into a unified, modular, and configurable **Composite Stability Score**.
+
+This system does not alter or modify the underlying deterministic bundle evaluation logic. Instead, it aggregates results and applies domain-specific weighting, penalties, and bonuses to produce a nuanced report of therapeutic candidate viability.
+
+## Architecture
+
+1. **WeightProfile (`scoring/WeightProfile.hpp`)**: An interface (with default implementations) that defines the weights, penalties, multipliers, and scaling factors for different domains and specific signals.
+2. **WeightedScoringEngine (`scoring/WeightedScoringEngine.hpp/.cpp`)**: The core engine that ingests the outputs from all bundles (`EvaluationReport`), applies the provided `WeightProfile`, computes the final score, and generates a structured summary.
+3. **ScoringPipeline (`scoring/ScoringPipeline.hpp/.cpp`)**: A wrapper pipeline managing the execution of the scoring engine with a specified weight profile.
+4. **ScoringReport (`scoring/ScoringReport.hpp`)**: The structured output structure, detailing penalty breakdowns, bonus breakdowns, falsification impacts, and a narrative summary.
+
+## Composite Stability Score
+
+The Composite Stability Score is a numerical representation of candidate stability scaled between 0 and 100:
+- **100**: Perfect theoretical safety baseline, zero constraint violations or penalized signals.
+- **< 100**: Progressive deterioration of the score based on domain-weighted penalties, amplified by specific severity levels, or falsification flags.
+- **Falsification impact**: Candidate falsification triggers massive penalty deductions (configurable per weight profile), severely lowering the final score.
+
+Higher scores indicate more stable candidates, and lower scores indicate more risk-burdened candidates.
+
+## Example Report Execution
+
+```cpp
+MultiBundleEvaluator evaluator;
+EvaluationReport eval_report = evaluator.evaluate(candidate);
+
+// Generate standard composite scoring
+ScoringReport score = evaluator.score(eval_report);
+
+// Generate with an aggressive safety profile
+ScoringReport safety_score = evaluator.score_with_profile(eval_report, std::make_shared<HighSafetyProfile>());
+```

docs/weight_profiles.md

@@ -0,0 +1,41 @@
+# Weight Profiles (v3.0.0)
+
+## Design and Intent
+
+Weight Profiles allow the CuraFrame Scoring Engine to view candidates under different lenses of scrutiny. Instead of hardcoded aggregation metrics, `WeightProfile` provides a configurable approach to amplifying certain domains (e.g., Cardiac or CNS safety) based on the context of the evaluation.
+
+## Built-in Profiles
+
+### 1. `DefaultResearchProfile`
+- A balanced, general-purpose profile.
+- Mildly emphasizes safety parameters but treats most domains with an equal base weight.
+
+### 2. `HighSafetyProfile`
+- Designed for late-stage conservative screening.
+- Applies heavy multipliers to `Safety`, `Cardiac`, `CNS`, and `SystemicExposure` domains.
+- Heavily amplifies specific toxicity signals.
+- Punishes falsification flags almost entirely zeroing out candidate viability.
+
+## Extending Weight Profiles
+
+To create a new weight profile, inherit from the `WeightProfile` abstract base class and implement the necessary configuration hooks.
+
+```cpp
+class PediatricSafetyProfile : public WeightProfile {
+public:
+    std::string name() const override { return "PediatricSafetyProfile"; }
+
+    double bundle_weight(const std::string& bundle_name) const override {
+        // Significantly amplify systemic exposure and safety for pediatric focus
+        if (bundle_name == "SystemicExposure" || bundle_name == "Safety") return 3.0;
+        return 1.0;
+    }
+
+    double signal_weight(const std::string& bundle_name, const std::string& signal_name) const override {
+        if (signal_name.find("clearance") != std::string::npos) return 2.0;
+        return 1.0;
+    }
+
+    double falsification_penalty() const override { return 100.0; }
+};
+```

scoring/ScoringPipeline.cpp

@@ -0,0 +1,10 @@
+#include "ScoringPipeline.hpp"
+
+ScoringPipeline::ScoringPipeline(std::shared_ptr<WeightProfile> profile)
+    : engine_(std::move(profile)) {}
+
+ScoringReport ScoringPipeline::execute(const EvaluationReport& eval_report) const {
+    // In a more complex pipeline, normalization or pre-processing could happen here
+    // Currently, the WeightedScoringEngine handles everything deterministically
+    return engine_.score(eval_report);
+}

scoring/ScoringPipeline.hpp

@@ -0,0 +1,20 @@
+#ifndef CURAFRAME_SCORING_PIPELINE_HPP
+#define CURAFRAME_SCORING_PIPELINE_HPP
+
+#include "../constraint_core/EvaluationReport.hpp"
+#include "ScoringReport.hpp"
+#include "WeightedScoringEngine.hpp"
+#include "WeightProfile.hpp"
+#include <memory>
+
+class ScoringPipeline {
+public:
+    ScoringPipeline(std::shared_ptr<WeightProfile> profile);
+
+    ScoringReport execute(const EvaluationReport& eval_report) const;
+
+private:
+    WeightedScoringEngine engine_;
+};
+
+#endif // CURAFRAME_SCORING_PIPELINE_HPP

scoring/ScoringReport.hpp

@@ -0,0 +1,29 @@
+#ifndef CURAFRAME_SCORING_REPORT_HPP
+#define CURAFRAME_SCORING_REPORT_HPP
+
+#include <string>
+#include <vector>
+#include <map>
+
+struct ScoringReport {
+    double composite_score = 0.0; // 0 to 100
+
+    // Per-bundle weighted contributions
+    std::map<std::string, double> bundle_contributions;
+
+    // Breakdowns
+    std::map<std::string, double> penalty_breakdown;
+    std::map<std::string, double> bonus_breakdown;
+
+    // Falsification
+    std::vector<std::string> falsification_flags;
+    double falsification_impact = 0.0;
+
+    // Metadata
+    std::string weight_profile_name;
+
+    // Narrative summary
+    std::string narrative_summary;
+};
+
+#endif // CURAFRAME_SCORING_REPORT_HPP