citymind-engine 1.0.0__py3-none-any.whl

citymind/__init__.py

@@ -0,0 +1,16 @@
+"""CITYMIND: Urban Human Systems Intelligence Framework.
+
+Independent Subsystem Modeling with AI-Enhanced Aggregation.
+Urban Health Index (UHI) composite metric for city governance.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Samir Baladi"
+__email__ = "gitdeeper@gmail.com"
+__license__ = "MIT"
+__doi__ = "10.5281/zenodo.20444647"
+
+from citymind.pipeline import CityMindAssessor
+from citymind.uhi import UrbanHealthIndex
+
+__all__ = ["CityMindAssessor", "UrbanHealthIndex"]

citymind/ai_enhancement/__init__.py

@@ -0,0 +1,17 @@
+"""AI enhancement layer for CITYMIND.
+
+AI is ONLY:
+- a predictive improvement tool
+- a calibration mechanism for system outputs
+- an adaptive weighting and anomaly detection layer
+
+AI is NOT:
+- a redefiner of the domain structure
+- a unifier of subsystems
+- a replacement of the underlying model logic
+"""
+
+from citymind.ai_enhancement.weight_optimizer import AIWeightOptimizer
+from citymind.ai_enhancement.anomaly_detector import AnomalyDetector
+
+__all__ = ["AIWeightOptimizer", "AnomalyDetector"]

citymind/ai_enhancement/anomaly_detector.py

@@ -0,0 +1,71 @@
+"""Anomaly detection for urban subsystems.
+
+AI-assisted anomaly detection for identifying stressed subsystems.
+"""
+
+import numpy as np
+from typing import Dict, List, Optional
+
+
+class AnomalyDetector:
+    """
+    Anomaly detection for urban subsystems.
+    
+    Identifies which subsystem is experiencing stress.
+    Does NOT modify subsystem models.
+    """
+    
+    def __init__(self, threshold: float = 2.0):
+        self.threshold = threshold
+        self.history: List[Dict[str, float]] = []
+    
+    def detect(self, scores: Dict[str, float]) -> Dict[str, any]:
+        """
+        Detect anomalies in subsystem scores.
+        
+        Returns:
+            Dictionary with detection results
+        """
+        self.history.append(scores)
+        
+        if len(self.history) < 3:
+            return {"anomaly_detected": False, "affected_subsystems": []}
+        
+        anomalies = []
+        
+        for subsystem, score in scores.items():
+            recent_scores = [h[subsystem] for h in self.history[-5:] if subsystem in h]
+            
+            if len(recent_scores) >= 3:
+                mean = np.mean(recent_scores)
+                std = np.std(recent_scores)
+                
+                if std > 0:
+                    z_score = abs(score - mean) / std
+                    if z_score > self.threshold:
+                        anomalies.append({
+                            "subsystem": subsystem,
+                            "score": score,
+                            "deviation": z_score,
+                            "severity": "HIGH" if z_score > 3 else "MEDIUM"
+                        })
+        
+        return {
+            "anomaly_detected": len(anomalies) > 0,
+            "affected_subsystems": anomalies,
+            "threshold": self.threshold
+        }
+    
+    def get_stressed_subsystem(self, scores: Dict[str, float]) -> Optional[str]:
+        """Identify the most stressed subsystem."""
+        result = self.detect(scores)
+        
+        if not result["anomaly_detected"]:
+            return None
+        
+        anomalies = result["affected_subsystems"]
+        if not anomalies:
+            return None
+        
+        # Return subsystem with highest deviation
+        return max(anomalies, key=lambda x: x["deviation"])["subsystem"]

citymind/ai_enhancement/weight_optimizer.py

@@ -0,0 +1,90 @@
+"""AI-enhanced weight optimization for Urban Health Index.
+
+AI strictly bounded to optimization of weights (Σ w_i = 1.0)
+Does NOT modify subsystem models or merge them.
+"""
+
+import numpy as np
+from typing import Dict, Optional
+
+
+class AIWeightOptimizer:
+    """
+    AI weight optimizer for UHI aggregation.
+    
+    Adjusts weights based on historical performance and anomaly detection.
+    Maintains constraint: Σ w_i = 1.0
+    """
+    
+    def __init__(self, learning_rate: float = 0.01):
+        self.learning_rate = learning_rate
+        self.historical_scores = []
+        self.current_weights = {
+            "transport": 0.20,
+            "population": 0.20,
+            "energy": 0.20,
+            "mobility": 0.20,
+            "infrastructure": 0.20
+        }
+    
+    def optimize_weights(self, scores: Dict[str, float]) -> Dict[str, float]:
+        """
+        Optimize subsystem weights based on recent performance.
+        
+        Higher performing subsystems receive higher weights.
+        Constraint: Σ w_i = 1.0
+        """
+        self.historical_scores.append(scores)
+        
+        # Calculate performance-based weights
+        total_performance = sum(scores.values())
+        if total_performance > 0:
+            raw_weights = {k: v / total_performance for k, v in scores.items()}
+        else:
+            raw_weights = self.current_weights.copy()
+        
+        # Apply learning rate for smooth transition
+        for k in self.current_weights:
+            self.current_weights[k] = (1 - self.learning_rate) * self.current_weights[k] + \
+                                       self.learning_rate * raw_weights[k]
+        
+        # Ensure sum to 1.0
+        total = sum(self.current_weights.values())
+        if total > 0:
+            self.current_weights = {k: v / total for k, v in self.current_weights.items()}
+        
+        return self.current_weights.copy()
+    
+    def detect_anomaly(self, scores: Dict[str, float], threshold: float = 0.3) -> bool:
+        """Detect anomalies in subsystem scores."""
+        if len(self.historical_scores) < 5:
+            return False
+        
+        recent_scores = self.historical_scores[-5:]
+        mean_scores = {}
+        std_scores = {}
+        
+        for subsystem in scores.keys():
+            values = [s[subsystem] for s in recent_scores]
+            mean_scores[subsystem] = np.mean(values)
+            std_scores[subsystem] = np.std(values)
+        
+        for subsystem in scores.keys():
+            deviation = abs(scores[subsystem] - mean_scores[subsystem])
+            if std_scores[subsystem] > 0 and deviation / std_scores[subsystem] > threshold:
+                return True
+        
+        return False
+    
+    def forecast_uhi(self, scores: Dict[str, float], horizon_hours: int = 48) -> float:
+        """Forecast future UHI using simple trend extrapolation."""
+        if len(self.historical_scores) < 10:
+            return sum(scores.values()) / len(scores)
+        
+        # Simple linear trend
+        recent_uhi = [sum(s.values()) / len(s) for s in self.historical_scores[-10:]]
+        trend = (recent_uhi[-1] - recent_uhi[0]) / len(recent_uhi)
+        
+        forecast = recent_uhi[-1] + trend * (horizon_hours / 24)
+        
+        return max(0.0, min(forecast, 1.0))

citymind/archival/__init__.py

@@ -0,0 +1,6 @@
+"""Data archival with SHA-256 integrity."""
+
+from citymind.archival.writer import ArchivalWriter
+from citymind.archival.checksum import compute_checksum
+
+__all__ = ["ArchivalWriter", "compute_checksum"]

citymind/archival/checksum.py

@@ -0,0 +1,20 @@
+"""SHA-256 checksum for data integrity."""
+
+import hashlib
+
+
+def compute_checksum(filepath: str, algorithm: str = "sha256") -> str:
+    """Compute file checksum for integrity verification."""
+    hash_func = hashlib.new(algorithm)
+    
+    with open(filepath, "rb") as f:
+        for chunk in iter(lambda: f.read(4096), b""):
+            hash_func.update(chunk)
+    
+    return hash_func.hexdigest()
+
+
+def verify_integrity(filepath: str, expected_checksum: str) -> bool:
+    """Verify file integrity against expected checksum."""
+    actual = compute_checksum(filepath)
+    return actual == expected_checksum

citymind/archival/writer.py

@@ -0,0 +1,31 @@
+"""Append-only data archival writer."""
+
+import json
+import csv
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any
+
+
+class ArchivalWriter:
+    """Append-only data archival writer."""
+    
+    def __init__(self, base_path: str = "./data/archival"):
+        self.base_path = Path(base_path)
+        self.base_path.mkdir(parents=True, exist_ok=True)
+    
+    def write_json(self, data: Dict[str, Any], filename: str):
+        """Write data to JSON file with timestamp."""
+        filepath = self.base_path / f"{filename}_{datetime.now().strftime('%Y%m%d')}.json"
+        
+        record = {
+            "timestamp": datetime.now().isoformat(),
+            "data": data
+        }
+        
+        with open(filepath, "a") as f:
+            f.write(json.dumps(record) + "\n")
+    
+    def write_uhi_record(self, uhi_result: Dict):
+        """Write UHI assessment record."""
+        self.write_json(uhi_result, "uhi_assessment")

citymind/monitoring/__init__.py

@@ -0,0 +1,5 @@
+"""Real-time monitoring dashboard for CITYMIND."""
+
+from citymind.monitoring.app import run_dashboard
+
+__all__ = ["run_dashboard"]

citymind/monitoring/app.py

@@ -0,0 +1,185 @@
+"""Streamlit application entry point for CITYMIND dashboard."""
+
+import streamlit as st
+import plotly.graph_objects as go
+import plotly.express as px
+import pandas as pd
+import numpy as np
+from datetime import datetime, timedelta
+
+from citymind.pipeline import CityMindAssessor
+
+
+def run_dashboard():
+    """Launch the CITYMIND monitoring dashboard."""
+    st.set_page_config(
+        page_title="CITYMIND Dashboard",
+        page_icon="🏙️",
+        layout="wide"
+    )
+    
+    st.title("🏙️ CITYMIND - Urban Health Intelligence Dashboard")
+    st.markdown("*Independent Subsystem Modeling with AI-Enhanced Aggregation*")
+    
+    # Initialize assessor
+    assessor = CityMindAssessor()
+    
+    # Sidebar
+    with st.sidebar:
+        st.header("⚙️ Controls")
+        refresh = st.button("🔄 Refresh Data", type="primary")
+        ai_enabled = st.checkbox("🤖 AI Enhancement", value=True)
+        
+        st.markdown("---")
+        st.markdown("### 🏗️ Urban Subsystems")
+        st.markdown("- 🚗 Transport Flow")
+        st.markdown("- 👥 Population Density")
+        st.markdown("- ⚡ Energy Consumption")
+        st.markdown("- 🚶 Mobility Behavior")
+        st.markdown("- 🏗️ Infrastructure Load")
+        
+        st.markdown("---")
+        st.markdown("### 📊 Governance Thresholds")
+        st.markdown("🟢 UHI ≥ 0.85 - Optimized")
+        st.markdown("🟠 0.70 ≤ UHI < 0.85 - Stressed")
+        st.markdown("🟠 0.55 ≤ UHI < 0.70 - Mitigation")
+        st.markdown("🔴 UHI < 0.55 - Critical")
+    
+    # Get results
+    if ai_enabled:
+        assessor.ai_enhancement = True
+    else:
+        assessor.ai_enhancement = False
+    
+    result = assessor.evaluate()
+    
+    # Main dashboard
+    col1, col2, col3 = st.columns(3)
+    
+    with col1:
+        # UHI Gauge
+        fig = go.Figure(go.Indicator(
+            mode="gauge+number",
+            value=result.uhi_result.uhi,
+            title={"text": "Urban Health Index (UHI)"},
+            gauge={
+                "axis": {"range": [0, 1], "tickwidth": 1},
+                "bar": {"color": _get_uhi_color(result.uhi_result.uhi)},
+                "steps": [
+                    {"range": [0, 0.55], "color": "#C0392B", "name": "Critical"},
+                    {"range": [0.55, 0.70], "color": "#E67E22", "name": "Mitigation"},
+                    {"range": [0.70, 0.85], "color": "#F39C12", "name": "Stressed"},
+                    {"range": [0.85, 1.0], "color": "#27AE60", "name": "Optimized"}
+                ],
+                "threshold": {
+                    "line": {"color": "black", "width": 4},
+                    "thickness": 0.75,
+                    "value": result.uhi_result.uhi
+                }
+            }
+        ))
+        fig.update_layout(height=300)
+        st.plotly_chart(fig, use_container_width=True)
+        
+        # Signal badge
+        signal_color = {
+            "🟢 OPTIMIZED_URBAN_FLOW": "green",
+            "🟠 STRESSED_SUBSYSTEM_WARNING": "orange",
+            "🟠 SYSTEMIC_MITIGATION_PHASE": "orange",
+            "🔴 CRITICAL_INFRASTRUCTURE_BREACH": "red"
+        }.get(result.uhi_result.signal.value, "gray")
+        
+        st.markdown(f"""
+        <div style="background-color: {signal_color}20; padding: 15px; border-radius: 10px; text-align: center;">
+            <h2>{result.uhi_result.signal.value}</h2>
+        </div>
+        """, unsafe_allow_html=True)
+    
+    with col2:
+        st.metric("🚗 Transport", f"{result.uhi_result.transport_score:.3f}")
+        st.metric("👥 Population", f"{result.uhi_result.population_score:.3f}")
+        st.metric("⚡ Energy", f"{result.uhi_result.energy_score:.3f}")
+    
+    with col3:
+        st.metric("🚶 Mobility", f"{result.uhi_result.mobility_score:.3f}")
+        st.metric("🏗️ Infrastructure", f"{result.uhi_result.infrastructure_score:.3f}")
+        st.metric("🤖 AI Anomaly", "Detected" if result.anomaly_detected else "None")
+    
+    # Subsystem scores chart
+    st.markdown("---")
+    st.subheader("📊 Subsystem Performance")
+    
+    scores_df = pd.DataFrame({
+        "Subsystem": ["Transport", "Population", "Energy", "Mobility", "Infrastructure"],
+        "Score": [
+            result.uhi_result.transport_score,
+            result.uhi_result.population_score,
+            result.uhi_result.energy_score,
+            result.uhi_result.mobility_score,
+            result.uhi_result.infrastructure_score
+        ],
+        "Weight": [
+            result.ai_weights.get("transport", 0.2),
+            result.ai_weights.get("population", 0.2),
+            result.ai_weights.get("energy", 0.2),
+            result.ai_weights.get("mobility", 0.2),
+            result.ai_weights.get("infrastructure", 0.2)
+        ]
+    })
+    
+    fig = px.bar(scores_df, x="Subsystem", y="Score", color="Score",
+                 color_continuous_scale="RdYlGn", range_color=[0, 1],
+                 title="Subsystem Health Scores")
+    fig.update_layout(height=400)
+    st.plotly_chart(fig, use_container_width=True)
+    
+    # AI weights
+    col1, col2 = st.columns(2)
+    
+    with col1:
+        st.subheader("🤖 AI-Optimized Weights")
+        weights_df = pd.DataFrame({
+            "Subsystem": list(result.ai_weights.keys()),
+            "Weight": list(result.ai_weights.values())
+        })
+        fig = px.pie(weights_df, values="Weight", names="Subsystem", title="Weight Distribution")
+        fig.update_layout(height=350)
+        st.plotly_chart(fig, use_container_width=True)
+    
+    with col2:
+        st.subheader("📈 Forecast")
+        if result.forecast_uhi:
+            st.metric("48h UHI Forecast", f"{result.forecast_uhi:.3f}")
+            trend = result.forecast_uhi - result.uhi_result.uhi
+            st.metric("Trend", f"{trend:+.3f}", delta=trend)
+        else:
+            st.info("AI enhancement disabled. Enable AI for forecasting.")
+        
+        # Governance action
+        st.subheader("📋 Recommended Action")
+        action = assessor.uhi.get_governance_action(result.uhi_result.signal)
+        st.info(action)
+    
+    # Footer
+    st.markdown("---")
+    st.markdown("""
+    <div style="text-align: center; color: gray; font-size: 12px;">
+        CITYMIND v1.0.0 | Urban Human Systems Intelligence | 
+        Independent Subsystem Modeling with AI-Enhanced Aggregation
+    </div>
+    """, unsafe_allow_html=True)
+
+
+def _get_uhi_color(uhi: float) -> str:
+    if uhi >= 0.85:
+        return "#27AE60"
+    elif uhi >= 0.70:
+        return "#F39C12"
+    elif uhi >= 0.55:
+        return "#E67E22"
+    else:
+        return "#C0392B"
+
+
+if __name__ == "__main__":
+    run_dashboard()

citymind/monitoring/dashboard.py

@@ -0,0 +1,45 @@
+"""CSII governance dashboard layout."""
+
+import streamlit as st
+import plotly.graph_objects as go
+
+
+def create_dashboard(uhi_value: float, signal: str, scores: dict):
+    """Create full UHI governance dashboard."""
+    col1, col2, col3 = st.columns(3)
+    
+    with col1:
+        fig = go.Figure(go.Indicator(
+            mode="gauge+number",
+            value=uhi_value,
+            title={"text": "UHI Score"},
+            gauge={
+                "axis": {"range": [0, 1]},
+                "bar": {"color": _get_color(uhi_value)},
+                "steps": [
+                    {"range": [0, 0.55], "color": "red"},
+                    {"range": [0.55, 0.70], "color": "orange"},
+                    {"range": [0.70, 0.85], "color": "yellow"},
+                    {"range": [0.85, 1.0], "color": "green"},
+                ]
+            }
+        ))
+        st.plotly_chart(fig)
+    
+    with col2:
+        st.metric("Urban Signal", signal)
+    
+    with col3:
+        for name, score in scores.items():
+            st.metric(name.capitalize(), f"{score:.3f}")
+
+
+def _get_color(uhi: float) -> str:
+    if uhi >= 0.85:
+        return "green"
+    elif uhi >= 0.70:
+        return "yellow"
+    elif uhi >= 0.55:
+        return "orange"
+    else:
+        return "red"

citymind/pipeline.py

@@ -0,0 +1,107 @@
+"""CITYMIND main assessment pipeline."""
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+import numpy as np
+
+from citymind.uhi import UrbanHealthIndex, UHIResult, UrbanSignal
+from citymind.subsystems.transport import TransportSubsystem
+from citymind.subsystems.population import PopulationSubsystem
+from citymind.subsystems.energy import EnergySubsystem
+from citymind.subsystems.mobility import MobilitySubsystem
+from citymind.subsystems.infrastructure import InfrastructureSubsystem
+from citymind.ai_enhancement.weight_optimizer import AIWeightOptimizer
+
+
+@dataclass
+class PipelineResult:
+    """Complete pipeline assessment result."""
+    uhi_result: UHIResult
+    subsystem_scores: Dict[str, float]
+    ai_weights: Dict[str, float]
+    anomaly_detected: bool
+    forecast_uhi: Optional[float]
+
+
+class CityMindAssessor:
+    """
+    CITYMIND main assessment pipeline.
+    
+    Integrates five independent urban subsystems with AI enhancement
+    strictly bounded to optimization and anomaly detection.
+    """
+    
+    def __init__(
+        self,
+        config: Optional[Dict] = None,
+        ai_enhancement: bool = True
+    ):
+        self.config = config or {}
+        self.ai_enhancement = ai_enhancement
+        
+        # Initialize five independent subsystems
+        self.transport = TransportSubsystem()
+        self.population = PopulationSubsystem()
+        self.energy = EnergySubsystem()
+        self.mobility = MobilitySubsystem()
+        self.infrastructure = InfrastructureSubsystem()
+        
+        # Initialize AI enhancement layer
+        self.ai_weight_optimizer = AIWeightOptimizer() if ai_enhancement else None
+        self.uhi = UrbanHealthIndex(ai_weight_optimization=ai_enhancement)
+    
+    def evaluate(self) -> PipelineResult:
+        """
+        Run full CITYMIND assessment pipeline.
+        
+        Each subsystem is evaluated independently. AI only enhances
+        weight optimization and anomaly detection.
+        """
+        # Evaluate each subsystem independently
+        transport_score = self.transport.compute()
+        population_score = self.population.compute()
+        energy_score = self.energy.compute()
+        mobility_score = self.mobility.compute()
+        infrastructure_score = self.infrastructure.compute()
+        
+        subsystem_scores = {
+            "transport": transport_score,
+            "population": population_score,
+            "energy": energy_score,
+            "mobility": mobility_score,
+            "infrastructure": infrastructure_score
+        }
+        
+        # AI-enhanced weight optimization
+        if self.ai_enhancement and self.ai_weight_optimizer:
+            weights = self.ai_weight_optimizer.optimize_weights(subsystem_scores)
+            anomaly_detected = self.ai_weight_optimizer.detect_anomaly(subsystem_scores)
+            forecast_uhi = self.ai_weight_optimizer.forecast_uhi(subsystem_scores)
+        else:
+            weights = None
+            anomaly_detected = False
+            forecast_uhi = None
+        
+        # Compute UHI composite index
+        uhi_result = self.uhi.compute(
+            transport_score=transport_score,
+            population_score=population_score,
+            energy_score=energy_score,
+            mobility_score=mobility_score,
+            infrastructure_score=infrastructure_score,
+            weights=weights
+        )
+        
+        return PipelineResult(
+            uhi_result=uhi_result,
+            subsystem_scores=subsystem_scores,
+            ai_weights=weights or self.uhi.DEFAULT_WEIGHTS,
+            anomaly_detected=anomaly_detected,
+            forecast_uhi=forecast_uhi
+        )
+    
+    def get_urban_signal(self) -> UrbanSignal:
+        """Get current urban governance signal."""
+        result = self.evaluate()
+        return result.uhi_result.signal

citymind/sensors/__init__.py

@@ -0,0 +1,6 @@
+"""Urban sensor integration for CITYMIND."""
+
+from citymind.sensors.traffic_sensor import TrafficSensor
+from citymind.sensors.energy_sensor import EnergySensor
+
+__all__ = ["TrafficSensor", "EnergySensor"]

citymind/sensors/energy_sensor.py

@@ -0,0 +1,24 @@
+"""Energy consumption sensor data processor."""
+
+import numpy as np
+from typing import Dict
+
+
+class EnergySensor:
+    """Energy grid sensor data processor."""
+    
+    def __init__(self):
+        pass
+    
+    def process(self, demand: float, supply: float) -> Dict:
+        """Process energy data."""
+        return {
+            "demand": demand,
+            "supply": supply,
+            "deficit_ratio": max(0, (demand - supply) / supply) if supply > 0 else 1.0,
+            "score": (supply - demand) / supply if supply > demand else 0.0
+        }
+    
+    def detect_deficit(self, demand: float, supply: float) -> bool:
+        """Detect energy deficit."""
+        return demand > supply * 0.95

citymind/sensors/traffic_sensor.py

@@ -0,0 +1,24 @@
+"""Traffic sensor data processor."""
+
+import numpy as np
+from typing import Dict, Optional
+
+
+class TrafficSensor:
+    """Traffic flow sensor data processor."""
+    
+    def __init__(self, sampling_rate: float = 60.0):
+        self.sampling_rate = sampling_rate
+    
+    def process(self, raw_data: np.ndarray) -> Dict:
+        """Process raw traffic sensor data."""
+        return {
+            "volume": float(np.mean(raw_data)),
+            "peak": float(np.max(raw_data)),
+            "congestion_ratio": float(np.mean(raw_data) / 10000),
+            "timestamp": None
+        }
+    
+    def detect_congestion(self, volume: float, capacity: float = 10000) -> bool:
+        """Detect traffic congestion."""
+        return volume / capacity > 0.85

citymind/simulation/__init__.py

@@ -0,0 +1,5 @@
+"""Validation and simulation environment for CITYMIND."""
+
+from citymind.simulation.benchmarks import run_validation_suite
+
+__all__ = ["run_validation_suite"]