contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/intelligence/sentiment_decay.py

@@ -0,0 +1,426 @@
+"""Sentiment Decay Model — signals decay over time unless reinforced.
+
+News sentiment doesn't switch off. It decays exponentially.
+New same-direction signals reinforce (reset decay clock).
+Opposite-direction signals start a new decay.
+
+This is a PLATFORM feature — generic, works for any context.
+
+Usage:
+    from contextsynapse.intelligence.sentiment_decay import SentimentDecayEngine
+
+    engine = SentimentDecayEngine()
+
+    # Add signals as they arrive
+    engine.add_signal("TCS", sentiment="positive", impact="high",
+                      timestamp="2026-08-31T22:00:00+05:30",
+                      evidence="TCS wins $2.5B deal")
+
+    engine.add_signal("TCS", sentiment="positive", impact="medium",
+                      timestamp="2026-08-31T22:30:00+05:30",
+                      evidence="TCS raises guidance")
+
+    # Query current sentiment (with decay applied)
+    score = engine.get_score("TCS")
+    # → {"score": 0.72, "direction": "positive", "signals": 2,
+    #    "last_signal": "2h ago", "decay_rate": "slow"}
+
+    # Query at a specific time
+    score = engine.get_score_at("TCS", "2026-09-01T06:00:00+05:30")
+    # → {"score": 0.45, "direction": "positive", "decayed_from": 1.0}
+"""
+from __future__ import annotations
+
+import logging
+import math
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone, timedelta
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# DEFAULT decay config — platform provides sensible defaults.
+# Domain plugins OVERRIDE these via DecayConfig.
+#
+# Formula: score × (1 / (1 + α × ln(1 + hours_since_silence)))
+# Small α = slow decay. Large α = faster decay.
+#
+# α=0.05: 1day=0.99  1week=0.92  1month=0.83 (major events)
+# α=0.15: 1day=0.96  1week=0.77  1month=0.50 (normal news)
+# α=0.35: 1day=0.91  1week=0.60  1month=0.33 (rumors)
+
+DEFAULT_DECAY_RATES = {
+    "breaking": 0.05,
+    "high": 0.10,
+    "medium": 0.15,
+    "low": 0.22,
+    "rumor": 0.35,
+}
+
+DEFAULT_SILENCE_THRESHOLD_HOURS = 6.0
+
+
+class DecayConfig:
+    """Configurable decay parameters — set by domain plugins.
+
+    Usage:
+        # Stock analysis plugin — normal market conditions
+        config = DecayConfig(
+            rates={"breaking": 0.03, "high": 0.08, "medium": 0.12, "low": 0.20, "rumor": 0.30},
+            silence_hours=8.0,
+        )
+
+        # During crisis — everything decays faster (news flow is intense)
+        crisis_config = DecayConfig(
+            rates={"breaking": 0.08, "high": 0.15, "medium": 0.25, "low": 0.35, "rumor": 0.50},
+            silence_hours=2.0,  # shorter silence window during crisis
+        )
+
+        # Pharma — FDA approvals last longer
+        pharma_config = DecayConfig(
+            rates={"breaking": 0.02, "high": 0.05, "medium": 0.10, "low": 0.15, "rumor": 0.30},
+            silence_hours=24.0,  # longer silence window for regulatory events
+        )
+
+        engine = SentimentDecayEngine(config=config)
+    """
+
+    def __init__(
+        self,
+        rates: dict = None,
+        silence_hours: float = None,
+        impact_multipliers: dict = None,
+    ):
+        self.rates = rates or dict(DEFAULT_DECAY_RATES)
+        self.silence_hours = silence_hours if silence_hours is not None else DEFAULT_SILENCE_THRESHOLD_HOURS
+        self.impact_multipliers = impact_multipliers or dict(IMPACT_MULTIPLIERS)
+
+    def get_rate(self, impact: str) -> float:
+        return self.rates.get(impact, self.rates.get("medium", 0.15))
+
+    def to_dict(self) -> dict:
+        return {"rates": self.rates, "silence_hours": self.silence_hours, "impact_multipliers": self.impact_multipliers}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "DecayConfig":
+        return cls(rates=data.get("rates"), silence_hours=data.get("silence_hours"),
+                   impact_multipliers=data.get("impact_multipliers"))
+
+
+# Active config — starts as default, overridden by plugins
+DECAY_RATES = dict(DEFAULT_DECAY_RATES)
+SILENCE_THRESHOLD_HOURS = DEFAULT_SILENCE_THRESHOLD_HOURS
+
+# Sentiment to numeric
+SENTIMENT_VALUES = {
+    "positive": 1.0,
+    "negative": -1.0,
+    "neutral": 0.0,
+    "mixed": 0.0,
+}
+
+# Impact to magnitude multiplier
+IMPACT_MULTIPLIERS = {
+    "breaking": 1.5,
+    "high": 1.0,
+    "medium": 0.7,
+    "low": 0.4,
+    "rumor": 0.2,
+}
+
+
+@dataclass
+class SentimentSignal:
+    """A single sentiment signal with timestamp."""
+    entity: str
+    sentiment: str            # positive | negative | neutral | mixed
+    impact: str = "medium"    # breaking | high | medium | low | rumor
+    value: float = 0.0        # computed: sentiment × impact multiplier
+    decay_rate: float = 0.07  # λ for exponential decay
+    timestamp: str = ""
+    evidence: str = ""
+    source: str = ""
+
+    def __post_init__(self):
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+        self.value = SENTIMENT_VALUES.get(self.sentiment, 0.0) * IMPACT_MULTIPLIERS.get(self.impact, 0.7)
+        self.decay_rate = DECAY_RATES.get(self.impact, 0.07)
+
+    @property
+    def datetime(self) -> datetime:
+        try:
+            dt = datetime.fromisoformat(self.timestamp.replace("Z", "+00:00"))
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return dt
+        except (ValueError, TypeError):
+            return datetime.now(timezone.utc)
+
+    def decayed_value(self, at: datetime, silence_start: Optional[datetime] = None) -> float:
+        """Get the signal's value at a specific time, with logarithmic decay.
+
+        Decay only starts after SILENCE_THRESHOLD_HOURS of no new signals.
+        Uses logarithmic curve: 1/(1 + α × ln(1 + hours_since_silence))
+        This is barely perceptible in hours, noticeable in days, significant in weeks.
+        """
+        if silence_start is None:
+            silence_start = self.datetime
+
+        # How long since the last signal on this entity?
+        hours_silent = max(0, (at - silence_start).total_seconds() / 3600)
+
+        # No decay during silence threshold
+        if hours_silent <= SILENCE_THRESHOLD_HOURS:
+            return self.value
+
+        # Decay only counts hours AFTER the silence threshold
+        decay_hours = hours_silent - SILENCE_THRESHOLD_HOURS
+        decay_factor = 1.0 / (1.0 + self.decay_rate * math.log(1.0 + decay_hours))
+
+        return self.value * decay_factor
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "entity": self.entity,
+            "sentiment": self.sentiment,
+            "impact": self.impact,
+            "value": round(self.value, 3),
+            "decay_rate": self.decay_rate,
+            "timestamp": self.timestamp,
+            "evidence": self.evidence,
+            "source": self.source,
+        }
+
+
+@dataclass
+class DecayedScore:
+    """Current sentiment score with decay applied."""
+    entity: str
+    score: float              # -1.5 to +1.5 (can exceed 1 with reinforcement)
+    normalized: float         # -1.0 to +1.0 (clamped)
+    direction: str            # positive | negative | neutral
+    strength: str             # strong | moderate | weak | neutral
+    active_signals: int       # signals still contributing (value > 0.01)
+    total_signals: int
+    last_signal_age_hours: float
+    dominant_decay: str       # the decay rate category of strongest signal
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "entity": self.entity,
+            "score": round(self.score, 3),
+            "normalized": round(self.normalized, 3),
+            "direction": self.direction,
+            "strength": self.strength,
+            "active_signals": self.active_signals,
+            "total_signals": self.total_signals,
+            "last_signal_age_hours": round(self.last_signal_age_hours, 1),
+            "dominant_decay": self.dominant_decay,
+        }
+
+
+class SentimentDecayEngine:
+    """Manages decaying sentiment signals for entities.
+
+    Signals accumulate and decay over time. Same-direction signals reinforce.
+    Score = sum of all decayed signal values at query time.
+
+    Decay behavior is configurable via DecayConfig — domain plugins
+    can set different rates for different industries or market conditions.
+    """
+
+    def __init__(self, config: DecayConfig = None):
+        self._signals: Dict[str, List[SentimentSignal]] = defaultdict(list)
+        self.config = config or DecayConfig()
+
+    def set_config(self, config: DecayConfig):
+        """Update decay configuration (e.g., switch to crisis mode)."""
+        self.config = config
+        # Update global rates for new signals
+        global DECAY_RATES, SILENCE_THRESHOLD_HOURS
+        DECAY_RATES = dict(config.rates)
+        SILENCE_THRESHOLD_HOURS = config.silence_hours
+
+    def add_signal(
+        self,
+        entity: str,
+        sentiment: str,
+        impact: str = "medium",
+        timestamp: str = "",
+        evidence: str = "",
+        source: str = "",
+    ) -> SentimentSignal:
+        """Add a sentiment signal for an entity."""
+        signal = SentimentSignal(
+            entity=entity,
+            sentiment=sentiment,
+            impact=impact,
+            timestamp=timestamp,
+            evidence=evidence,
+            source=source,
+        )
+        self._signals[entity].append(signal)
+        logger.debug("[DECAY] %s: %s %s (value=%.2f, λ=%.3f) — %s",
+                      entity, sentiment, impact, signal.value, signal.decay_rate, evidence[:40])
+        return signal
+
+    def get_score(self, entity: str, at: Optional[datetime] = None) -> DecayedScore:
+        """Get current sentiment score with decay applied.
+
+        Args:
+            entity: Entity name
+            at: Point in time to compute score. Default: now.
+        """
+        if at is None:
+            at = datetime.now(timezone.utc)
+        if at.tzinfo is None:
+            at = at.replace(tzinfo=timezone.utc)
+
+        signals = self._signals.get(entity, [])
+        if not signals:
+            return DecayedScore(
+                entity=entity, score=0.0, normalized=0.0,
+                direction="neutral", strength="neutral",
+                active_signals=0, total_signals=0,
+                last_signal_age_hours=0, dominant_decay="none",
+            )
+
+        # Find the latest signal time — decay only starts after silence from this point
+        latest_signal_dt = max(sig.datetime for sig in signals)
+
+        # Compute decayed values
+        total_score = 0.0
+        active = 0
+        dominant_signal = None
+        dominant_abs = 0
+
+        for sig in signals:
+            decayed = sig.decayed_value(at, silence_start=latest_signal_dt)
+            if abs(decayed) > 0.01:
+                active += 1
+                total_score += decayed
+                if abs(decayed) > dominant_abs:
+                    dominant_abs = abs(decayed)
+                    dominant_signal = sig
+
+        # Normalize to -1.0 to +1.0
+        normalized = max(-1.0, min(1.0, total_score))
+
+        # Direction
+        if normalized > 0.1:
+            direction = "positive"
+        elif normalized < -0.1:
+            direction = "negative"
+        else:
+            direction = "neutral"
+
+        # Strength
+        abs_norm = abs(normalized)
+        if abs_norm > 0.7:
+            strength = "strong"
+        elif abs_norm > 0.3:
+            strength = "moderate"
+        elif abs_norm > 0.1:
+            strength = "weak"
+        else:
+            strength = "neutral"
+
+        # Last signal age
+        latest = max(signals, key=lambda s: s.timestamp)
+        age_hours = (at - latest.datetime).total_seconds() / 3600
+
+        return DecayedScore(
+            entity=entity,
+            score=total_score,
+            normalized=normalized,
+            direction=direction,
+            strength=strength,
+            active_signals=active,
+            total_signals=len(signals),
+            last_signal_age_hours=max(0, age_hours),
+            dominant_decay=dominant_signal.impact if dominant_signal else "none",
+        )
+
+    def get_score_at(self, entity: str, timestamp: str) -> DecayedScore:
+        """Get score at a specific timestamp string."""
+        try:
+            dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return self.get_score(entity, at=dt)
+        except (ValueError, TypeError):
+            return self.get_score(entity)
+
+    def get_timeline(
+        self, entity: str, hours: int = 24, resolution_minutes: int = 30,
+    ) -> List[Dict[str, Any]]:
+        """Get sentiment score over time for charting.
+
+        Returns list of {time, score, direction, active_signals} at regular intervals.
+        """
+        now = datetime.now(timezone.utc)
+        start = now - timedelta(hours=hours)
+        step = timedelta(minutes=resolution_minutes)
+
+        timeline = []
+        current = start
+        while current <= now:
+            score = self.get_score(entity, at=current)
+            timeline.append({
+                "time": current.isoformat(),
+                "score": score.normalized,
+                "direction": score.direction,
+                "strength": score.strength,
+                "active_signals": score.active_signals,
+            })
+            current += step
+
+        return timeline
+
+    def get_all_scores(self, at: Optional[datetime] = None) -> Dict[str, DecayedScore]:
+        """Get current scores for all entities."""
+        return {entity: self.get_score(entity, at) for entity in self._signals}
+
+    def load_from_context(self, db, entity_filter: str = ""):
+        """Load signals from a context graph's entities/facts.
+
+        Reads _sentiment, _event_date, _impact from existing nodes
+        and populates the decay engine.
+        """
+        try:
+            adapter = getattr(db, 'csr_adapter', None) or db
+            for node in adapter.get_all_nodes():
+                label = getattr(node, 'label', getattr(node, 'node_type', ''))
+                if label in ('Document', 'Passage', 'ContextIntelligence', 'Chunk',
+                             'Table', 'Image', 'Indicator'):
+                    continue
+
+                props = getattr(node, 'properties', {}) or {}
+                name = props.get('name', '')
+                sentiment = props.get('_sentiment', '')
+                if not name or not sentiment:
+                    continue
+
+                if entity_filter and entity_filter.lower() not in name.lower():
+                    continue
+
+                self.add_signal(
+                    entity=name,
+                    sentiment=sentiment,
+                    impact=props.get('_impact', 'medium'),
+                    timestamp=props.get('_published_at', '') or props.get('_event_date', '') or props.get('_created_at', ''),
+                    evidence=props.get('statement', props.get('description', ''))[:100],
+                    source=props.get('_source_title', props.get('_source_name', '')),
+                )
+        except Exception as exc:
+            logger.warning("[DECAY] Failed to load from context: %s", exc)
+
+    def clear(self, entity: str = ""):
+        """Clear signals for an entity or all."""
+        if entity:
+            self._signals.pop(entity, None)
+        else:
+            self._signals.clear()

contextsynapse/intelligence/session.py

@@ -0,0 +1,277 @@
+"""Session — live workspace with attach/detach contexts.
+
+A Session is where agents and analysts work. You attach atomic contexts
+to a session, and the runtime assembler provides a unified view.
+Agents read from the session and write insights back.
+
+Usage:
+    from contextsynapse.intelligence.session import ContextSession
+
+    session = ContextSession("IT Sector Analysis", graph_registry=registry)
+    session.attach("tcs")
+    session.attach("india_economy")
+    session.attach("tcs_price")
+
+    # Get unified view
+    view = session.assemble()
+
+    # Agent writes insight back
+    session.add_insight(
+        insight="TCS outperforms when USD weakens",
+        produced_by="agent:claude",
+        confidence=0.85,
+        evidence=["TCS Q1 revenue up 4.2%", "USD/INR stable at 83.5"],
+    )
+
+    # Detach a context
+    session.detach("tcs_price")
+
+    # View updates automatically
+    view = session.assemble()
+"""
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Insight:
+    """An insight produced by an agent or the platform."""
+    id: str = ""
+    insight: str = ""
+    produced_by: str = ""       # agent:claude, platform:fusion, external:model
+    confidence: float = 0.0
+    evidence: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    created_at: str = ""
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = f"insight_{uuid.uuid4().hex[:10]}"
+        if not self.created_at:
+            self.created_at = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "insight": self.insight,
+            "produced_by": self.produced_by,
+            "confidence": self.confidence,
+            "evidence": self.evidence,
+            "tags": self.tags,
+            "created_at": self.created_at,
+        }
+
+    def to_node_props(self) -> Dict[str, Any]:
+        return {
+            "name": self.insight[:80],
+            "statement": self.insight,
+            "produced_by": self.produced_by,
+            "confidence": self.confidence,
+            "evidence": self.evidence,
+            "tags": self.tags,
+            "source_type": "insight",
+            "_created_at": self.created_at,
+        }
+
+
+class ContextSession:
+    """A live workspace with attach/detach contexts and insight write-back."""
+
+    def __init__(self, name: str, graph_registry=None, context_manager=None):
+        self.name = name
+        self.session_id = f"session_{uuid.uuid4().hex[:10]}"
+        self._registry = graph_registry
+        self._context_manager = context_manager
+        self._attached: List[str] = []
+        self._insights: List[Insight] = []
+        self._created_at = datetime.now(timezone.utc).isoformat()
+        self._assembler = None
+
+    def _get_assembler(self):
+        if not self._assembler:
+            from .runtime_context import RuntimeContextAssembler
+            self._assembler = RuntimeContextAssembler(
+                graph_registry=self._registry,
+                context_manager=self._context_manager,
+            )
+        return self._assembler
+
+    def attach(self, context_name: str) -> bool:
+        """Attach an atomic context to this session."""
+        if context_name in self._attached:
+            return False
+        self._attached.append(context_name)
+        # Invalidate assembler cache
+        self._get_assembler().invalidate_cache(context_name)
+        logger.info("[SESSION] '%s' attached context '%s' (%d total)",
+                     self.name, context_name, len(self._attached))
+        return True
+
+    def detach(self, context_name: str) -> bool:
+        """Detach an atomic context from this session."""
+        if context_name not in self._attached:
+            return False
+        self._attached.remove(context_name)
+        self._get_assembler().invalidate_cache(context_name)
+        logger.info("[SESSION] '%s' detached context '%s' (%d remaining)",
+                     self.name, context_name, len(self._attached))
+        return True
+
+    def list_attached(self) -> List[str]:
+        """List all attached context names."""
+        return list(self._attached)
+
+    def assemble(self, focus_entity: str = "", days: int = 30):
+        """Assemble a unified view from all attached contexts."""
+        if not self._attached:
+            return None
+        assembler = self._get_assembler()
+        return assembler.assemble(
+            contexts=self._attached,
+            focus_entity=focus_entity,
+            days=days,
+        )
+
+    def add_insight(
+        self,
+        insight: str,
+        produced_by: str = "",
+        confidence: float = 0.0,
+        evidence: List[str] = None,
+        tags: List[str] = None,
+        context: str = "",
+    ) -> Insight:
+        """Write an insight back to the platform.
+
+        The insight is stored:
+        1. In-memory (this session)
+        2. In the target context's graph (if context specified) — visible to
+           all agents, dashboard, and future sessions
+        3. In the session's insight graph (fallback if no context specified)
+
+        Args:
+            insight: The insight text
+            produced_by: Who produced it (agent:claude, platform:fusion, etc.)
+            confidence: 0.0-1.0
+            evidence: Supporting evidence
+            tags: Classification tags
+            context: Which atomic context to write into (e.g., "tcs")
+        """
+        ins = Insight(
+            insight=insight,
+            produced_by=produced_by,
+            confidence=confidence,
+            evidence=evidence or [],
+            tags=tags or [],
+        )
+        self._insights.append(ins)
+
+        # Write into the target context's graph (shared, visible to all)
+        if context:
+            self._write_to_context(ins, context)
+        else:
+            # Fallback: write to session-specific insights graph
+            self._write_to_session_graph(ins)
+
+        logger.info("[SESSION] '%s' insight by '%s' → %s: %s",
+                     self.name, produced_by, context or 'session', insight[:50])
+        return ins
+
+    def _write_to_context(self, ins: Insight, context_name: str):
+        """Write insight into an atomic context's graph — visible to everyone."""
+        if not self._registry:
+            return
+
+        db = self._registry.get_graph(context_name, load_if_missing=True)
+        if not db:
+            return
+
+        from ..core.graph_structures import GraphNode
+        props = ins.to_node_props()
+        props["_session"] = self.name
+        props["_session_id"] = self.session_id
+
+        db.add_node(GraphNode(
+            id=ins.id,
+            label="Insight",
+            properties=props,
+        ))
+
+    def _write_to_session_graph(self, ins: Insight):
+        """Fallback: store in session-specific graph."""
+        if not self._registry:
+            return
+
+        graph_name = f"insights_{self.name.lower().replace(' ', '_')}"
+        db = self._registry.get_graph(graph_name, load_if_missing=True)
+        if not db:
+            db = self._registry.create_graph(graph_name)
+
+        from ..core.graph_structures import GraphNode
+        db.add_node(GraphNode(
+            id=ins.id,
+            label="Insight",
+            properties=ins.to_node_props(),
+        ))
+
+    def get_insights(self, produced_by: str = "") -> List[Insight]:
+        """Get insights from this session, optionally filtered by producer."""
+        if produced_by:
+            return [i for i in self._insights if i.produced_by == produced_by]
+        return list(self._insights)
+
+    def status(self) -> Dict[str, Any]:
+        """Get session status."""
+        return {
+            "session_id": self.session_id,
+            "name": self.name,
+            "attached_contexts": self._attached,
+            "context_count": len(self._attached),
+            "insight_count": len(self._insights),
+            "created_at": self._created_at,
+        }
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            **self.status(),
+            "insights": [i.to_dict() for i in self._insights],
+        }
+
+
+class SessionManager:
+    """Manages multiple sessions."""
+
+    def __init__(self, graph_registry=None, context_manager=None):
+        self._registry = graph_registry
+        self._context_manager = context_manager
+        self._sessions: Dict[str, ContextSession] = {}
+
+    def create(self, name: str) -> ContextSession:
+        """Create a new session."""
+        session = ContextSession(
+            name=name,
+            graph_registry=self._registry,
+            context_manager=self._context_manager,
+        )
+        self._sessions[session.session_id] = session
+        logger.info("[SESSION-MGR] Created session '%s' (id=%s)", name, session.session_id)
+        return session
+
+    def get(self, session_id: str) -> Optional[ContextSession]:
+        return self._sessions.get(session_id)
+
+    def list_sessions(self) -> List[Dict[str, Any]]:
+        return [s.status() for s in self._sessions.values()]
+
+    def delete(self, session_id: str) -> bool:
+        if session_id in self._sessions:
+            del self._sessions[session_id]
+            return True
+        return False