contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/realtime/collaboration.py

@@ -0,0 +1,147 @@
+"""
+Real-Time Collaboration Hub — WebSocket-based live graph editing.
+
+Manages connected clients (humans + agents), broadcasts graph changes,
+handles conflict resolution.
+
+Usage:
+    from contextsynapse.realtime.collaboration import CollaborationHub
+    hub = CollaborationHub()
+    await hub.connect(websocket, session_id, user_id)
+    await hub.broadcast_change(session_id, change_event)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from collections import defaultdict
+from typing import Any, Dict, List, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+
+class CollaborationHub:
+    """Manages real-time collaboration sessions."""
+
+    def __init__(self):
+        # session_id → set of (websocket, user_id) tuples
+        self._connections: Dict[str, Set] = defaultdict(set)
+        # session_id → list of recent changes (ring buffer)
+        self._recent_changes: Dict[str, List[Dict]] = defaultdict(list)
+        # user_id → {cursor_position, active_node, last_seen}
+        self._cursors: Dict[str, Dict[str, Any]] = {}
+        self._max_history = 50
+
+    async def connect(self, websocket, session_id: str, user_id: str, user_name: str = ""):
+        """Register a WebSocket client for a session."""
+        self._connections[session_id].add((websocket, user_id))
+        self._cursors[user_id] = {
+            "session_id": session_id,
+            "user_name": user_name or user_id[:12],
+            "active_node": None,
+            "last_seen": time.time(),
+        }
+
+        # Notify others
+        await self._broadcast(session_id, {
+            "type": "user_joined",
+            "user_id": user_id,
+            "user_name": user_name or user_id[:12],
+            "users_online": self._get_online_users(session_id),
+        }, exclude=user_id)
+
+        # Send recent history to the new joiner
+        try:
+            history = self._recent_changes.get(session_id, [])[-20:]
+            await websocket.send_json({
+                "type": "sync",
+                "changes": history,
+                "users_online": self._get_online_users(session_id),
+            })
+        except Exception:
+            pass
+
+        logger.info("[COLLAB] %s joined session %s (%d online)",
+                     user_name or user_id[:12], session_id[:12],
+                     len(self._connections[session_id]))
+
+    async def disconnect(self, websocket, session_id: str, user_id: str):
+        """Remove a WebSocket client."""
+        self._connections[session_id].discard((websocket, user_id))
+        self._cursors.pop(user_id, None)
+
+        await self._broadcast(session_id, {
+            "type": "user_left",
+            "user_id": user_id,
+            "users_online": self._get_online_users(session_id),
+        })
+
+    async def broadcast_change(self, session_id: str, change: Dict[str, Any]):
+        """Broadcast a graph change to all connected clients."""
+        change["timestamp"] = time.time()
+        self._recent_changes[session_id].append(change)
+        if len(self._recent_changes[session_id]) > self._max_history:
+            self._recent_changes[session_id] = self._recent_changes[session_id][-self._max_history:]
+
+        await self._broadcast(session_id, change)
+
+    async def update_cursor(self, session_id: str, user_id: str, active_node: str = None):
+        """Update a user's cursor position (which node they're looking at)."""
+        if user_id in self._cursors:
+            self._cursors[user_id]["active_node"] = active_node
+            self._cursors[user_id]["last_seen"] = time.time()
+
+        await self._broadcast(session_id, {
+            "type": "cursor_update",
+            "user_id": user_id,
+            "active_node": active_node,
+        }, exclude=user_id)
+
+    def _get_online_users(self, session_id: str) -> List[Dict[str, Any]]:
+        """Get list of online users in a session."""
+        users = []
+        for _, uid in self._connections.get(session_id, set()):
+            cursor = self._cursors.get(uid, {})
+            users.append({
+                "user_id": uid,
+                "user_name": cursor.get("user_name", uid[:12]),
+                "active_node": cursor.get("active_node"),
+            })
+        return users
+
+    async def _broadcast(self, session_id: str, message: Dict[str, Any], exclude: str = None):
+        """Send message to all connected clients in a session."""
+        dead = set()
+        for ws, uid in self._connections.get(session_id, set()):
+            if exclude and uid == exclude:
+                continue
+            try:
+                await ws.send_json(message)
+            except Exception:
+                dead.add((ws, uid))
+
+        # Clean dead connections
+        for d in dead:
+            self._connections[session_id].discard(d)
+
+    def get_session_info(self, session_id: str) -> Dict[str, Any]:
+        """Get info about a collaboration session."""
+        return {
+            "session_id": session_id,
+            "users_online": len(self._connections.get(session_id, set())),
+            "recent_changes": len(self._recent_changes.get(session_id, [])),
+            "users": self._get_online_users(session_id),
+        }
+
+
+# Singleton
+_hub = None
+
+def get_collaboration_hub() -> CollaborationHub:
+    global _hub
+    if _hub is None:
+        _hub = CollaborationHub()
+    return _hub

contextsynapse/rules/__init__.py

@@ -0,0 +1,10 @@
+"""Unified Rules Engine for financial compliance and portfolio management."""
+from .models import RuleAction, RuleDefinition, RuleResult, RuleSeverity, RuleTrigger
+from .loader import RuleLoader
+from .engine import UnifiedRulesEngine
+
+__all__ = [
+    "RuleAction", "RuleDefinition", "RuleResult", "RuleSeverity", "RuleTrigger",
+    "RuleLoader",
+    "UnifiedRulesEngine",
+]

contextsynapse/rules/engine.py

@@ -0,0 +1,116 @@
+"""UnifiedRulesEngine — orchestrates all rule evaluators.
+
+Routes rules to the correct evaluator (aggregate, temporal, pre_action)
+based on rule_type, filters by trigger, and returns sorted results.
+
+Usage:
+    engine = UnifiedRulesEngine.from_yaml("config/schemas/pms_rules.yaml")
+    results = engine.evaluate(RuleTrigger.ON_TRADE, db, action_context={"stock": "TCS"})
+    for r in results:
+        if r.action == RuleAction.BLOCK:
+            raise ComplianceError(r.message)
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .loader import RuleLoader
+from .models import RuleAction, RuleDefinition, RuleResult, RuleSeverity, RuleTrigger
+from .evaluators.aggregate import AggregateEvaluator
+from .evaluators.temporal import TemporalEvaluator
+from .evaluators.pre_action import PreActionEvaluator
+
+logger = logging.getLogger(__name__)
+
+_SEVERITY_ORDER = {
+    RuleSeverity.CRITICAL: 0,
+    RuleSeverity.HIGH: 1,
+    RuleSeverity.MEDIUM: 2,
+    RuleSeverity.LOW: 3,
+    RuleSeverity.INFO: 4,
+}
+
+
+class UnifiedRulesEngine:
+    """Orchestrates all rule evaluators — aggregate, temporal, pre-action."""
+
+    def __init__(self, rules: List[RuleDefinition] = None):
+        self._rules: List[RuleDefinition] = rules or []
+        self._aggregate = AggregateEvaluator()
+        self._temporal = TemporalEvaluator()
+        self._pre_action = PreActionEvaluator()
+
+    @property
+    def rules(self) -> List[RuleDefinition]:
+        return list(self._rules)
+
+    @classmethod
+    def from_yaml(cls, path: str) -> UnifiedRulesEngine:
+        """Create engine from a rules YAML file."""
+        loader = RuleLoader()
+        rules = loader.load_from_yaml(path)
+        return cls(rules=rules)
+
+    def get_rules_for_trigger(
+        self, trigger: RuleTrigger
+    ) -> List[RuleDefinition]:
+        """Get all rules that match the given trigger.
+
+        ON_DEMAND bypasses trigger filtering and returns all rules.
+        """
+        if trigger == RuleTrigger.ON_DEMAND:
+            return list(self._rules)
+        return [r for r in self._rules if trigger in r.triggers]
+
+    def evaluate(
+        self,
+        trigger: RuleTrigger,
+        db,
+        action_context: Optional[Dict[str, Any]] = None,
+    ) -> List[RuleResult]:
+        """Evaluate all rules matching the trigger.
+
+        Args:
+            trigger: The event that triggered evaluation
+            db: Graph adapter (AIContextDB or CSR adapter)
+            action_context: For pre-action rules, describes the proposed action
+
+        Returns:
+            List of RuleResult sorted by severity (critical first)
+        """
+        rules = self.get_rules_for_trigger(trigger)
+        all_results: List[RuleResult] = []
+
+        for rule in rules:
+            try:
+                results = self.evaluate_rule(rule, db, action_context)
+                all_results.extend(results)
+            except Exception as e:
+                logger.error(
+                    "[RULES] Error evaluating rule %s: %s", rule.name, e
+                )
+
+        # Sort by severity (critical first)
+        all_results.sort(key=lambda r: _SEVERITY_ORDER.get(r.severity, 99))
+        return all_results
+
+    def evaluate_rule(
+        self,
+        rule: RuleDefinition,
+        db,
+        action_context: Optional[Dict[str, Any]] = None,
+    ) -> List[RuleResult]:
+        """Evaluate a single rule against the graph."""
+        if rule.rule_type == "aggregate":
+            return self._aggregate.evaluate(rule, db)
+        elif rule.rule_type == "temporal":
+            return self._temporal.evaluate(rule, db)
+        elif rule.rule_type == "pre_action":
+            return self._pre_action.evaluate(rule, db, action_context or {})
+        else:
+            logger.warning(
+                "[RULES] Unknown rule type %s for rule %s",
+                rule.rule_type, rule.name,
+            )
+            return []

contextsynapse/rules/evaluators/__init__.py

@@ -0,0 +1,6 @@
+"""Rule evaluators — one per rule type."""
+from .aggregate import AggregateEvaluator
+from .temporal import TemporalEvaluator
+from .pre_action import PreActionEvaluator
+
+__all__ = ["AggregateEvaluator", "TemporalEvaluator", "PreActionEvaluator"]

contextsynapse/rules/evaluators/aggregate.py

@@ -0,0 +1,205 @@
+"""AggregateEvaluator — evaluates portfolio aggregate rules.
+
+Supports:
+  sum       — SUM(field) GROUP BY group_by, check each group against threshold
+  top_n_sum — Sort by field desc, sum top N, check against threshold
+  count_ratio — COUNT(WHERE condition) / COUNT(all), check ratio against threshold
+
+Usage:
+    evaluator = AggregateEvaluator()
+    results = evaluator.evaluate(rule, db)
+"""
+from __future__ import annotations
+
+import logging
+import operator
+from collections import defaultdict
+from typing import Any, Callable, Dict, List
+
+from ..models import RuleAction, RuleDefinition, RuleResult, RuleSeverity
+
+logger = logging.getLogger(__name__)
+
+_OP_MAP: Dict[str, Callable] = {
+    ">": operator.gt,
+    ">=": operator.ge,
+    "<": operator.lt,
+    "<=": operator.le,
+    "==": operator.eq,
+    "=": operator.eq,
+}
+
+
+class AggregateEvaluator:
+    """Evaluates aggregate rules against graph node properties."""
+
+    def evaluate(self, rule: RuleDefinition, db) -> List[RuleResult]:
+        """Evaluate an aggregate rule against the graph."""
+        condition = rule.condition
+        agg_type = condition.get("aggregate", "sum")
+        adapter = getattr(db, "csr_adapter", db)
+
+        if agg_type == "sum":
+            return self._eval_sum_group_by(rule, adapter)
+        elif agg_type == "top_n_sum":
+            return self._eval_top_n_sum(rule, adapter)
+        elif agg_type == "count_ratio":
+            return self._eval_count_ratio(rule, adapter)
+        else:
+            logger.warning("[RULES] Unknown aggregate type: %s", agg_type)
+            return []
+
+    def _eval_sum_group_by(
+        self, rule: RuleDefinition, adapter
+    ) -> List[RuleResult]:
+        """SUM(field) GROUP BY group_by — check each group against threshold."""
+        cond = rule.condition
+        node_type = cond.get("node_type", "")
+        field_name = cond.get("field", "")
+        group_by = cond.get("group_by", "")
+        op_str = cond.get("operator", ">")
+        threshold = float(cond.get("threshold", 0))
+        op_fn = _OP_MAP.get(op_str, operator.gt)
+
+        groups: Dict[str, float] = defaultdict(float)
+        nodes = adapter.get_all_nodes(node_type=node_type) if node_type else adapter.get_all_nodes()
+
+        for node in nodes:
+            props = node.properties if hasattr(node, "properties") else {}
+            group_key = props.get(group_by, "unknown")
+            value = props.get(field_name, 0)
+            if value is None:
+                value = 0
+            try:
+                groups[str(group_key)] += float(value)
+            except (TypeError, ValueError):
+                continue
+
+        results = []
+        for group, value in groups.items():
+            if op_fn(value, threshold):
+                msg = rule.message
+                try:
+                    msg = msg.format(
+                        group=group, value=value, threshold=threshold,
+                    )
+                except (KeyError, ValueError, IndexError):
+                    pass
+
+                results.append(RuleResult(
+                    rule_name=rule.name,
+                    action=rule.action,
+                    severity=rule.severity,
+                    message=msg,
+                    details={
+                        "group": group,
+                        "value": value,
+                        "threshold": threshold,
+                        "operator": op_str,
+                    },
+                    invoke_skill=rule.invoke_skill,
+                ))
+        return results
+
+    def _eval_top_n_sum(
+        self, rule: RuleDefinition, adapter
+    ) -> List[RuleResult]:
+        """Sort nodes by field desc, sum top N, check against threshold."""
+        cond = rule.condition
+        node_type = cond.get("node_type", "")
+        field_name = cond.get("field", "")
+        n = int(cond.get("n", 5))
+        op_str = cond.get("operator", ">")
+        threshold = float(cond.get("threshold", 0))
+        op_fn = _OP_MAP.get(op_str, operator.gt)
+
+        nodes = adapter.get_all_nodes(node_type=node_type) if node_type else adapter.get_all_nodes()
+        values = []
+        for node in nodes:
+            props = node.properties if hasattr(node, "properties") else {}
+            v = props.get(field_name, 0)
+            if v is None:
+                v = 0
+            try:
+                values.append(float(v))
+            except (TypeError, ValueError):
+                continue
+
+        values.sort(reverse=True)
+        top_n_sum = sum(values[:n])
+
+        if op_fn(top_n_sum, threshold):
+            msg = rule.message
+            try:
+                msg = msg.format(value=top_n_sum, threshold=threshold, n=n)
+            except (KeyError, ValueError, IndexError):
+                pass
+
+            return [RuleResult(
+                rule_name=rule.name,
+                action=rule.action,
+                severity=rule.severity,
+                message=msg,
+                details={"value": top_n_sum, "threshold": threshold, "n": n},
+                invoke_skill=rule.invoke_skill,
+            )]
+        return []
+
+    def _eval_count_ratio(
+        self, rule: RuleDefinition, adapter
+    ) -> List[RuleResult]:
+        """COUNT(WHERE condition) / COUNT(all), check ratio against threshold."""
+        cond = rule.condition
+        node_type = cond.get("node_type", "")
+        where_field = cond.get("where_field", "")
+        where_op_str = cond.get("where_operator", "<=")
+        where_threshold = float(cond.get("where_threshold", 0))
+        where_op = _OP_MAP.get(where_op_str, operator.le)
+        op_str = cond.get("operator", "<")
+        threshold = float(cond.get("threshold", 0))
+        op_fn = _OP_MAP.get(op_str, operator.lt)
+
+        nodes = adapter.get_all_nodes(node_type=node_type) if node_type else adapter.get_all_nodes()
+
+        total = 0
+        matching = 0
+        for node in nodes:
+            props = node.properties if hasattr(node, "properties") else {}
+            total += 1
+            field_val = props.get(where_field)
+            if field_val is not None:
+                try:
+                    if where_op(float(field_val), where_threshold):
+                        matching += 1
+                except (TypeError, ValueError):
+                    continue
+
+        if total == 0:
+            return []
+
+        ratio = matching / total
+
+        if op_fn(ratio, threshold):
+            msg = rule.message
+            try:
+                msg = msg.format(
+                    value=ratio, threshold=threshold,
+                    matching=matching, total=total,
+                )
+            except (KeyError, ValueError, IndexError):
+                pass
+
+            return [RuleResult(
+                rule_name=rule.name,
+                action=rule.action,
+                severity=rule.severity,
+                message=msg,
+                details={
+                    "value": ratio,
+                    "threshold": threshold,
+                    "matching": matching,
+                    "total": total,
+                },
+                invoke_skill=rule.invoke_skill,
+            )]
+        return []

contextsynapse/rules/evaluators/custom.py

@@ -0,0 +1,170 @@
+"""Custom rule evaluator — evaluates user-defined rules stored in graph."""
+from __future__ import annotations
+import logging
+from typing import Any, Dict, List, Optional
+
+from ..models import RuleAction, RuleResult, RuleSeverity
+
+logger = logging.getLogger(__name__)
+
+_OPERATORS = {
+    "gt": lambda a, b: a > b,
+    "gte": lambda a, b: a >= b,
+    "lt": lambda a, b: a < b,
+    "lte": lambda a, b: a <= b,
+    "eq": lambda a, b: a == b,
+    "neq": lambda a, b: a != b,
+}
+
+_FIELDS = {
+    "stock_weight": "Max single stock weight (%)",
+    "sector_weight": "Max sector weight (%)",
+    "top5_concentration": "Top 5 holdings concentration (%)",
+    "total_value": "Portfolio total value (₹)",
+    "cash_balance_pct": "Cash balance (%)",
+    "holding_count": "Number of holdings",
+    "avg_cost": "Average cost per holding (₹)",
+    "portfolio_drift": "Portfolio drift (%)",
+}
+
+
+def _compute_metrics(holdings: List[Dict]) -> Dict[str, Any]:
+    """Compute all portfolio metrics from holdings list."""
+    total_value = sum(
+        float(h.get("quantity", 0)) * float(h.get("current_price") or h.get("avg_cost", 0))
+        for h in holdings
+    )
+
+    stock_weights: Dict[str, float] = {}
+    sector_weights: Dict[str, float] = {}
+
+    for h in holdings:
+        symbol = h.get("stock_symbol", "UNKNOWN")
+        sector = h.get("sector", "Unknown")
+        qty = float(h.get("quantity", 0))
+        price = float(h.get("current_price") or h.get("avg_cost", 0))
+        mv = qty * price
+        weight = (mv / total_value * 100) if total_value > 0 else 0
+        stock_weights[symbol] = stock_weights.get(symbol, 0) + weight
+        sector_weights[sector] = sector_weights.get(sector, 0) + weight
+
+    sorted_weights = sorted(stock_weights.values(), reverse=True)
+    top5_concentration = sum(sorted_weights[:5])
+
+    return {
+        "total_value": total_value,
+        "stock_weights": stock_weights,
+        "sector_weights": sector_weights,
+        "max_stock_weight": max(stock_weights.values()) if stock_weights else 0.0,
+        "max_sector_weight": max(sector_weights.values()) if sector_weights else 0.0,
+        "top5_concentration": top5_concentration,
+        "cash_balance_pct": 0.0,
+        "holding_count": float(len(holdings)),
+        "portfolio_drift": 0.0,
+    }
+
+
+_FIELD_ALIAS = {
+    # UI field name → metrics dict key
+    "stock_weight": "max_stock_weight",
+    "sector_weight": "max_sector_weight",
+}
+
+
+def _eval_condition(condition: Dict, metrics: Dict) -> bool:
+    field = condition.get("field", "")
+    operator = condition.get("operator", "gt")
+    value = float(condition.get("value", 0))
+    # Resolve alias (e.g. "stock_weight" → "max_stock_weight")
+    metric_key = _FIELD_ALIAS.get(field, field)
+    metric_val = metrics.get(metric_key, 0.0)
+    op_fn = _OPERATORS.get(operator)
+    if op_fn is None:
+        return False
+    return op_fn(float(metric_val), value)
+
+
+def evaluate_custom_rule(
+    rule_data: Dict[str, Any],
+    holdings: List[Dict[str, Any]],
+) -> Optional[RuleResult]:
+    """Evaluate a single custom rule against portfolio holdings.
+
+    Returns RuleResult if the rule fires, None otherwise.
+    """
+    try:
+        conditions = rule_data.get("conditions", [])
+        conditions_operator = rule_data.get("conditions_operator", "AND")
+        actions = rule_data.get("actions", [])
+
+        if not conditions or not actions:
+            return None
+
+        metrics = _compute_metrics(holdings)
+
+        cond_results = [_eval_condition(c, metrics) for c in conditions]
+
+        # Per-row connectors: each condition has an optional "connector" field
+        # that determines how it joins the NEXT condition.
+        # Walk left-to-right: result = c[0], then apply connector[0] with c[1], etc.
+        # Falls back to global conditions_operator when connector is missing.
+        if len(cond_results) == 0:
+            fired = False
+        elif len(cond_results) == 1:
+            fired = cond_results[0]
+        else:
+            fired = cond_results[0]
+            for i, val in enumerate(cond_results[1:], start=0):
+                conn = (conditions[i].get("connector") if isinstance(conditions[i], dict)
+                        else getattr(conditions[i], "connector", None)) or conditions_operator
+                if conn.upper() == "OR":
+                    fired = fired or val
+                else:
+                    fired = fired and val
+
+        if not fired:
+            return None
+
+        action_data = actions[0]
+        action_type = action_data.get("type", "alert")
+        raw_message = action_data.get("message", rule_data.get("name", "Rule triggered"))
+
+        try:
+            action = RuleAction(action_type)
+        except ValueError:
+            action = RuleAction.ALERT
+
+        try:
+            severity = RuleSeverity(rule_data.get("severity", "medium"))
+        except ValueError:
+            severity = RuleSeverity.MEDIUM
+
+        # Safe template substitution
+        fmt_ctx = {
+            k: round(v, 2) if isinstance(v, float) else v
+            for k, v in metrics.items()
+            if not isinstance(v, dict)
+        }
+        try:
+            message = raw_message.format(**fmt_ctx)
+        except (KeyError, ValueError):
+            message = raw_message
+
+        return RuleResult(
+            rule_name=rule_data.get("name", "Custom Rule"),
+            action=action,
+            severity=severity,
+            message=message,
+            details={
+                "rule_id": rule_data.get("rule_id", ""),
+                "category": rule_data.get("category", "custom"),
+                "fired_conditions": [
+                    conditions[i] for i, r in enumerate(cond_results) if r
+                ],
+                "metrics": {k: round(v, 2) if isinstance(v, float) else v
+                           for k, v in fmt_ctx.items()},
+            },
+        )
+    except Exception as e:
+        logger.error("[CUSTOM_RULE] Error evaluating rule %s: %s", rule_data.get("name"), e)
+        return None