agent-magnet 0.1.0__tar.gz

agent_magnet-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: agent-magnet
+Version: 0.1.0
+Summary: Self-learning memory infrastructure for AI products
+License: MIT
+Keywords: ai,memory,llm,agents,mcp
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi
+Requires-Dist: redis
+Requires-Dist: litellm
+Requires-Dist: mcp
+Requires-Dist: qdrant-client
+Requires-Dist: neo4j
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# Agent Magnet
+
+Self-learning memory infrastructure for AI products.
+
+## Install
+```
+pip install agent-magnet
+```
+
+## MCP Setup (Claude Desktop / Cursor)
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "agent-magnet": {
+      "command": "agent-magnet-mcp",
+      "env": {
+        "MAGNET_REDIS_URL": "your_redis_url",
+        "MAGNET_OPENAI_KEY": "your_openai_key"
+      }
+    }
+  }
+}
+```
+
+## Proxy Setup (any OpenAI-compatible client)
+```python
+client = OpenAI(
+    base_url="https://magnet-gateway.onrender.com/v1",
+    api_key="mg_sk_...",
+    default_headers={"x-session-id": "user_123"}
+)
+```

agent_magnet-0.1.0/README.md

@@ -0,0 +1,34 @@
+# Agent Magnet
+
+Self-learning memory infrastructure for AI products.
+
+## Install
+```
+pip install agent-magnet
+```
+
+## MCP Setup (Claude Desktop / Cursor)
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "agent-magnet": {
+      "command": "agent-magnet-mcp",
+      "env": {
+        "MAGNET_REDIS_URL": "your_redis_url",
+        "MAGNET_OPENAI_KEY": "your_openai_key"
+      }
+    }
+  }
+}
+```
+
+## Proxy Setup (any OpenAI-compatible client)
+```python
+client = OpenAI(
+    base_url="https://magnet-gateway.onrender.com/v1",
+    api_key="mg_sk_...",
+    default_headers={"x-session-id": "user_123"}
+)
+```

agent_magnet-0.1.0/agent_magnet.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: agent-magnet
+Version: 0.1.0
+Summary: Self-learning memory infrastructure for AI products
+License: MIT
+Keywords: ai,memory,llm,agents,mcp
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi
+Requires-Dist: redis
+Requires-Dist: litellm
+Requires-Dist: mcp
+Requires-Dist: qdrant-client
+Requires-Dist: neo4j
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# Agent Magnet
+
+Self-learning memory infrastructure for AI products.
+
+## Install
+```
+pip install agent-magnet
+```
+
+## MCP Setup (Claude Desktop / Cursor)
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "agent-magnet": {
+      "command": "agent-magnet-mcp",
+      "env": {
+        "MAGNET_REDIS_URL": "your_redis_url",
+        "MAGNET_OPENAI_KEY": "your_openai_key"
+      }
+    }
+  }
+}
+```
+
+## Proxy Setup (any OpenAI-compatible client)
+```python
+client = OpenAI(
+    base_url="https://magnet-gateway.onrender.com/v1",
+    api_key="mg_sk_...",
+    default_headers={"x-session-id": "user_123"}
+)
+```

agent_magnet-0.1.0/agent_magnet.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+README.md
+pyproject.toml
+agent_magnet.egg-info/PKG-INFO
+agent_magnet.egg-info/SOURCES.txt
+agent_magnet.egg-info/dependency_links.txt
+agent_magnet.egg-info/entry_points.txt
+agent_magnet.egg-info/requires.txt
+agent_magnet.egg-info/top_level.txt
+magnet/__init__.py
+magnet/aggregate_store.py
+magnet/buffer.py
+magnet/classifier.py
+magnet/client.py
+magnet/consolidation.py
+magnet/episodic_store.py
+magnet/knowledge_store.py
+magnet/mcp_server.py
+magnet/memory_orchestrator.py
+magnet/reflector.py
+magnet/router.py
+magnet/signals.py
+magnet/store.py
+tests/test_buffer.py
+tests/test_classifier.py
+tests/test_episodic_store.py
+tests/test_memory_orchestrator.py
+tests/test_router.py

agent_magnet-0.1.0/agent_magnet.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_magnet-0.1.0/agent_magnet.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-magnet-mcp = magnet.mcp_server:main

agent_magnet-0.1.0/agent_magnet.egg-info/requires.txt

@@ -0,0 +1,11 @@
+fastapi
+redis
+litellm
+mcp
+qdrant-client
+neo4j
+python-dotenv
+
+[dev]
+pytest>=8.0
+pytest-asyncio

agent_magnet-0.1.0/agent_magnet.egg-info/top_level.txt

@@ -0,0 +1 @@
+magnet

agent_magnet-0.1.0/magnet/__init__.py

@@ -0,0 +1,22 @@
+from .client import BehavioralMemory
+from .signals import SignalDetector
+from .reflector import Reflector
+from .classifier import IntelligentClassifier, ClassificationResult
+from .router import ModelRouter, RouterDecision
+from .episodic_store import EpisodicStore
+from .knowledge_store import KnowledgeStore
+from .memory_orchestrator import MemoryOrchestrator
+
+__version__ = "0.1.0"
+__all__ = [
+    "BehavioralMemory",
+    "SignalDetector",
+    "Reflector",
+    "IntelligentClassifier",
+    "ClassificationResult",
+    "ModelRouter",
+    "RouterDecision",
+    "EpisodicStore",
+    "KnowledgeStore",
+    "MemoryOrchestrator",
+]

agent_magnet-0.1.0/magnet/aggregate_store.py

@@ -0,0 +1,164 @@
+# ═══════════════════════════════════════════════════
+# GDPR/CCPA COMPLIANCE DOCUMENTATION
+# ═══════════════════════════════════════════════════
+# This module processes anonymous data in compliance with GDPR
+# and CCPA standards. It does not contain personal data (PII).
+#
+# Legal Basis: Anonymous Data Processing
+# "Data rendered anonymous in such a way that the data subject
+#  is not or no longer identifiable is excluded from GDPR scope."
+#
+# Techniques Applied:
+# 1. K-Anonymity (min_k=5): Patterns unique to a single user
+#    are not added to the aggregate pool.
+# 2. Differential Privacy (Laplace, ε=1.0):
+#    Mathematical noise is added to query results.
+# 3. Data Minimization: Only signal type, category,
+#    dimension, and value are stored.
+# 4. TTL: 90 days — automatic destruction.
+#
+# NEVER enters the Aggregate store:
+# - user_id, session_id, project_id
+# - Message content
+# - Exact timestamps
+# - IP addresses
+# ═══════════════════════════════════════════════════
+
+import datetime
+import json
+import numpy as np
+from typing import Any
+
+class AggregateSignalStore:
+    def __init__(self, redis_client: Any, min_k: int = 5, epsilon: float = 1.0):
+        self._redis = redis_client
+        self._min_k = min_k      # k-anonymity: min 5 distinct records
+        self._epsilon = epsilon  # differential privacy noise
+
+    def record(self, signal_type: str, query_category: str, dimension: str, dimension_value: str) -> None:
+        """
+        Records an anonymous signal in a GDPR-compliant manner.
+        Contains no PII — statistical counter only.
+        """
+        if not self._redis:
+            return
+            
+        allowed_signal_types = {
+            "correction", "rejection", "preference", "clarification", "positive"
+        }
+        if signal_type not in allowed_signal_types:
+            return
+        
+        allowed_dimensions = {
+            "response_length", "detail_level", "tone", "format", "language", "unknown", "heuristic", "llm_extracted"
+        }
+        if dimension not in allowed_dimensions:
+            return
+        
+        # Time bucket (rounded to the hour for privacy, no exact timestamps)
+        hour_bucket = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H")
+        
+        # Redis key — NO PII included
+        key = f"magnet:agg:{signal_type}:{query_category}:{dimension}:{dimension_value}"
+        counter_key = f"magnet:agg:count:{signal_type}:{query_category}"
+        
+        try:
+            pipe = self._redis.pipeline()
+            pipe.incr(key)
+            pipe.incr(counter_key)
+            pipe.expire(key, 60 * 60 * 24 * 90)        # 90-day TTL
+            pipe.expire(counter_key, 60 * 60 * 24 * 90) 
+            pipe.execute()
+        except Exception:
+            pass
+
+    def get_prior(self, query_category: str, dimension: str) -> Any:
+        """
+        Returns the aggregate prior probability for a new user.
+        K-anonymity: Returns None if total records < min_k.
+        Differential Privacy: Adds Laplace noise to the results.
+        """
+        if not self._redis:
+            return None
+            
+        pattern = f"magnet:agg:*:{query_category}:{dimension}:*"
+        try:
+            keys = list(self._redis.scan_iter(pattern))
+            if not keys:
+                return None
+            
+            counts = {}
+            total = 0
+            for key in keys:
+                value = key.split(":")[-1]
+                count = int(self._redis.get(key) or 0)
+                counts[value] = count
+                total += count
+            
+            if total < self._min_k:
+                return None
+            
+            noisy_counts = {}
+            for value, count in counts.items():
+                noise = np.random.laplace(0, 1.0 / self._epsilon)
+                noisy_counts[value] = max(0, count + noise)
+            
+            noisy_total = sum(noisy_counts.values())
+            if noisy_total == 0:
+                return None
+            
+            return {v: round(c / noisy_total, 3) for v, c in noisy_counts.items()}
+        except Exception:
+            return None
+
+    def get_cold_start_injection(self, query_category: str) -> str:
+        """Generates the cold start injection context for a new user."""
+        if not self._redis:
+            return ""
+            
+        lines = []
+        for dimension in ["response_length", "detail_level", "tone", "language", "heuristic", "llm_extracted"]:
+            prior = self.get_prior(query_category, dimension)
+            if prior:
+                top_value = max(prior, key=prior.get)
+                top_pct = int(prior[top_value] * 100)
+                if top_pct >= 55:  # Add if there is a strong aggregate signal
+                    lines.append(f"  - {dimension}: {top_value} ({top_pct}% of users)")
+        
+        if not lines:
+            return ""
+
+        return (
+            "[Aggregate Prior]\n"
+            "Based on anonymized patterns from similar users:\n" +
+            "\n".join(lines) + "\n\n"
+            "Note: These are statistical suggestions. "
+            "User's own behavior takes priority."
+        )
+
+    def store_consolidated_pattern(self, pattern: dict) -> bool:
+        """
+        Stores a cross-user consolidated pattern from ConsolidationEngine.
+        Never overwrites an existing entry that has equal or higher confidence.
+        Returns True if written, False if skipped.
+        """
+        if not self._redis:
+            return False
+        context = pattern.get("context", "general")
+        relation = pattern.get("relation", "unknown")
+        subject = pattern.get("subject", "").lower().replace(" ", "_")
+        key = f"magnet:consolidated:{context}:{relation}:{subject}"
+        try:
+            existing_raw = self._redis.get(key)
+            if existing_raw:
+                existing = json.loads(existing_raw)
+                if existing.get("confidence", 0.0) >= pattern.get("confidence", 0.0):
+                    return False
+            self._redis.setex(
+                key,
+                60 * 60 * 24 * 90,
+                json.dumps(pattern, ensure_ascii=False),
+            )
+            return True
+        except Exception:
+            return False

agent_magnet-0.1.0/magnet/buffer.py

@@ -0,0 +1,78 @@
+"""
+Signal Buffer
+-------------
+Accumulates signals in Redis.
+Triggers Reflector when threshold is met.
+
+If no Redis, in-memory fallback works (for development).
+"""
+
+from __future__ import annotations
+import json
+import time
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_BUFFER_PREFIX = "vmm:signals:"
+_DEFAULT_TTL = 60 * 60 * 24 * 7  # 7 days
+_ATOMIC_FLUSH_SCRIPT = """
+local vals = redis.call('LRANGE', KEYS[1], 0, -1)
+redis.call('DEL', KEYS[1])
+return vals
+"""
+
+
+class SignalBuffer:
+    def __init__(
+        self,
+        redis_client: Any | None = None,
+        threshold: int = 5,
+        ttl: int = _DEFAULT_TTL,
+    ):
+        self._redis = redis_client
+        self.threshold = threshold
+        self.ttl = ttl
+        self._memory: dict[str, list[dict]] = {}  # fallback
+
+    def push(self, user_id: str, signals: list[dict]) -> int:
+        if not signals:
+            return self._count(user_id)
+
+        key = _BUFFER_PREFIX + user_id
+        enriched = [{"ts": time.time(), **s} for s in signals]
+
+        if self._redis:
+            pipe = self._redis.pipeline()
+            for sig in enriched:
+                pipe.rpush(key, json.dumps(sig))
+            pipe.expire(key, self.ttl)
+            pipe.execute()
+            return self._redis.llen(key)
+
+        self._memory.setdefault(key, []).extend(enriched)
+        return len(self._memory[key])
+
+    def should_reflect(self, user_id: str) -> bool:
+        return self._count(user_id) >= self.threshold
+
+    def flush(self, user_id: str) -> list[dict]:
+        key = _BUFFER_PREFIX + user_id
+        if self._redis:
+            results = self._redis.eval(_ATOMIC_FLUSH_SCRIPT, 1, key)
+            return [json.loads(r) for r in results]
+
+        return self._memory.pop(key, [])
+
+    def peek(self, user_id: str) -> list[dict]:
+        key = _BUFFER_PREFIX + user_id
+        if self._redis:
+            return [json.loads(r) for r in self._redis.lrange(key, 0, -1)]
+        return list(self._memory.get(key, []))
+
+    def _count(self, user_id: str) -> int:
+        key = _BUFFER_PREFIX + user_id
+        if self._redis:
+            return self._redis.llen(key)
+        return len(self._memory.get(key, []))