hipcortex 0.2.0__py3-none-any.whl

hipcortex/__init__.py

@@ -0,0 +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/adapters/__init__.py

@@ -0,0 +1 @@
+"""Framework adapters for HipCortex — AutoGen and CrewAI."""

hipcortex/adapters/autogen.py

@@ -0,0 +1,156 @@
+"""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/adapters/crewai.py

@@ -0,0 +1,153 @@
+"""CrewAI tool adapter for HipCortex.
+
+Exposes HipCortex memory operations as CrewAI ``BaseTool`` subclasses
+so agents can store and retrieve memories as tool calls during task execution.
+
+Usage::
+
+    from crewai import Agent, Task, Crew
+    from hipcortex import HipCortexClient
+    from hipcortex.adapters.crewai import (
+        HipCortexRememberTool,
+        HipCortexRecallTool,
+        HipCortexForgetTool,
+    )
+
+    client = HipCortexClient(base_url="http://localhost:3000")
+    tools = [
+        HipCortexRememberTool(client=client, agent_id="researcher"),
+        HipCortexRecallTool(client=client, agent_id="researcher"),
+        HipCortexForgetTool(client=client, agent_id="researcher"),
+    ]
+
+    researcher = Agent(
+        role="Senior Researcher",
+        goal="Research and remember findings",
+        tools=tools,
+        ...
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from ..client import HipCortexClient
+
+try:
+    from crewai_tools import BaseTool
+    from pydantic import BaseModel, Field
+    _CREWAI_AVAILABLE = True
+except ImportError:
+    _CREWAI_AVAILABLE = False
+
+    class BaseModel:  # type: ignore[no-redef]
+        pass
+
+    class Field:  # type: ignore[no-redef]
+        def __init__(self, *a: Any, **kw: Any) -> None: ...
+
+    class BaseTool:  # type: ignore[no-redef]
+        name: str = ""
+        description: str = ""
+        args_schema: Any = None
+        def _run(self, *a: Any, **kw: Any) -> str: ...
+
+
+# ---------------------------------------------------------------------------
+# Input schemas
+# ---------------------------------------------------------------------------
+
+if _CREWAI_AVAILABLE:
+    class RememberInput(BaseModel):
+        content: str = Field(..., description="Observation or fact to remember.")
+        action: str = Field(default="observation", description="Action tag (e.g. 'finding', 'decision').")
+
+    class RecallInput(BaseModel):
+        limit: int = Field(default=20, description="Max number of memories to return.")
+
+    class ForgetInput(BaseModel):
+        confirm: bool = Field(default=False, description="Set to True to confirm deletion.")
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+class HipCortexRememberTool(BaseTool):  # type: ignore[misc]
+    """CrewAI tool: store an observation in HipCortex memory."""
+
+    name: str = "hipcortex_remember"
+    description: str = (
+        "Store an important observation, finding, or decision in persistent memory. "
+        "Use this whenever you discover information worth remembering for future tasks."
+    )
+    if _CREWAI_AVAILABLE:
+        args_schema: Type[BaseModel] = RememberInput
+
+    def __init__(self, client: HipCortexClient, agent_id: str = "crewai-agent") -> None:
+        super().__init__()
+        self._client = client
+        self._agent_id = agent_id
+
+    def _run(self, content: str, action: str = "observation") -> str:
+        result = self._client.add_memory(
+            actor=self._agent_id,
+            action=action,
+            target=content,
+            record_type="Temporal",
+        )
+        if result.get("success"):
+            return f"Stored memory with id={result.get('record_id', '?')}"
+        return f"Failed to store memory: {result.get('error', 'unknown error')}"
+
+
+class HipCortexRecallTool(BaseTool):  # type: ignore[misc]
+    """CrewAI tool: retrieve recent memories from HipCortex."""
+
+    name: str = "hipcortex_recall"
+    description: str = (
+        "Retrieve recent memories and observations stored in HipCortex. "
+        "Use this to recall past findings before starting a new research task."
+    )
+    if _CREWAI_AVAILABLE:
+        args_schema: Type[BaseModel] = RecallInput
+
+    def __init__(self, client: HipCortexClient, agent_id: str = "crewai-agent") -> None:
+        super().__init__()
+        self._client = client
+        self._agent_id = agent_id
+
+    def _run(self, limit: int = 20) -> str:
+        records = self._client.get_conversation_history(self._agent_id, limit=limit)
+        if not records:
+            return "No memories found."
+        records.sort(key=lambda r: r.get("timestamp", ""))
+        lines = []
+        for i, rec in enumerate(records, 1):
+            lines.append(f"{i}. [{rec.get('action', '?')}] {rec.get('target', '')}")
+        return "\n".join(lines)
+
+
+class HipCortexForgetTool(BaseTool):  # type: ignore[misc]
+    """CrewAI tool: delete all memories for this agent (GDPR / session reset)."""
+
+    name: str = "hipcortex_forget"
+    description: str = (
+        "Delete all memories stored for this agent. "
+        "Only use this when explicitly asked to clear memory or start fresh."
+    )
+    if _CREWAI_AVAILABLE:
+        args_schema: Type[BaseModel] = ForgetInput
+
+    def __init__(self, client: HipCortexClient, agent_id: str = "crewai-agent") -> None:
+        super().__init__()
+        self._client = client
+        self._agent_id = agent_id
+
+    def _run(self, confirm: bool = False) -> str:
+        if not confirm:
+            return "Deletion not confirmed. Pass confirm=True to proceed."
+        result = self._client.forget(self._agent_id)
+        deleted = result.get("records_deleted", 0)
+        return f"Deleted {deleted} memory records for agent '{self._agent_id}'."

hipcortex/async_client.py

@@ -0,0 +1,255 @@
+"""HipCortex async HTTP client — thin async wrapper around the REST API using httpx."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+
+class AsyncHipCortexClient:
+    """Asynchronous HTTP client for the HipCortex memory server.
+
+    Mirrors :class:`HipCortexClient` with coroutine-based methods powered by
+    ``httpx.AsyncClient``.  Compatible with FastAPI, Django async views,
+    LangChain 0.3+ async chains, and any asyncio / anyio event loop.
+
+    Args:
+        base_url: Root URL of the running hipcortex web-server binary.
+        timeout:  Per-request timeout in seconds.
+        api_key:  Optional Bearer token sent as ``Authorization: Bearer <key>``.
+
+    Usage::
+
+        # One-shot (opens and closes the underlying httpx.AsyncClient per call)
+        client = AsyncHipCortexClient()
+        result = await client.add_memory("alice", "said", "hello")
+
+        # Context-manager (recommended for sustained use)
+        async with AsyncHipCortexClient() as client:
+            result = await client.add_memory("alice", "said", "hello")
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:3030",
+        timeout: float = 10.0,
+        api_key: Optional[str] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._api_key = api_key
+        headers: Dict[str, str] = {}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._client = httpx.AsyncClient(headers=headers, timeout=timeout)
+
+    # ------------------------------------------------------------------
+    # Async context-manager support
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> "AsyncHipCortexClient":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying :class:`httpx.AsyncClient`."""
+        await self._client.aclose()
+
+    # ------------------------------------------------------------------
+    # Core memory operations
+    # ------------------------------------------------------------------
+
+    async def add_memory(
+        self,
+        actor: str,
+        action: str,
+        target: str,
+        record_type: str = "Temporal",
+        metadata: Optional[Dict[str, Any]] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Store a memory record.
+
+        Returns the server response dict with ``success`` and ``record_id``.
+        """
+        payload: Dict[str, Any] = {
+            "actor": actor,
+            "action": action,
+            "target": target,
+            "record_type": record_type,
+            "metadata": metadata or {},
+        }
+        if ttl_seconds is not None:
+            payload["ttl_seconds"] = ttl_seconds
+        resp = await self._client.post(f"{self.base_url}/memory/add", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def query_memory(
+        self,
+        actor: Optional[str] = None,
+        action: Optional[str] = None,
+        record_type: Optional[str] = None,
+        limit: int = 100,
+    ) -> List[Dict[str, Any]]:
+        """Query memory records. Returns a list of record dicts."""
+        params: Dict[str, Any] = {"limit": limit}
+        if actor is not None:
+            params["actor"] = actor
+        if action is not None:
+            params["action"] = action
+        if record_type is not None:
+            params["record_type"] = record_type
+        resp = await self._client.get(f"{self.base_url}/memory/query", params=params)
+        resp.raise_for_status()
+        return resp.json().get("records", [])
+
+    async def search(
+        self,
+        query: str,
+        embedding: Optional[List[float]] = None,
+        limit: int = 10,
+    ) -> List[Dict[str, Any]]:
+        """Semantic + keyword search over stored memory records.
+
+        If ``embedding`` is provided, ranks results by cosine similarity
+        against records that carry a ``metadata.embedding`` float array.
+        Falls back to keyword matching when embeddings are absent.
+
+        Returns a list of ``{"score": float, "record": {...}}`` dicts,
+        sorted by descending score.
+        """
+        payload: Dict[str, Any] = {"query": query, "limit": limit}
+        if embedding is not None:
+            payload["embedding"] = embedding
+        resp = await self._client.post(f"{self.base_url}/memory/search", json=payload)
+        resp.raise_for_status()
+        return resp.json().get("results", [])
+
+    async def bulk_add(self, records: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Bulk-insert multiple memory records in a single request.
+
+        Args:
+            records: List of record dicts, each with at minimum
+                     ``actor``, ``action``, and ``target`` keys.
+
+        Returns the server response with ``inserted`` count and any errors.
+        """
+        resp = await self._client.post(
+            f"{self.base_url}/memory/bulk", json={"records": records}
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def embed_and_add(
+        self,
+        actor: str,
+        action: str,
+        target: str,
+        embedding_model: str,
+        record_type: str = "Temporal",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Store a memory record and generate an embedding server-side.
+
+        The server calls the specified ``embedding_model`` (e.g. an Ollama
+        or OpenAI model) and attaches the resulting vector to the record.
+
+        Returns the server response dict with ``success`` and ``record_id``.
+        """
+        payload: Dict[str, Any] = {
+            "actor": actor,
+            "action": action,
+            "target": target,
+            "record_type": record_type,
+            "embedding_model": embedding_model,
+            "metadata": metadata or {},
+        }
+        resp = await self._client.post(f"{self.base_url}/memory/embed", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def forget(self, actor: str) -> Dict[str, Any]:
+        """GDPR right-to-forget: delete all records for ``actor``.
+
+        Returns ``{"success": bool, "records_deleted": int, "symbolic_nodes_deleted": int}``.
+        """
+        resp = await self._client.delete(
+            f"{self.base_url}/memory/forget/{actor}"
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # System
+    # ------------------------------------------------------------------
+
+    async def health(self) -> bool:
+        """Return True if the server is reachable and healthy."""
+        try:
+            resp = await self._client.get(f"{self.base_url}/health")
+            return resp.status_code == 200
+        except httpx.RequestError:
+            return False
+
+    async def stats(self) -> Dict[str, Any]:
+        """Return live server statistics: record counts, type breakdown, metering state."""
+        resp = await self._client.get(f"{self.base_url}/stats")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def coherence_status(self) -> Dict[str, Any]:
+        """Return the current coherence metrics from the server."""
+        resp = await self._client.get(f"{self.base_url}/coherence/status")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def graph(self) -> Dict[str, Any]:
+        """Return the full symbolic graph (nodes + edges)."""
+        resp = await self._client.get(f"{self.base_url}/graph")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_node(self, node_id: str) -> Optional[Dict[str, Any]]:
+        """Fetch a single symbolic node by UUID."""
+        resp = await self._client.get(f"{self.base_url}/node/{node_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Convenience helpers used by framework adapters
+    # ------------------------------------------------------------------
+
+    async def add_human_message(self, session_id: str, content: str) -> Dict[str, Any]:
+        """Record a human turn in a conversation session."""
+        return await self.add_memory(
+            actor=session_id,
+            action="human_message",
+            target=content,
+            record_type="Temporal",
+        )
+
+    async def add_ai_message(self, session_id: str, content: str) -> Dict[str, Any]:
+        """Record an AI turn in a conversation session."""
+        return await self.add_memory(
+            actor=session_id,
+            action="ai_message",
+            target=content,
+            record_type="Reflexion",
+        )
+
+    async def get_conversation_history(
+        self, session_id: str, limit: int = 50
+    ) -> List[Dict[str, Any]]:
+        """Retrieve the message history for a conversation session."""
+        return await self.query_memory(actor=session_id, limit=limit)
+
+    async def ping_latency_ms(self) -> float:
+        """Return round-trip latency to /health in milliseconds."""
+        t0 = time.perf_counter()
+        await self.health()
+        return (time.perf_counter() - t0) * 1000