contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/shield/shield.py

@@ -0,0 +1,108 @@
+"""AgentShield — facade wiring profile + anomaly + trust + permissions."""
+from __future__ import annotations
+import logging
+from typing import Any, Dict
+from .profile import AgentProfile
+from .anomaly import AnomalyDetector, AnomalyResult
+from .trust_engine import TrustEngine
+from .permissions import AdaptivePermissions, PermissionDecision
+
+logger = logging.getLogger(__name__)
+
+class AgentShield:
+    def __init__(self, redis_client=None):
+        self.profile = AgentProfile(redis_client=redis_client)
+        self.anomaly = AnomalyDetector()
+        self.trust = TrustEngine(redis_client=redis_client)
+        self.permissions = AdaptivePermissions()
+        self._notifications: list = []  # recent notifications (ring buffer)
+        self._max_notifications = 100
+        self._redis = redis_client
+
+    def check_permission(self, agent_id: str, tool_name: str) -> PermissionDecision:
+        score = self.trust.get_score(agent_id)
+        return self.permissions.check(agent_id, tool_name, trust_score=score)
+
+    def on_tool_call(self, agent_id: str, tool_name: str, category: str, success: bool):
+        self.profile.record_tool_call(agent_id, tool_name)
+        if success:
+            self.profile.increment_clean(agent_id)
+            p = self.profile.get(agent_id)
+            self.trust.on_consistency(agent_id, p.get("consecutive_clean", 0))
+
+    def on_feedback(self, agent_id: str, node_id: str, signal: str):
+        signal_map = {"useful": "feedback_useful", "misleading": "feedback_misleading",
+                      "incorrect": "feedback_incorrect", "outdated": "feedback_outdated"}
+        trust_signal = signal_map.get(signal)
+        if trust_signal:
+            old_level = self.get_trust_level(agent_id)
+            self.profile.record_feedback(agent_id, signal)
+            self.trust.on_signal(agent_id, trust_signal)
+            new_level = self.get_trust_level(agent_id)
+            if old_level != new_level:
+                self._notify(agent_id, "trust_change", {
+                    "old_level": old_level, "new_level": new_level,
+                    "trigger": f"feedback:{signal}", "score": self.get_trust_score(agent_id),
+                })
+
+    def on_invalidation(self, invalidated_node_ids: list, reason: str = ""):
+        pass  # wired via on_invalidation_for_agent when called from InvalidationEngine
+
+    def on_invalidation_for_agent(self, agent_id: str, count: int = 1):
+        old_level = self.get_trust_level(agent_id)
+        self.profile.record_invalidation(agent_id, count)
+        for _ in range(count):
+            self.trust.on_signal(agent_id, "content_invalidated")
+        new_level = self.get_trust_level(agent_id)
+        if old_level != new_level:
+            self._notify(agent_id, "trust_change", {
+                "old_level": old_level, "new_level": new_level,
+                "trigger": f"invalidation (x{count})", "score": self.get_trust_score(agent_id),
+            })
+
+    def get_trust_score(self, agent_id: str) -> float:
+        return self.trust.get_score(agent_id)
+
+    def get_trust_level(self, agent_id: str) -> str:
+        return TrustEngine.score_to_level(self.trust.get_score(agent_id))
+
+    def get_profile(self, agent_id: str) -> Dict[str, Any]:
+        return self.profile.get(agent_id)
+
+    def get_anomaly(self, agent_id: str, session_data: Dict = None) -> AnomalyResult:
+        profile = self.profile.get(agent_id)
+        return self.anomaly.analyze(profile, session_data or {})
+
+    def mark_active(self, agent_id: str, task_id: str):
+        """Mark agent as mid-workflow."""
+        self.permissions.mark_active(agent_id, task_id)
+
+    def mark_idle(self, agent_id: str):
+        """Mark agent as idle."""
+        self.permissions.mark_idle(agent_id)
+
+    def get_notifications(self, limit: int = 50) -> list:
+        """Get recent shield notifications."""
+        return self._notifications[-limit:]
+
+    def _notify(self, agent_id: str, event_type: str, details: dict):
+        """Emit a shield notification."""
+        from datetime import datetime, timezone
+        notification = {
+            "agent_id": agent_id,
+            "event_type": event_type,
+            "details": details,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        self._notifications.append(notification)
+        if len(self._notifications) > self._max_notifications:
+            self._notifications = self._notifications[-self._max_notifications:]
+        # Also publish to Redis for cross-process visibility
+        if self._redis:
+            try:
+                import json
+                self._redis.lpush("contextcore:shield:notifications", json.dumps(notification))
+                self._redis.ltrim("contextcore:shield:notifications", 0, self._max_notifications - 1)
+            except Exception:
+                pass
+        logger.info("[SHIELD] %s: %s — %s", event_type, agent_id[:12], details)

contextsynapse/shield/trust_engine.py

@@ -0,0 +1,69 @@
+"""TrustEngine — auto-adjust trust score from quality signals."""
+from __future__ import annotations
+import logging
+from typing import Dict
+
+logger = logging.getLogger(__name__)
+
+_ADJUSTMENTS = {
+    "feedback_useful": 0.02, "feedback_misleading": -0.08,
+    "feedback_incorrect": -0.15, "feedback_outdated": -0.05,
+    "content_invalidated": -0.10, "anomaly_detected": -0.20,
+    "anomaly_cleared": 0.05, "consistency_bonus": 0.01,
+}
+_DEFAULT_SCORE = 0.5
+
+class TrustEngine:
+    def __init__(self, redis_client=None):
+        self._redis = redis_client
+        self._scores: Dict[str, float] = {}
+        self._prefix = "contextcore:shield:trust"
+
+    def get_score(self, agent_id: str) -> float:
+        if agent_id in self._scores:
+            return self._scores[agent_id]
+        if self._redis:
+            try:
+                val = self._redis.hget(f"{self._prefix}:{agent_id}", "score")
+                if val is not None:
+                    score = float(val.decode() if isinstance(val, bytes) else val)
+                    self._scores[agent_id] = score
+                    return score
+            except Exception:
+                pass
+        self._scores[agent_id] = _DEFAULT_SCORE
+        return _DEFAULT_SCORE
+
+    def on_signal(self, agent_id: str, signal: str):
+        delta = _ADJUSTMENTS.get(signal, 0.0)
+        if delta == 0.0:
+            return
+        current = self.get_score(agent_id)
+        if delta > 0:
+            delta *= (1.0 - current)
+        new_score = max(0.0, min(1.0, current + delta))
+        self._set_score(agent_id, new_score)
+        old_level = self.score_to_level(current)
+        new_level = self.score_to_level(new_score)
+        if old_level != new_level:
+            logger.info("[SHIELD] Agent %s trust: %s -> %s (%.3f, %s)", agent_id[:12], old_level, new_level, new_score, signal)
+
+    def on_consistency(self, agent_id: str, consecutive_clean: int):
+        if consecutive_clean > 0 and consecutive_clean % 10 == 0:
+            self.on_signal(agent_id, "consistency_bonus")
+
+    @staticmethod
+    def score_to_level(score: float) -> str:
+        if score >= 0.8: return "trusted"
+        if score >= 0.5: return "verified"
+        if score >= 0.2: return "provisional"
+        return "untrusted"
+
+    def _set_score(self, agent_id: str, score: float):
+        score = round(score, 4)
+        self._scores[agent_id] = score
+        if self._redis:
+            try:
+                self._redis.hset(f"{self._prefix}:{agent_id}", mapping={"score": str(score), "level": self.score_to_level(score)})
+            except Exception:
+                pass

contextsynapse/skills/__init__.py

@@ -0,0 +1,14 @@
+"""Skill Engine — YAML-driven composable agent capabilities."""
+from .models import (
+    SkillChainRule, SkillContextRequirement, SkillDefinition,
+    SkillResult, SkillStatus, SkillTier,
+)
+from .loader import SkillLoader
+from .engine import SkillEngine
+
+__all__ = [
+    "SkillChainRule", "SkillContextRequirement", "SkillDefinition",
+    "SkillResult", "SkillStatus", "SkillTier",
+    "SkillLoader",
+    "SkillEngine",
+]

contextsynapse/skills/engine.py

@@ -0,0 +1,233 @@
+"""SkillEngine — orchestrates skill invocation, rule evaluation, and chaining.
+
+The engine:
+1. Loads skill definition by name
+2. Evaluates applicable rules against the graph
+3. Determines skill status (SUCCESS/BLOCKED/PARTIAL) from rule results
+4. Evaluates chain conditions to determine next skills
+5. Returns SkillResult with output + chains
+
+The engine does NOT:
+- Call LLMs
+- Execute trades
+- Modify the graph
+- Invoke chained skills (caller does that)
+
+Usage:
+    engine = SkillEngine(skill_loader=loader, rules_engine=rules)
+    result = engine.invoke("compliance-check", db)
+    if result.has_blocks():
+        raise ComplianceError(result.message)
+    for chain in result.chain_invocations:
+        engine.invoke(chain, db)
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .loader import SkillLoader
+from .models import SkillChainRule, SkillDefinition, SkillResult, SkillStatus
+
+logger = logging.getLogger(__name__)
+
+
+class SkillEngine:
+    """Orchestrates skill invocation — rules + chains."""
+
+    def __init__(
+        self,
+        skill_loader: SkillLoader,
+        rules_engine=None,
+    ):
+        self._loader = skill_loader
+        self._rules_engine = rules_engine
+
+    def get_skill(self, name: str) -> Optional[SkillDefinition]:
+        """Get a skill definition by name."""
+        return self._loader.get_skill(name)
+
+    def list_skills(self) -> List[str]:
+        """List all loaded skill names."""
+        return list(self._loader._skills.keys())
+
+    def invoke(
+        self,
+        skill_name: str,
+        db,
+        action_context: Optional[Dict[str, Any]] = None,
+    ) -> SkillResult:
+        """Invoke a skill — evaluate rules and determine chains.
+
+        Args:
+            skill_name: Name of the skill to invoke
+            db: Graph adapter
+            action_context: For pre-action skills, the proposed action details
+
+        Returns:
+            SkillResult with status, rule results, and chain invocations
+        """
+        skill = self.get_skill(skill_name)
+        if skill is None:
+            return SkillResult(
+                skill_name=skill_name,
+                status=SkillStatus.ERROR,
+                message=f"Skill '{skill_name}' not found",
+            )
+
+        # Evaluate rules
+        rule_results = []
+        if self._rules_engine and skill.rules:
+            rule_results = self._evaluate_skill_rules(skill, db, action_context)
+
+        # Determine status from rule results
+        status = self._determine_status(rule_results)
+
+        # Build result
+        result = SkillResult(
+            skill_name=skill_name,
+            status=status,
+            output=self._build_output(skill, rule_results),
+            rule_results=rule_results,
+            message=self._build_message(skill, status, rule_results),
+        )
+
+        # Evaluate chains
+        result.chain_invocations = self.evaluate_chains(skill, result)
+
+        return result
+
+    def evaluate_chains(
+        self, skill_def: SkillDefinition, result: SkillResult
+    ) -> List[str]:
+        """Evaluate chain conditions and return list of skills to invoke next."""
+        chains = []
+        for chain_rule in skill_def.chains_to:
+            if self._chain_condition_met(chain_rule, result):
+                chains.append(chain_rule.skill)
+        return chains
+
+    def _evaluate_skill_rules(
+        self, skill: SkillDefinition, db, action_context: Optional[Dict]
+    ) -> list:
+        """Evaluate the rules specified by this skill."""
+        from contextsynapse.rules.models import RuleTrigger
+
+        # Determine trigger type based on skill triggers
+        trigger = RuleTrigger.ON_DEMAND
+        if "pre_trade" in skill.triggers:
+            trigger = RuleTrigger.ON_TRADE
+        elif "on_schedule" in skill.triggers or "daily_close" in skill.triggers:
+            trigger = RuleTrigger.ON_SCHEDULE
+
+        # Get all rule results for the trigger
+        all_results = self._rules_engine.evaluate(
+            trigger, db, action_context=action_context
+        )
+
+        # Filter to only rules this skill cares about
+        if skill.rules:
+            skill_rule_names = set(skill.rules)
+            filtered = [r for r in all_results if r.rule_name in skill_rule_names]
+            return filtered
+
+        return all_results
+
+    def _determine_status(self, rule_results: list) -> SkillStatus:
+        """Determine skill status from rule evaluation results."""
+        from contextsynapse.rules.models import RuleAction
+
+        if not rule_results:
+            return SkillStatus.SUCCESS
+
+        has_blocks = any(r.action == RuleAction.BLOCK for r in rule_results)
+        has_warns = any(r.action == RuleAction.WARN for r in rule_results)
+
+        if has_blocks:
+            return SkillStatus.BLOCKED
+        elif has_warns:
+            return SkillStatus.PARTIAL
+        else:
+            return SkillStatus.SUCCESS
+
+    def _build_output(self, skill: SkillDefinition, rule_results: list) -> Dict:
+        """Build skill output from rule results."""
+        from contextsynapse.rules.models import RuleAction
+
+        violations = [r.to_dict() for r in rule_results if r.action == RuleAction.BLOCK]
+        warnings = [r.to_dict() for r in rule_results if r.action == RuleAction.WARN]
+
+        status = "PASS"
+        if violations:
+            status = "BREACH"
+        elif warnings:
+            status = "WARNING"
+
+        return {
+            "status": status,
+            "violations": violations,
+            "warnings": warnings,
+            "rules_evaluated": len(rule_results),
+        }
+
+    def _build_message(
+        self, skill: SkillDefinition, status: SkillStatus, rule_results: list
+    ) -> str:
+        """Build a human-readable message from the skill result."""
+        from contextsynapse.rules.models import RuleAction
+
+        if status == SkillStatus.BLOCKED:
+            blocks = [r.message for r in rule_results if r.action == RuleAction.BLOCK]
+            return f"BLOCKED: {'; '.join(blocks)}" if blocks else "BLOCKED by compliance rules"
+        elif status == SkillStatus.PARTIAL:
+            return f"Completed with {len(rule_results)} warning(s)"
+        elif status == SkillStatus.ERROR:
+            return "Skill execution failed"
+        else:
+            return f"Completed successfully ({len(rule_results)} rules evaluated)"
+
+    def _chain_condition_met(
+        self, chain_rule: SkillChainRule, result: SkillResult
+    ) -> bool:
+        """Evaluate whether a chain condition is met."""
+        condition = chain_rule.when.strip()
+
+        if not condition:
+            return False
+
+        if condition == "always":
+            return True
+
+        # Simple condition parsing: "field == VALUE"
+        if "==" in condition:
+            parts = condition.split("==")
+            if len(parts) == 2:
+                field_name = parts[0].strip()
+                expected = parts[1].strip()
+
+                if field_name == "status":
+                    # Match against status enum name or value
+                    return (
+                        result.status.value.upper() == expected.upper()
+                        or result.status.name == expected.upper()
+                    )
+
+                # Check output fields
+                actual = result.output.get(field_name)
+                if actual is not None:
+                    return str(actual).upper() == expected.upper()
+
+        # Simple condition: "field > threshold"
+        if ">" in condition and "==" not in condition:
+            parts = condition.split(">")
+            if len(parts) == 2:
+                field_name = parts[0].strip()
+                threshold = parts[1].strip()
+                actual = result.output.get(field_name)
+                if actual is not None:
+                    try:
+                        return float(actual) > float(threshold)
+                    except (TypeError, ValueError):
+                        pass
+
+        return False

contextsynapse/skills/loader.py

@@ -0,0 +1,59 @@
+"""SkillLoader — loads skill definitions from YAML files.
+
+Usage:
+    loader = SkillLoader()
+    loader.load_from_directory("config/skills/")
+    skill = loader.get_skill("compliance-check")
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Dict, Optional
+
+import yaml
+
+from .models import SkillDefinition
+
+logger = logging.getLogger(__name__)
+
+
+class SkillLoader:
+    """Loads SkillDefinition objects from YAML files."""
+
+    def __init__(self):
+        self._skills: Dict[str, SkillDefinition] = {}
+
+    def load_from_yaml(self, path: str) -> SkillDefinition:
+        """Load a single skill from a YAML file."""
+        with open(path, "r") as f:
+            data = yaml.safe_load(f) or {}
+
+        if not data.get("name"):
+            raise ValueError(f"Skill config {path} missing required field: name")
+
+        skill = SkillDefinition.from_dict(data)
+        self._skills[skill.name] = skill
+        return skill
+
+    def load_from_directory(self, config_dir: str) -> Dict[str, SkillDefinition]:
+        """Load all skill YAMLs from a directory. Returns {name: definition}."""
+        config_path = Path(config_dir)
+        if not config_path.is_dir():
+            logger.warning("[SKILLS] Config dir not found: %s", config_dir)
+            return {}
+
+        for f in sorted(config_path.iterdir()):
+            if f.suffix not in (".yaml", ".yml"):
+                continue
+            try:
+                self.load_from_yaml(str(f))
+            except Exception as e:
+                logger.warning("[SKILLS] Skipping %s: %s", f.name, e)
+
+        logger.info("[SKILLS] Loaded %d skills from %s", len(self._skills), config_dir)
+        return dict(self._skills)
+
+    def get_skill(self, name: str) -> Optional[SkillDefinition]:
+        """Get a loaded skill by name."""
+        return self._skills.get(name)

contextsynapse/skills/models.py

@@ -0,0 +1,139 @@
+"""Skill engine data models — definitions, results, context requirements, chains.
+
+A Skill is a composable capability that agents invoke. Each skill defines:
+  - What contexts it needs (boundary template)
+  - What projection tier to use
+  - What rules to evaluate
+  - What output it produces
+  - What skills can chain after it
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from contextsynapse.rules.models import RuleAction, RuleResult
+
+
+class SkillTier(Enum):
+    """CGP projection tier for this skill."""
+    INSTANT = "instant"      # < 50ms, 500 tokens
+    FAST = "fast"            # < 200ms, 1500 tokens
+    STANDARD = "standard"   # < 1000ms, 3000 tokens
+    DEEP = "deep"            # < 5000ms, 8000 tokens
+
+
+class SkillStatus(Enum):
+    """Outcome of a skill execution."""
+    SUCCESS = "success"      # completed, no blocks
+    PARTIAL = "partial"      # completed with warnings
+    BLOCKED = "blocked"      # blocked by compliance rule
+    ERROR = "error"          # failed due to error
+
+
+@dataclass
+class SkillContextRequirement:
+    """A context that a skill needs to operate."""
+    type: str                           # portfolio | rules | market_data | etc.
+    role: str = "input"                 # input (read-only) | output (write)
+    source: Optional[str] = None        # schema | connector | specific context id
+    required: bool = True
+
+
+@dataclass
+class SkillChainRule:
+    """Defines when to invoke another skill after this one."""
+    skill: str                          # skill name to invoke, e.g. "/rebalance"
+    when: str = ""                      # condition expression, e.g. "status == BREACH"
+    reason: str = ""                    # why this chain exists
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SkillDefinition:
+    """A skill loaded from YAML — defines capability, context, rules, chains."""
+
+    name: str
+    description: str = ""
+    version: str = "1.0"
+    triggers: List[str] = field(default_factory=list)
+    contexts: Dict[str, List[SkillContextRequirement]] = field(
+        default_factory=lambda: {"required": [], "optional": []}
+    )
+    projection: Dict[str, Any] = field(default_factory=dict)
+    rules: List[str] = field(default_factory=list)
+    output: Dict[str, Any] = field(default_factory=dict)
+    chains_to: List[SkillChainRule] = field(default_factory=list)
+    configurable: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> SkillDefinition:
+        """Parse a skill definition from YAML dict."""
+        # Parse context requirements
+        ctx_raw = raw.get("contexts", {})
+        contexts: Dict[str, List[SkillContextRequirement]] = {"required": [], "optional": []}
+        for key in ("required", "optional"):
+            for item in ctx_raw.get(key, []):
+                contexts[key].append(SkillContextRequirement(
+                    type=item.get("type", ""),
+                    role=item.get("role", "input"),
+                    source=item.get("source"),
+                    required=(key == "required"),
+                ))
+
+        # Parse chain rules
+        chains = []
+        for item in raw.get("chains_to", []):
+            chains.append(SkillChainRule(
+                skill=item.get("skill", ""),
+                when=item.get("when", ""),
+                reason=item.get("reason", ""),
+                params=item.get("params", {}),
+            ))
+
+        return cls(
+            name=raw.get("name", ""),
+            description=raw.get("description", ""),
+            version=raw.get("version", "1.0"),
+            triggers=raw.get("trigger", []),
+            contexts=contexts,
+            projection=raw.get("projection", {}),
+            rules=raw.get("rules", []),
+            output=raw.get("output", {}),
+            chains_to=chains,
+            configurable=raw.get("configurable", []),
+        )
+
+
+@dataclass
+class SkillResult:
+    """Result of executing a skill."""
+
+    skill_name: str
+    status: SkillStatus
+    output: Dict[str, Any] = field(default_factory=dict)
+    rule_results: List[RuleResult] = field(default_factory=list)
+    chain_invocations: List[str] = field(default_factory=list)
+    message: str = ""
+    executed_at: str = ""
+
+    def __post_init__(self):
+        if not self.executed_at:
+            self.executed_at = datetime.now(timezone.utc).isoformat()
+
+    def has_blocks(self) -> bool:
+        """True if any rule result has a BLOCK action."""
+        return any(r.action == RuleAction.BLOCK for r in self.rule_results)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "skill_name": self.skill_name,
+            "status": self.status.value,
+            "output": self.output,
+            "rule_results": [r.to_dict() for r in self.rule_results],
+            "chain_invocations": self.chain_invocations,
+            "message": self.message,
+            "executed_at": self.executed_at,
+        }

contextsynapse/storage/__init__.py

@@ -0,0 +1,7 @@
+"""Storage abstraction layer."""
+
+from .storage_manager import StorageManager
+from .pure_graph_storage import PureGraphStorage
+from .csr_graph_storage import CSRGraphStorage, CSRGraphStorageAdapter, CSRNode, CSREdge
+
+__all__ = ['StorageManager', 'PureGraphStorage', 'CSRGraphStorage', 'CSRGraphStorageAdapter', 'CSRNode', 'CSREdge']