contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/context/smart_budget.py

@@ -0,0 +1,129 @@
+"""
+Smart Context Budgeting — Outcome-based context prioritization.
+
+Instead of giving agents everything, measure which context items
+actually led to good outcomes (task completions, correct decisions)
+and prioritize those for future agents.
+
+The "smart" part: context that helped Agent A succeed gets boosted
+for Agent B working on similar tasks.
+
+Usage:
+    from contextsynapse.context.smart_budget import SmartBudget
+    budget = SmartBudget(graph_registry)
+    ranked = budget.rank_context_items(session_id, agent_id, items, budget_tokens=4000)
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class SmartBudget:
+    """Outcome-aware context prioritization."""
+
+    def __init__(self, graph_registry=None):
+        self._registry = graph_registry
+
+    def rank_context_items(
+        self,
+        namespace: str,
+        agent_id: str,
+        items: List[Dict[str, Any]],
+        budget_tokens: int = 4000,
+    ) -> List[Dict[str, Any]]:
+        """Re-rank context items by outcome relevance.
+
+        Scores each item based on:
+        1. Recency (newer = higher)
+        2. Agent gravity (matches agent's current focus)
+        3. Outcome signal (items referenced by completed tasks score higher)
+        4. Cross-agent success (items that helped other agents complete tasks)
+        """
+        if not items:
+            return []
+
+        # Get completed tasks to measure outcomes
+        outcome_keywords = set()
+        try:
+            from .gravity import get_gravity
+            intent = get_gravity().get_intent(agent_id)
+            outcome_keywords = set(intent.keys())
+        except Exception:
+            pass
+
+        # Get completed task titles/descriptions for outcome signal
+        completed_terms = set()
+        if self._registry and namespace:
+            try:
+                db = self._registry.get_graph(namespace)
+                if db:
+                    for n in db.get_all_nodes():
+                        if getattr(n, "label", "") == "Task":
+                            props = n.properties if hasattr(n, "properties") else {}
+                            if props.get("status") in ("completed", "done"):
+                                title = (props.get("title") or "").lower()
+                                completed_terms.update(w for w in title.split() if len(w) > 3)
+                                desc = (props.get("description") or "").lower()
+                                completed_terms.update(w for w in desc.split() if len(w) > 3)
+            except Exception:
+                pass
+
+        # Score each item
+        scored = []
+        for item in items:
+            score = 1.0
+            text = ""
+            if isinstance(item, dict):
+                text = " ".join(str(v) for v in item.values() if isinstance(v, str)).lower()
+            elif hasattr(item, "properties"):
+                text = " ".join(str(v) for v in item.properties.values() if isinstance(v, str)).lower()
+
+            # Gravity boost: matches agent's current focus
+            if outcome_keywords:
+                gravity_matches = sum(1 for kw in outcome_keywords if kw in text)
+                score += gravity_matches * 0.5
+
+            # Outcome boost: referenced by completed tasks
+            if completed_terms:
+                outcome_matches = sum(1 for term in completed_terms if term in text)
+                score += outcome_matches * 0.3
+
+            # Recency boost
+            created = ""
+            if isinstance(item, dict):
+                created = item.get("_created_at", item.get("created_at", ""))
+            elif hasattr(item, "properties"):
+                created = item.properties.get("_created_at", "")
+            if created:
+                # More recent = higher score (simple: longer ISO string = more recent)
+                score += 0.1  # base boost for having a timestamp
+
+            scored.append((score, item))
+
+        # Sort by score descending
+        scored.sort(key=lambda x: x[0], reverse=True)
+
+        # Budget: keep items until we hit token limit
+        result = []
+        tokens_used = 0
+        for score, item in scored:
+            # Estimate tokens for this item
+            if isinstance(item, dict):
+                item_text = " ".join(str(v) for v in item.values() if isinstance(v, str))
+            elif hasattr(item, "properties"):
+                item_text = " ".join(str(v) for v in item.properties.values() if isinstance(v, str))
+            else:
+                item_text = str(item)
+            item_tokens = len(item_text) // 4
+
+            if tokens_used + item_tokens > budget_tokens and result:
+                break
+            result.append(item)
+            tokens_used += item_tokens
+
+        return result

contextsynapse/context/source_policy.py

@@ -0,0 +1,242 @@
+"""
+Source Policy — Control what data sources a context can ingest from.
+
+Each context can have allowed_sources and blocked_sources in its config.
+Checked before any ingestion (URL, file, connector, agent add_knowledge).
+
+Usage:
+    from contextsynapse.context.source_policy import check_source_allowed
+
+    # Check if a URL is allowed for this context
+    allowed, reason = check_source_allowed(context, source_url="https://docs.example.com/api")
+
+    # Check if a file type is allowed
+    allowed, reason = check_source_allowed(context, source_type="file", filename="spec.pdf")
+
+Config format (stored in context.config):
+    {
+        "source_policy": {
+            "allowed_domains": ["docs.mycompany.com", "github.com/myorg"],
+            "blocked_domains": ["competitor.com"],
+            "allowed_types": ["url", "file", "text"],  # or empty = all
+            "blocked_types": [],
+            "allowed_file_extensions": [".pdf", ".md", ".txt", ".docx"],
+            "max_file_size_mb": 50,
+            "require_approval": false
+        }
+    }
+
+If no source_policy in config → everything is allowed (open by default).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+# Always blocked — security risk regardless of policy
+ALWAYS_BLOCKED_DOMAINS = {
+    "169.254.169.254",  # AWS metadata
+    "metadata.google.internal",  # GCP metadata
+    "localhost",
+    "127.0.0.1",
+    "0.0.0.0",
+    "[::]",
+    "[::1]",
+}
+
+ALWAYS_BLOCKED_IP_PREFIXES = (
+    "10.",       # Private
+    "172.16.",   # Private
+    "172.17.",
+    "172.18.",
+    "172.19.",
+    "172.20.",
+    "172.21.",
+    "172.22.",
+    "172.23.",
+    "172.24.",
+    "172.25.",
+    "172.26.",
+    "172.27.",
+    "172.28.",
+    "172.29.",
+    "172.30.",
+    "172.31.",
+    "192.168.",  # Private
+    "169.254.",  # Link-local / cloud metadata
+)
+
+
+def check_source_allowed(
+    context,
+    source_url: Optional[str] = None,
+    source_type: Optional[str] = None,  # "url", "file", "text", "connector"
+    filename: Optional[str] = None,
+    file_size_mb: Optional[float] = None,
+) -> Tuple[bool, str]:
+    """Check if a source is allowed for this context.
+
+    Returns:
+        (allowed: bool, reason: str)
+    """
+    config = context.config if hasattr(context, "config") else {}
+    policy = config.get("source_policy", {})
+
+    # Auto-derive policy from context's own URL source
+    # If context has source="web:https://docs.example.com", only that domain is allowed
+    ctx_source = getattr(context, "source", "") or ""
+    ctx_type = getattr(context, "context_type", "") or ""
+    if not policy and ctx_source.startswith("web:"):
+        ctx_url = ctx_source[4:]  # strip "web:" prefix
+        parsed_ctx = urlparse(ctx_url)
+        if parsed_ctx.netloc:
+            policy = {"allowed_domains": [parsed_ctx.netloc]}
+
+    # Also check config.url if set directly
+    ctx_config_url = config.get("url", "")
+    if not policy and ctx_config_url:
+        parsed_cfg = urlparse(ctx_config_url)
+        if parsed_cfg.netloc:
+            policy = {"allowed_domains": [parsed_cfg.netloc]}
+
+    # No policy and no URL source = open (everything allowed, except always-blocked)
+    if not policy:
+        if source_url:
+            blocked, reason = _check_security_blocklist(source_url)
+            if blocked:
+                return False, reason
+        return True, "No source policy (open)"
+
+    # Check source type
+    allowed_types = policy.get("allowed_types", [])
+    blocked_types = policy.get("blocked_types", [])
+    if source_type:
+        if blocked_types and source_type in blocked_types:
+            return False, f"Source type '{source_type}' is blocked by policy"
+        if allowed_types and source_type not in allowed_types:
+            return False, f"Source type '{source_type}' not in allowed types: {allowed_types}"
+
+    # Check URL domain
+    if source_url:
+        blocked, reason = _check_security_blocklist(source_url)
+        if blocked:
+            return False, reason
+
+        parsed = urlparse(source_url)
+        domain = parsed.netloc.lower()
+
+        blocked_domains = [d.lower() for d in policy.get("blocked_domains", [])]
+        allowed_domains = [d.lower() for d in policy.get("allowed_domains", [])]
+
+        # Check blocked first
+        for bd in blocked_domains:
+            if domain == bd or domain.endswith("." + bd):
+                return False, f"Domain '{domain}' is blocked by policy"
+
+        # Check allowed (if set, only these are permitted)
+        if allowed_domains:
+            matched = False
+            # Strip www. for comparison
+            bare_domain = domain.removeprefix("www.")
+            for ad in allowed_domains:
+                bare_ad = ad.removeprefix("www.")
+                if bare_domain == bare_ad or domain == ad:
+                    matched = True
+                    break
+                if bare_domain.endswith("." + bare_ad) or domain.endswith("." + ad):
+                    matched = True
+                    break
+                # Support path-prefix matching: "github.com/myorg"
+                if "/" in ad:
+                    ad_domain, ad_path = ad.split("/", 1)
+                    bare_ad_domain = ad_domain.removeprefix("www.")
+                    if (bare_domain == bare_ad_domain or domain == ad_domain) and parsed.path.startswith("/" + ad_path):
+                        matched = True
+                        break
+                # Match related domains: e.g. allowed "timesofindia.com"
+                # should match "timesofindia.indiatimes.com" since the
+                # primary name ("timesofindia") appears as a subdomain label.
+                # Skip this for path-scoped domains like "github.com/myorg".
+                if "/" not in ad:
+                    ad_name = bare_ad.split(".")[0]
+                    if ad_name and len(ad_name) > 3 and bare_domain.startswith(ad_name + "."):
+                        matched = True
+                        break
+            if not matched:
+                return False, f"Domain '{domain}' not in allowed sources: {allowed_domains}"
+
+    # Check file extension
+    if filename:
+        allowed_exts = policy.get("allowed_file_extensions", [])
+        if allowed_exts:
+            ext = "." + filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+            if ext not in allowed_exts:
+                return False, f"File extension '{ext}' not allowed. Permitted: {allowed_exts}"
+
+    # Check file size
+    if file_size_mb is not None:
+        max_size = policy.get("max_file_size_mb", 0)
+        if max_size > 0 and file_size_mb > max_size:
+            return False, f"File size {file_size_mb:.1f}MB exceeds limit of {max_size}MB"
+
+    return True, "Allowed by policy"
+
+
+def _check_security_blocklist(url: str) -> Tuple[bool, str]:
+    """Check if URL targets a dangerous internal resource."""
+    parsed = urlparse(url)
+    host = parsed.netloc.lower().split(":")[0]  # strip port
+
+    if host in ALWAYS_BLOCKED_DOMAINS:
+        return True, f"Blocked: '{host}' is a restricted internal address"
+
+    if any(host.startswith(prefix) for prefix in ALWAYS_BLOCKED_IP_PREFIXES):
+        return True, f"Blocked: '{host}' is a private/internal IP address"
+
+    return False, ""
+
+
+def get_policy_summary(context) -> Dict[str, Any]:
+    """Get a human-readable summary of the context's source policy."""
+    config = context.config if hasattr(context, "config") else {}
+    policy = config.get("source_policy", {})
+
+    # Auto-derive from context URL source
+    ctx_source = getattr(context, "source", "") or ""
+    ctx_config_url = config.get("url", "")
+    if not policy:
+        url_to_check = ""
+        if ctx_source.startswith("web:"):
+            url_to_check = ctx_source[4:]
+        elif ctx_config_url:
+            url_to_check = ctx_config_url
+        if url_to_check:
+            parsed = urlparse(url_to_check)
+            if parsed.netloc:
+                return {
+                    "has_policy": True,
+                    "mode": "auto",
+                    "source_url": url_to_check,
+                    "allowed_domains": [parsed.netloc],
+                    "description": f"Auto-restricted to {parsed.netloc} (from context URL)",
+                }
+        return {"has_policy": False, "mode": "open", "description": "All sources allowed"}
+
+    return {
+        "has_policy": True,
+        "mode": "restricted",
+        "allowed_domains": policy.get("allowed_domains", []),
+        "blocked_domains": policy.get("blocked_domains", []),
+        "allowed_types": policy.get("allowed_types", []),
+        "allowed_file_extensions": policy.get("allowed_file_extensions", []),
+        "max_file_size_mb": policy.get("max_file_size_mb", 0),
+        "description": (
+            f"Allowed: {', '.join(policy.get('allowed_domains', ['all']))}"
+            if policy.get("allowed_domains")
+            else "All domains allowed" + (f", blocked: {', '.join(policy.get('blocked_domains', []))}" if policy.get("blocked_domains") else "")
+        ),
+    }

contextsynapse/context/store_factory.py

@@ -0,0 +1,53 @@
+"""
+Store Factory
+==============
+Single point where the backend decision is made: Redis if available,
+SQLite fallback.  Everything else imports from here.
+
+Usage:
+    from contextsynapse.context.store_factory import create_agent_registry
+
+    registry = create_agent_registry()   # auto-selects backend
+    agent, key = registry.register(name="my-agent")
+"""
+
+import logging
+import os
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_cached_registry = None
+
+
+def create_agent_registry(redis_url: Optional[str] = None, force_new: bool = False):
+    """Create an agent registry — Redis if available, SQLite fallback.
+
+    Args:
+        redis_url: Redis connection URL. Falls back to AICONTEXTDB_REDIS_URL env var.
+        force_new: If True, create a new instance (don't use cached).
+
+    Returns:
+        RedisAgentRegistry or AgentRegistry (SQLite), same API.
+    """
+    global _cached_registry
+    if _cached_registry is not None and not force_new:
+        return _cached_registry
+
+    url = redis_url or os.environ.get("CONTEXTSYNAPSE_REDIS_URL") or os.environ.get("AICONTEXTDB_REDIS_URL")
+    if url:
+        try:
+            from .agents_redis import RedisAgentRegistry
+            registry = RedisAgentRegistry(redis_url=url)
+            registry._r.ping()
+            logger.info("Agent registry: Redis (%s)", url.split("@")[-1])
+            _cached_registry = registry
+            return registry
+        except Exception as e:
+            logger.warning("Redis unavailable (%s), falling back to SQLite", e)
+
+    from .agents import AgentRegistry
+    registry = AgentRegistry()
+    logger.info("Agent registry: SQLite")
+    _cached_registry = registry
+    return registry