hipcortex 0.3.2__tar.gz → 0.5.0__tar.gz

hipcortex-0.5.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: hipcortex
+Version: 0.5.0
+Summary: Persistent causal memory for AI agents -- LangChain, LlamaIndex, AutoGen, CrewAI
+Author: HipCortex Contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/farmountain/HipCortex
+Project-URL: Repository, https://github.com/farmountain/HipCortex
+Project-URL: Issues, https://github.com/farmountain/HipCortex/issues
+Project-URL: Benchmark, https://github.com/farmountain/HipCortex/blob/main/BENCHMARK.md
+Keywords: ai,memory,langchain,autogen,crewai,llm,agents,rag
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: httpx>=0.27
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28; extra == "crewai"
+Requires-Dist: crewai-tools>=0.1; extra == "crewai"
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2; extra == "autogen"
+Provides-Extra: benchmark
+Requires-Dist: mem0ai>=0.1; extra == "benchmark"
+Requires-Dist: tabulate>=0.9; extra == "benchmark"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1; extra == "all"
+Requires-Dist: llama-index-core>=0.10; extra == "all"
+Requires-Dist: crewai>=0.28; extra == "all"
+Requires-Dist: crewai-tools>=0.1; extra == "all"
+Requires-Dist: pyautogen>=0.2; extra == "all"
+Requires-Dist: mem0ai>=0.1; extra == "all"
+Requires-Dist: tabulate>=0.9; extra == "all"
+Dynamic: requires-python
+
+# HipCortex Python SDK (`v0.5.0`)
+
+**Persistent causal topological memory, recursive Bayesian world-model prediction (`/worldmodel/rollout`), and automatic FSM skill compilation for autonomous AI agents.**
+
+Runs against the standalone local Rust binary (`http://127.0.0.1:3030`) with `0.48–0.61 ms p50` write latency, SHA-256 Merkle audit chains, and Headroom context budgeting (`59–88% token savings`).
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install hipcortex
+hipcortex doctor   # verify server health + version after install
+```
+
+---
+
+## ⚡ Quick Start: Multi-Tier Memory & World Model Prediction
+
+```python
+from hipcortex import HipCortexClient
+
+client = HipCortexClient(base_url="http://127.0.0.1:3030")
+
+# 1. Multi-Tier Memory Ingestion (5 verified memory tiers)
+client.add_memory(
+    actor="agent",
+    action="configured",
+    target="jwt_token_ttl=3600",
+    record_type="Working",  # Mapped natively to Temporal tier
+    priority="high"
+)
+
+client.add_memory(
+    actor="agent",
+    action="established",
+    target="All database migrations must run inside transactions",
+    record_type="Semantic", # Mapped natively to Symbolic/LongTerm tier
+    priority="pinned"
+)
+
+# 2. Check SelfModel Execution Capacity Gates before running risky actions
+if client.can_execute("rollout"):
+    print("Health check passed — engine ready for simulation")
+
+# 3. World Model Trajectory Rollout Prediction (POST /worldmodel/rollout)
+rollout_result = client.rollout(
+    initial_state={"db_status": "locked", "active_tx": 1},
+    actions=["rollback_tx", "release_lock", "retry_migration"]
+)
+print("Predicted outcome:", rollout_result)
+```
+
+---
+
+## 🧠 Proactive CodeAct Harness & Live Beliefs
+
+For autonomous agent harnesses (`LangChain`, `LlamaIndex`, `CrewAI`, `AutoGen`), query the topological substrate before reasoning:
+
+```python
+# Query live causal beliefs and Top-K topological context (Personalized PageRank)
+context = client.context(query="database migrations", actor="agent", limit=5)
+print("Active Topological Context:\n", context)
+
+# Store multi-hop reasoning or CoT reflection
+client.add_memory(
+    actor="agent",
+    action="reflected",
+    target="Migration failed due to missing index on users.email",
+    record_type="Causal"
+)
+```
+
+---
+
+## 🧩 Framework Integrations
+
+### LangChain (`ConversationBufferMemory` drop-in)
+```python
+from hipcortex.langchain_memory import HipCortexMemory
+
+memory = HipCortexMemory(session_id="session-42", url="http://127.0.0.1:3030")
+```
+
+### LlamaIndex (`ChatStore`)
+```python
+from hipcortex.llamaindex_storage import HipCortexStorageContext
+
+storage_context = HipCortexStorageContext.from_defaults(client=client)
+```
+
+### CrewAI (`Remember` & `Recall` Tools)
+```python
+from hipcortex.adapters.crewai import HipCortexRememberTool, HipCortexRecallTool
+
+tools = [HipCortexRememberTool(client=client), HipCortexRecallTool(client=client)]
+```
+
+### AutoGen (`Memory` Hook)
+```python
+from hipcortex.adapters.autogen import HipCortexAutoGenMemory
+
+mem = HipCortexAutoGenMemory(client=client, agent_id="researcher")
+agent.register_hook("process_message_before_send", mem.on_message_sent)
+```
+
+---
+
+## 📊 Server Statistics & GDPR Right-to-Forget
+
+```python
+# Get Merkle hash chain status and tier counts
+stats = client.stats()
+print("Memory statistics:", stats)
+
+# Erase all records for a specific actor (GDPR compliant)
+client.forget("agent")
+```

hipcortex-0.5.0/README.md

@@ -0,0 +1,118 @@
+# HipCortex Python SDK (`v0.5.0`)
+
+**Persistent causal topological memory, recursive Bayesian world-model prediction (`/worldmodel/rollout`), and automatic FSM skill compilation for autonomous AI agents.**
+
+Runs against the standalone local Rust binary (`http://127.0.0.1:3030`) with `0.48–0.61 ms p50` write latency, SHA-256 Merkle audit chains, and Headroom context budgeting (`59–88% token savings`).
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install hipcortex
+hipcortex doctor   # verify server health + version after install
+```
+
+---
+
+## ⚡ Quick Start: Multi-Tier Memory & World Model Prediction
+
+```python
+from hipcortex import HipCortexClient
+
+client = HipCortexClient(base_url="http://127.0.0.1:3030")
+
+# 1. Multi-Tier Memory Ingestion (5 verified memory tiers)
+client.add_memory(
+    actor="agent",
+    action="configured",
+    target="jwt_token_ttl=3600",
+    record_type="Working",  # Mapped natively to Temporal tier
+    priority="high"
+)
+
+client.add_memory(
+    actor="agent",
+    action="established",
+    target="All database migrations must run inside transactions",
+    record_type="Semantic", # Mapped natively to Symbolic/LongTerm tier
+    priority="pinned"
+)
+
+# 2. Check SelfModel Execution Capacity Gates before running risky actions
+if client.can_execute("rollout"):
+    print("Health check passed — engine ready for simulation")
+
+# 3. World Model Trajectory Rollout Prediction (POST /worldmodel/rollout)
+rollout_result = client.rollout(
+    initial_state={"db_status": "locked", "active_tx": 1},
+    actions=["rollback_tx", "release_lock", "retry_migration"]
+)
+print("Predicted outcome:", rollout_result)
+```
+
+---
+
+## 🧠 Proactive CodeAct Harness & Live Beliefs
+
+For autonomous agent harnesses (`LangChain`, `LlamaIndex`, `CrewAI`, `AutoGen`), query the topological substrate before reasoning:
+
+```python
+# Query live causal beliefs and Top-K topological context (Personalized PageRank)
+context = client.context(query="database migrations", actor="agent", limit=5)
+print("Active Topological Context:\n", context)
+
+# Store multi-hop reasoning or CoT reflection
+client.add_memory(
+    actor="agent",
+    action="reflected",
+    target="Migration failed due to missing index on users.email",
+    record_type="Causal"
+)
+```
+
+---
+
+## 🧩 Framework Integrations
+
+### LangChain (`ConversationBufferMemory` drop-in)
+```python
+from hipcortex.langchain_memory import HipCortexMemory
+
+memory = HipCortexMemory(session_id="session-42", url="http://127.0.0.1:3030")
+```
+
+### LlamaIndex (`ChatStore`)
+```python
+from hipcortex.llamaindex_storage import HipCortexStorageContext
+
+storage_context = HipCortexStorageContext.from_defaults(client=client)
+```
+
+### CrewAI (`Remember` & `Recall` Tools)
+```python
+from hipcortex.adapters.crewai import HipCortexRememberTool, HipCortexRecallTool
+
+tools = [HipCortexRememberTool(client=client), HipCortexRecallTool(client=client)]
+```
+
+### AutoGen (`Memory` Hook)
+```python
+from hipcortex.adapters.autogen import HipCortexAutoGenMemory
+
+mem = HipCortexAutoGenMemory(client=client, agent_id="researcher")
+agent.register_hook("process_message_before_send", mem.on_message_sent)
+```
+
+---
+
+## 📊 Server Statistics & GDPR Right-to-Forget
+
+```python
+# Get Merkle hash chain status and tier counts
+stats = client.stats()
+print("Memory statistics:", stats)
+
+# Erase all records for a specific actor (GDPR compliant)
+client.forget("agent")
+```

{hipcortex-0.3.2 → hipcortex-0.5.0}/hipcortex/__init__.py

@@ -1,15 +1,15 @@
-"""HipCortex Python SDK — AI memory engine client."""
-
-from .client import HipCortexClient
-from .async_client import AsyncHipCortexClient
-from .langchain_memory import HipCortexMemory, AsyncHipCortexMemory
-from .llamaindex_storage import HipCortexStorageContext
-
-__version__ = "0.2.0"
-__all__ = [
-    "HipCortexClient",
-    "AsyncHipCortexClient",
-    "HipCortexMemory",
-    "AsyncHipCortexMemory",
-    "HipCortexStorageContext",
-]
+"""HipCortex Python SDK — AI memory engine client."""
+
+from .client import HipCortexClient
+from .async_client import AsyncHipCortexClient
+from .langchain_memory import HipCortexMemory, AsyncHipCortexMemory
+from .llamaindex_storage import HipCortexStorageContext
+
+__version__ = "0.5.0"
+__all__ = [
+    "HipCortexClient",
+    "AsyncHipCortexClient",
+    "HipCortexMemory",
+    "AsyncHipCortexMemory",
+    "HipCortexStorageContext",
+]

hipcortex-0.5.0/hipcortex/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Framework adapters for HipCortex — shared factories, CrewAI, AutoGen."""
+
+from .common import (
+    bootstrap_live_beliefs,
+    client_from_settings,
+    default_session_id,
+)
+
+__all__ = [
+    "bootstrap_live_beliefs",
+    "client_from_settings",
+    "default_session_id",
+]

{hipcortex-0.3.2 → hipcortex-0.5.0}/hipcortex/adapters/autogen.py

@@ -1,156 +1,175 @@
-"""HipCortex AutoGen adapter — targets AutoGen 0.4+ (autogen-agentchat >= 0.4).
-
-AutoGen 0.4 changed from register_hook() to the Memory protocol.
-
-Usage (AutoGen 0.4+):
-    from autogen_agentchat.agents import AssistantAgent
-    from hipcortex import HipCortexClient
-    from hipcortex.adapters.autogen import HipCortexAutoGenMemory
-
-    client = HipCortexClient(base_url="http://localhost:3030")
-    memory = HipCortexAutoGenMemory(client=client, agent_id="researcher")
-    agent = AssistantAgent(name="researcher", model_client=..., memory=[memory])
-
-Usage (AutoGen 0.3 — legacy):
-    agent.register_hook("process_message_before_send", memory.on_message_sent_v03)
-    agent.register_hook("process_all_messages_before_reply", memory.on_messages_received_v03)
-"""
-
-from __future__ import annotations
-
-from typing import Any, Dict, List, Optional
-
-from ..client import HipCortexClient
-
-try:
-    from autogen_core.memory import Memory, MemoryContent, MemoryMimeType, MemoryQueryResult
-    from autogen_core import CancellationToken
-    _AUTOGEN4_AVAILABLE = True
-except ImportError:
-    _AUTOGEN4_AVAILABLE = False
-    class Memory:  # type: ignore[no-redef]
-        pass
-    class CancellationToken:  # type: ignore[no-redef]
-        pass
-
-
-class HipCortexAutoGenMemory(Memory):  # type: ignore[misc]
-    """AutoGen 0.4 Memory protocol backed by HipCortex."""
-
-    def __init__(
-        self,
-        client: HipCortexClient,
-        agent_id: str = "autogen-agent",
-        top_k: int = 10,
-    ) -> None:
-        self._client = client
-        self._agent_id = agent_id
-        self._top_k = top_k
-
-    # AutoGen 0.4 Memory protocol -------------------------------------------
-
-    async def add(
-        self,
-        content: Any,
-        cancellation_token: Optional[CancellationToken] = None,
-    ) -> None:
-        if _AUTOGEN4_AVAILABLE and hasattr(content, "content"):
-            text = str(content.content)
-            role = getattr(content, "role", None)
-            mime = getattr(content, "mime_type", None)
-            action = "ai_message" if (
-                (role and role in ("assistant", "ai")) or
-                (mime and "assistant" in str(mime).lower())
-            ) else "observation"
-        else:
-            text = str(content)
-            action = "observation"
-        self._client.add_memory(
-            actor=self._agent_id, action=action,
-            target=text, record_type="Temporal",
-        )
-
-    async def query(
-        self,
-        query: Any,
-        cancellation_token: Optional[CancellationToken] = None,
-    ) -> Any:
-        query_text = str(getattr(query, "content", query))
-        try:
-            search_results = self._client.search(query=query_text, limit=self._top_k)
-        except Exception:
-            search_results = [
-                {"record": r, "score": 1.0}
-                for r in self._client.get_conversation_history(self._agent_id, limit=self._top_k)
-            ]
-        if not _AUTOGEN4_AVAILABLE:
-            return search_results
-        memories = []
-        for item in search_results:
-            rec = item.get("record", item)
-            memories.append(MemoryContent(
-                content=rec.get("target", ""),
-                mime_type=MemoryMimeType.TEXT,
-                metadata={"score": item.get("score", 1.0), "actor": rec.get("actor", ""),
-                          "action": rec.get("action", ""), "timestamp": rec.get("timestamp", "")},
-            ))
-        return MemoryQueryResult(results=memories)
-
-    async def update_context(
-        self,
-        model_context: Any,
-        cancellation_token: Optional[CancellationToken] = None,
-    ) -> Any:
-        records = self._client.get_conversation_history(self._agent_id, limit=self._top_k)
-        records.sort(key=lambda r: r.get("timestamp", ""))
-        if not records:
-            return {"memories_added": 0}
-        lines = [f"[{r.get('action','memory')}] {r.get('target','')}" for r in records]
-        system_msg = {"role": "system", "content": "[HipCortex memory]\n" + "\n".join(lines)}
-        if hasattr(model_context, "add_message"):
-            await model_context.add_message(system_msg)
-        elif hasattr(model_context, "messages"):
-            model_context.messages.insert(0, system_msg)
-        return {"memories_added": len(records)}
-
-    async def clear(self) -> None:
-        self._client.forget(self._agent_id)
-
-    # AutoGen 0.3 legacy hooks -----------------------------------------------
-
-    def on_message_sent_v03(self, message: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]:
-        """AutoGen 0.3 hook: process_message_before_send."""
-        content = message.get("content", "")
-        role = message.get("role", "assistant")
-        action = "ai_message" if role == "assistant" else "human_message"
-        self._client.add_memory(actor=self._agent_id, action=action, target=str(content),
-                                record_type="Reflexion" if role == "assistant" else "Temporal")
-        return message
-
-    def on_messages_received_v03(
-        self, messages: List[Dict[str, Any]], **kwargs: Any
-    ) -> List[Dict[str, Any]]:
-        """AutoGen 0.3 hook: process_all_messages_before_reply."""
-        history = self._client.get_conversation_history(self._agent_id, limit=20)
-        if not history:
-            return messages
-        history.sort(key=lambda r: r.get("timestamp", ""))
-        lines = [
-            f"{'AI' if r.get('action') == 'ai_message' else 'Human'}: {r.get('target','')}"
-            for r in history
-        ]
-        return [{"role": "system", "content": "[HipCortex memory]\n" + "\n".join(lines)}] + list(messages)
-
-    # Sync helpers (no AutoGen needed) ---------------------------------------
-
-    def store(self, content: str, action: str = "observation") -> Dict[str, Any]:
-        return self._client.add_memory(actor=self._agent_id, action=action,
-                                       target=content, record_type="Temporal")
-
-    def recall(self, limit: int = 20) -> str:
-        records = self._client.get_conversation_history(self._agent_id, limit=limit)
-        records.sort(key=lambda r: r.get("timestamp", ""))
-        return "\n".join(f"[{r.get('action','?')}] {r.get('target','')}" for r in records)
-
-    def forget_all(self) -> Dict[str, Any]:
-        return self._client.forget(self._agent_id)
+"""HipCortex AutoGen adapter — targets AutoGen 0.4+ (autogen-agentchat >= 0.4).
+
+AutoGen 0.4 changed from register_hook() to the Memory protocol.
+
+Usage (AutoGen 0.4+):
+    from autogen_agentchat.agents import AssistantAgent
+    from hipcortex.adapters.autogen import HipCortexAutoGenMemory
+
+    memory = HipCortexAutoGenMemory.from_settings()  # config URL + default actor
+    agent = AssistantAgent(name="researcher", model_client=..., memory=[memory])
+
+Usage (AutoGen 0.3 — legacy):
+    agent.register_hook("process_message_before_send", memory.on_message_sent_v03)
+    agent.register_hook("process_all_messages_before_reply", memory.on_messages_received_v03)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..client import HipCortexClient
+
+try:
+    from autogen_core.memory import Memory, MemoryContent, MemoryMimeType, MemoryQueryResult
+    from autogen_core import CancellationToken
+    _AUTOGEN4_AVAILABLE = True
+except ImportError:
+    _AUTOGEN4_AVAILABLE = False
+    class Memory:  # type: ignore[no-redef]
+        pass
+    class CancellationToken:  # type: ignore[no-redef]
+        pass
+
+
+class HipCortexAutoGenMemory(Memory):  # type: ignore[misc]
+    """AutoGen 0.4 Memory protocol backed by HipCortex."""
+
+    def __init__(
+        self,
+        client: HipCortexClient,
+        agent_id: str = "autogen-agent",
+        top_k: int = 10,
+    ) -> None:
+        self._client = client
+        self._agent_id = agent_id
+        self._top_k = top_k
+
+    @classmethod
+    def from_settings(
+        cls,
+        agent_id: Optional[str] = None,
+        top_k: int = 10,
+        **kw: Any,
+    ) -> "HipCortexAutoGenMemory":
+        """Build memory from project/user config (URL + default actor).
+
+        Args:
+            agent_id: Actor scope; defaults to :func:`default_session_id`.
+            top_k: Max results for query/update_context.
+            **kw: Optional ``client`` override and unused extras ignored.
+        """
+        from .common import client_from_settings, default_session_id
+
+        client = kw.pop("client", None) or client_from_settings()
+        if agent_id is None:
+            agent_id = default_session_id()
+        return cls(client=client, agent_id=agent_id, top_k=top_k)
+
+    # AutoGen 0.4 Memory protocol -------------------------------------------
+
+    async def add(
+        self,
+        content: Any,
+        cancellation_token: Optional[CancellationToken] = None,
+    ) -> None:
+        if _AUTOGEN4_AVAILABLE and hasattr(content, "content"):
+            text = str(content.content)
+            role = getattr(content, "role", None)
+            mime = getattr(content, "mime_type", None)
+            action = "ai_message" if (
+                (role and role in ("assistant", "ai")) or
+                (mime and "assistant" in str(mime).lower())
+            ) else "observation"
+        else:
+            text = str(content)
+            action = "observation"
+        self._client.add_memory(
+            actor=self._agent_id, action=action,
+            target=text, record_type="Temporal",
+        )
+
+    async def query(
+        self,
+        query: Any,
+        cancellation_token: Optional[CancellationToken] = None,
+    ) -> Any:
+        query_text = str(getattr(query, "content", query))
+        try:
+            search_results = self._client.search(query=query_text, limit=self._top_k)
+        except Exception:
+            search_results = [
+                {"record": r, "score": 1.0}
+                for r in self._client.get_conversation_history(self._agent_id, limit=self._top_k)
+            ]
+        if not _AUTOGEN4_AVAILABLE:
+            return search_results
+        memories = []
+        for item in search_results:
+            rec = item.get("record", item)
+            memories.append(MemoryContent(
+                content=rec.get("target", ""),
+                mime_type=MemoryMimeType.TEXT,
+                metadata={"score": item.get("score", 1.0), "actor": rec.get("actor", ""),
+                          "action": rec.get("action", ""), "timestamp": rec.get("timestamp", "")},
+            ))
+        return MemoryQueryResult(results=memories)
+
+    async def update_context(
+        self,
+        model_context: Any,
+        cancellation_token: Optional[CancellationToken] = None,
+    ) -> Any:
+        records = self._client.get_conversation_history(self._agent_id, limit=self._top_k)
+        records.sort(key=lambda r: r.get("timestamp", ""))
+        if not records:
+            return {"memories_added": 0}
+        lines = [f"[{r.get('action','memory')}] {r.get('target','')}" for r in records]
+        system_msg = {"role": "system", "content": "[HipCortex memory]\n" + "\n".join(lines)}
+        if hasattr(model_context, "add_message"):
+            await model_context.add_message(system_msg)
+        elif hasattr(model_context, "messages"):
+            model_context.messages.insert(0, system_msg)
+        return {"memories_added": len(records)}
+
+    async def clear(self) -> None:
+        self._client.forget(self._agent_id)
+
+    # AutoGen 0.3 legacy hooks -----------------------------------------------
+
+    def on_message_sent_v03(self, message: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]:
+        """AutoGen 0.3 hook: process_message_before_send."""
+        content = message.get("content", "")
+        role = message.get("role", "assistant")
+        action = "ai_message" if role == "assistant" else "human_message"
+        self._client.add_memory(actor=self._agent_id, action=action, target=str(content),
+                                record_type="Reflexion" if role == "assistant" else "Temporal")
+        return message
+
+    def on_messages_received_v03(
+        self, messages: List[Dict[str, Any]], **kwargs: Any
+    ) -> List[Dict[str, Any]]:
+        """AutoGen 0.3 hook: process_all_messages_before_reply."""
+        history = self._client.get_conversation_history(self._agent_id, limit=20)
+        if not history:
+            return messages
+        history.sort(key=lambda r: r.get("timestamp", ""))
+        lines = [
+            f"{'AI' if r.get('action') == 'ai_message' else 'Human'}: {r.get('target','')}"
+            for r in history
+        ]
+        return [{"role": "system", "content": "[HipCortex memory]\n" + "\n".join(lines)}] + list(messages)
+
+    # Sync helpers (no AutoGen needed) ---------------------------------------
+
+    def store(self, content: str, action: str = "observation") -> Dict[str, Any]:
+        return self._client.add_memory(actor=self._agent_id, action=action,
+                                       target=content, record_type="Temporal")
+
+    def recall(self, limit: int = 20) -> str:
+        records = self._client.get_conversation_history(self._agent_id, limit=limit)
+        records.sort(key=lambda r: r.get("timestamp", ""))
+        return "\n".join(f"[{r.get('action','?')}] {r.get('target','')}" for r in records)
+
+    def forget_all(self) -> Dict[str, Any]:
+        return self._client.forget(self._agent_id)