autogen-substrate-memory 0.1.0__py3-none-any.whl

autogen_substrate/__init__.py

@@ -0,0 +1,6 @@
+"""SUBSTRATE cognitive memory provider for Microsoft AutoGen agents."""
+
+from autogen_substrate.memory import SubstrateMemory
+
+__all__ = ["SubstrateMemory"]
+__version__ = "0.1.0"

autogen_substrate/client.py

@@ -0,0 +1,173 @@
+"""Lightweight async HTTP client for the SUBSTRATE MCP server.
+
+Sends JSON-RPC 2.0 requests over HTTPS with Bearer token authentication.
+All responses are validated and errors are surfaced as typed exceptions.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("autogen_substrate.client")
+
+DEFAULT_MCP_URL = "https://substrate.garmolabs.com/mcp-server/mcp"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+class SubstrateClientError(Exception):
+    """Base exception for SUBSTRATE client errors."""
+
+
+class SubstrateAuthError(SubstrateClientError):
+    """Raised when the API key is invalid or missing."""
+
+
+class SubstrateRPCError(SubstrateClientError):
+    """Raised when the MCP server returns a JSON-RPC error."""
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        self.code = code
+        self.rpc_message = message
+        self.data = data
+        super().__init__(f"JSON-RPC error {code}: {message}")
+
+
+@dataclass(frozen=True)
+class RPCResponse:
+    """Immutable wrapper around a successful JSON-RPC result."""
+
+    id: int | str | None
+    result: Any
+
+
+@dataclass(frozen=True)
+class SubstrateClientConfig:
+    """Immutable configuration for the SUBSTRATE MCP client."""
+
+    api_key: str
+    mcp_url: str = DEFAULT_MCP_URL
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+    extra_headers: dict[str, str] = field(default_factory=dict)
+
+
+class SubstrateClient:
+    """Async HTTP client for SUBSTRATE MCP JSON-RPC calls.
+
+    Usage::
+
+        config = SubstrateClientConfig(api_key="sk_sub_...")
+        async with SubstrateClient(config) as client:
+            result = await client.call_tool("memory_search", {"query": "hello"})
+    """
+
+    def __init__(self, config: SubstrateClientConfig) -> None:
+        if not config.api_key:
+            raise SubstrateAuthError("SUBSTRATE API key must not be empty")
+        self._config = config
+        self._request_id = 0
+        self._http: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> SubstrateClient:
+        self._http = httpx.AsyncClient(
+            base_url=self._config.mcp_url,
+            headers={
+                "Authorization": f"Bearer {self._config.api_key}",
+                "Content-Type": "application/json",
+                **self._config.extra_headers,
+            },
+            timeout=httpx.Timeout(self._config.timeout_seconds),
+        )
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    def _next_id(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+    async def _send_rpc(self, method: str, params: dict[str, Any] | None = None) -> RPCResponse:
+        """Send a JSON-RPC 2.0 request and return the parsed response."""
+        if self._http is None:
+            raise SubstrateClientError("Client not initialized. Use 'async with' context manager.")
+
+        request_id = self._next_id()
+        payload: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+        }
+        if params is not None:
+            payload["params"] = params
+
+        logger.debug("MCP request: method=%s id=%d", method, request_id)
+
+        try:
+            response = await self._http.post("", content=json.dumps(payload))
+        except httpx.TimeoutException as exc:
+            raise SubstrateClientError(f"Request timed out after {self._config.timeout_seconds}s") from exc
+        except httpx.HTTPError as exc:
+            raise SubstrateClientError(f"HTTP error: {exc}") from exc
+
+        if response.status_code == 401:
+            raise SubstrateAuthError("Invalid or expired API key")
+        if response.status_code == 429:
+            raise SubstrateClientError("Rate limit exceeded")
+        if response.status_code >= 400:
+            raise SubstrateClientError(
+                f"HTTP {response.status_code}: {response.text[:200]}"
+            )
+
+        try:
+            body = response.json()
+        except (json.JSONDecodeError, ValueError) as exc:
+            raise SubstrateClientError(f"Invalid JSON response: {response.text[:200]}") from exc
+
+        if "error" in body and body["error"] is not None:
+            err = body["error"]
+            raise SubstrateRPCError(
+                code=err.get("code", -32603),
+                message=err.get("message", "Unknown error"),
+                data=err.get("data"),
+            )
+
+        return RPCResponse(id=body.get("id"), result=body.get("result"))
+
+    async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None = None) -> Any:
+        """Call an MCP tool and return the result content.
+
+        Args:
+            tool_name: Name of the SUBSTRATE MCP tool (e.g. ``hybrid_search``).
+            arguments: Tool-specific arguments dict.
+
+        Returns:
+            The ``result`` field from the JSON-RPC response.
+
+        Raises:
+            SubstrateRPCError: If the server returns a JSON-RPC error.
+            SubstrateAuthError: If authentication fails.
+            SubstrateClientError: On network or protocol errors.
+        """
+        params: dict[str, Any] = {"name": tool_name}
+        if arguments:
+            params["arguments"] = arguments
+
+        rpc = await self._send_rpc("tools/call", params)
+        return rpc.result
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """List all available MCP tools for the authenticated tier."""
+        rpc = await self._send_rpc("tools/list")
+        result = rpc.result
+        if isinstance(result, dict) and "tools" in result:
+            return result["tools"]
+        if isinstance(result, list):
+            return result
+        return []

autogen_substrate/memory.py

@@ -0,0 +1,346 @@
+"""SUBSTRATE Memory provider for Microsoft AutoGen agents.
+
+Implements the ``autogen_core.memory.Memory`` protocol, backed by the
+SUBSTRATE cognitive entity framework. Queries combine hybrid search with
+emotional state awareness; context injection provides identity, emotion,
+and relevant memories as a system message.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+from autogen_core.memory import Memory, MemoryContent, MemoryMimeType, MemoryQueryResult
+from autogen_core.model_context import ChatCompletionContext
+from autogen_core.models import SystemMessage
+
+from autogen_substrate.client import (
+    SubstrateClient,
+    SubstrateClientConfig,
+    SubstrateClientError,
+    SubstrateRPCError,
+)
+
+logger = logging.getLogger("autogen_substrate.memory")
+
+
+def _extract_text(content: Any) -> str:
+    """Extract text from various MCP tool response shapes."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, dict):
+        # MCP content blocks: [{"type": "text", "text": "..."}]
+        if "content" in content and isinstance(content["content"], list):
+            parts = []
+            for block in content["content"]:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    parts.append(block.get("text", ""))
+            return "\n".join(parts)
+        # Direct text field
+        if "text" in content:
+            return str(content["text"])
+        return json.dumps(content, indent=2, default=str)
+    if isinstance(content, list):
+        parts = []
+        for item in content:
+            parts.append(_extract_text(item))
+        return "\n".join(parts)
+    return str(content)
+
+
+@dataclass(frozen=True)
+class SubstrateMemoryConfig:
+    """Immutable configuration for SubstrateMemory.
+
+    Attributes:
+        api_key: SUBSTRATE API key. Falls back to ``SUBSTRATE_API_KEY`` env var.
+        mcp_url: MCP server URL. Falls back to ``SUBSTRATE_MCP_URL`` env var.
+        name: Display name for this memory provider.
+        search_top_k: Default number of results for hybrid search.
+        include_emotion: Whether to include emotional state in queries and context.
+        include_identity: Whether to include identity verification in context.
+        include_values: Whether to include core values in context.
+        timeout_seconds: HTTP request timeout.
+    """
+
+    api_key: str = ""
+    mcp_url: str = ""
+    name: str = "substrate"
+    search_top_k: int = 5
+    include_emotion: bool = True
+    include_identity: bool = True
+    include_values: bool = True
+    timeout_seconds: float = 30.0
+
+
+class SubstrateMemory(Memory):
+    """SUBSTRATE-backed memory for AutoGen agents.
+
+    Provides cognitive memory, emotional state, identity verification, and
+    value-aligned context injection for AutoGen agent conversations.
+
+    Usage::
+
+        from autogen_substrate import SubstrateMemory
+
+        memory = SubstrateMemory(api_key="sk_sub_...")
+        await memory.add("User prefers concise responses")
+        result = await memory.query("What does the user prefer?")
+        print(result.results)
+
+    Or with full config::
+
+        from autogen_substrate.memory import SubstrateMemory, SubstrateMemoryConfig
+
+        config = SubstrateMemoryConfig(
+            api_key="sk_sub_...",
+            search_top_k=10,
+            include_emotion=True,
+        )
+        memory = SubstrateMemory(config=config)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str = "",
+        config: SubstrateMemoryConfig | None = None,
+    ) -> None:
+        resolved_config = config or SubstrateMemoryConfig(api_key=api_key)
+
+        resolved_key = (
+            resolved_config.api_key
+            or os.environ.get("SUBSTRATE_API_KEY", "")
+        )
+        resolved_url = (
+            resolved_config.mcp_url
+            or os.environ.get("SUBSTRATE_MCP_URL", "")
+            or "https://substrate.garmolabs.com/mcp-server/mcp"
+        )
+
+        self._config = SubstrateMemoryConfig(
+            api_key=resolved_key,
+            mcp_url=resolved_url,
+            name=resolved_config.name,
+            search_top_k=resolved_config.search_top_k,
+            include_emotion=resolved_config.include_emotion,
+            include_identity=resolved_config.include_identity,
+            include_values=resolved_config.include_values,
+            timeout_seconds=resolved_config.timeout_seconds,
+        )
+
+        self._client_config = SubstrateClientConfig(
+            api_key=self._config.api_key,
+            mcp_url=self._config.mcp_url,
+            timeout_seconds=self._config.timeout_seconds,
+        )
+
+    @property
+    def name(self) -> str:
+        """Display name for this memory provider."""
+        return self._config.name
+
+    async def query(
+        self,
+        query: str,
+        *,
+        cancellation_token: Any | None = None,
+        **kwargs: Any,
+    ) -> MemoryQueryResult:
+        """Query SUBSTRATE for relevant memories and emotional context.
+
+        Performs a hybrid search (semantic + keyword) across the entity's memory
+        and knowledge stores. Optionally includes the current emotional state
+        as additional context.
+
+        Args:
+            query: Natural language search query.
+            cancellation_token: Optional cancellation token (unused, kept for protocol).
+            **kwargs: Additional arguments. Supports ``top_k`` override.
+
+        Returns:
+            MemoryQueryResult with matching memory contents.
+        """
+        top_k = kwargs.get("top_k", self._config.search_top_k)
+        results: list[MemoryContent] = []
+
+        async with SubstrateClient(self._client_config) as client:
+            # Hybrid search for relevant memories
+            try:
+                search_result = await client.call_tool(
+                    "hybrid_search",
+                    {"query": query, "top_k": top_k},
+                )
+                search_text = _extract_text(search_result)
+                if search_text.strip():
+                    results.append(
+                        MemoryContent(
+                            content=search_text,
+                            mime_type=MemoryMimeType.TEXT,
+                            metadata={"source": "substrate_hybrid_search", "query": query},
+                        )
+                    )
+            except (SubstrateRPCError, SubstrateClientError) as exc:
+                logger.warning("hybrid_search failed, falling back to memory_search: %s", exc)
+                try:
+                    fallback = await client.call_tool("memory_search", {"query": query})
+                    fallback_text = _extract_text(fallback)
+                    if fallback_text.strip():
+                        results.append(
+                            MemoryContent(
+                                content=fallback_text,
+                                mime_type=MemoryMimeType.TEXT,
+                                metadata={"source": "substrate_memory_search", "query": query},
+                            )
+                        )
+                except (SubstrateRPCError, SubstrateClientError) as fallback_exc:
+                    logger.error("memory_search also failed: %s", fallback_exc)
+
+            # Include emotional state if configured
+            if self._config.include_emotion:
+                try:
+                    emotion_result = await client.call_tool("get_emotion_state")
+                    emotion_text = _extract_text(emotion_result)
+                    if emotion_text.strip():
+                        results.append(
+                            MemoryContent(
+                                content=f"[Emotional State]\n{emotion_text}",
+                                mime_type=MemoryMimeType.TEXT,
+                                metadata={"source": "substrate_emotion"},
+                            )
+                        )
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("get_emotion_state unavailable: %s", exc)
+
+        return MemoryQueryResult(results=results)
+
+    async def update_context(
+        self,
+        model_context: ChatCompletionContext,
+    ) -> None:
+        """Inject SUBSTRATE cognitive context into the agent's model context.
+
+        Prepends a system message containing the entity's identity status,
+        emotional state, core values, and any recent relevant memories.
+
+        Args:
+            model_context: The agent's current chat completion context.
+        """
+        sections: list[str] = []
+
+        async with SubstrateClient(self._client_config) as client:
+            # Identity verification
+            if self._config.include_identity:
+                try:
+                    identity = await client.call_tool("verify_identity")
+                    identity_text = _extract_text(identity)
+                    if identity_text.strip():
+                        sections.append(f"## Identity Continuity\n{identity_text}")
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("verify_identity unavailable: %s", exc)
+
+            # Emotional state
+            if self._config.include_emotion:
+                try:
+                    emotion = await client.call_tool("get_emotion_state")
+                    emotion_text = _extract_text(emotion)
+                    if emotion_text.strip():
+                        sections.append(f"## Emotional State\n{emotion_text}")
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("get_emotion_state unavailable: %s", exc)
+
+            # Core values
+            if self._config.include_values:
+                try:
+                    values = await client.call_tool("get_values")
+                    values_text = _extract_text(values)
+                    if values_text.strip():
+                        sections.append(f"## Core Values\n{values_text}")
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("get_values unavailable: %s", exc)
+
+            # Recent context from conversation messages
+            existing = await model_context.get_messages()
+            context_query = _build_context_query(existing)
+            if context_query:
+                try:
+                    memories = await client.call_tool(
+                        "hybrid_search",
+                        {"query": context_query, "top_k": 3},
+                    )
+                    mem_text = _extract_text(memories)
+                    if mem_text.strip():
+                        sections.append(f"## Relevant Memories\n{mem_text}")
+                except (SubstrateRPCError, SubstrateClientError) as exc:
+                    logger.debug("Context memory search unavailable: %s", exc)
+
+        if sections:
+            system_text = (
+                "# SUBSTRATE Cognitive Context\n\n"
+                + "\n\n".join(sections)
+            )
+            await model_context.add_message(SystemMessage(content=system_text))
+
+    async def add(
+        self,
+        content: str,
+        *,
+        cancellation_token: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Store a memory in SUBSTRATE via the respond tool.
+
+        Sends the content with a ``[memory-store]`` prefix so the entity
+        processes it as an explicit memory rather than conversational input.
+
+        Args:
+            content: The memory content to store.
+            cancellation_token: Optional cancellation token (unused).
+            **kwargs: Reserved for future use.
+        """
+        async with SubstrateClient(self._client_config) as client:
+            try:
+                await client.call_tool(
+                    "respond",
+                    {"message": f"[memory-store] {content}"},
+                )
+            except (SubstrateRPCError, SubstrateClientError) as exc:
+                logger.error("Failed to store memory: %s", exc)
+                raise
+
+    async def clear(self) -> None:
+        """No-op. SUBSTRATE manages its own memory lifecycle.
+
+        SUBSTRATE entities maintain causal memory with built-in consolidation
+        and decay. Explicit clearing is not supported to preserve identity
+        continuity.
+        """
+        logger.debug("clear() called — SUBSTRATE manages its own memory lifecycle")
+
+    async def close(self) -> None:
+        """No-op. Each operation creates its own HTTP connection.
+
+        The client uses context managers per-call, so there is no persistent
+        connection to close.
+        """
+        logger.debug("close() called — no persistent resources to release")
+
+
+def _build_context_query(messages: Sequence[Any]) -> str:
+    """Build a search query from the most recent user messages.
+
+    Extracts text from the last few messages to form a contextual query
+    for memory retrieval.
+    """
+    texts: list[str] = []
+    for msg in messages[-5:]:
+        content = getattr(msg, "content", None)
+        if isinstance(content, str) and content.strip():
+            texts.append(content.strip())
+    combined = " ".join(texts)
+    # Truncate to a reasonable query length
+    return combined[:500] if combined else ""

autogen_substrate_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: autogen-substrate-memory
+Version: 0.1.0
+Summary: SUBSTRATE cognitive memory provider for Microsoft AutoGen agents
+Project-URL: Homepage, https://garmolabs.com
+Project-URL: Documentation, https://garmolabs.com/substrate/docs
+Project-URL: Repository, https://github.com/GarmoLabs/autogen-substrate-memory
+Author-email: Garmo Labs <hello@garmolabs.com>
+License-Expression: MIT
+Keywords: ai-agents,autogen,cognitive,memory,substrate
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: autogen-agentchat>=0.4
+Requires-Dist: autogen-core>=0.4
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# autogen-substrate-memory
+
+SUBSTRATE cognitive memory provider for [Microsoft AutoGen](https://github.com/microsoft/autogen) agents.
+
+Give your AutoGen agents persistent identity, emotional awareness, and causal memory powered by the [SUBSTRATE](https://garmolabs.com) cognitive entity framework.
+
+## Installation
+
+```bash
+pip install autogen-substrate-memory
+```
+
+Or install from source:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from autogen_substrate import SubstrateMemory
+
+async def main():
+    # Create SUBSTRATE memory provider
+    memory = SubstrateMemory(api_key="sk_sub_your_key_here")
+
+    # Create an AutoGen agent with SUBSTRATE memory
+    agent = AssistantAgent(
+        name="kai",
+        model_client=OpenAIChatCompletionClient(model="gpt-4o"),
+        memory=[memory],
+    )
+
+    # The agent now has access to persistent cognitive memory,
+    # emotional state, and identity verification.
+    response = await agent.run(task="What do you remember about our last conversation?")
+    print(response)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `SUBSTRATE_API_KEY` | Your SUBSTRATE API key | (required) |
+| `SUBSTRATE_MCP_URL` | MCP server URL | `https://substrate.garmolabs.com/mcp-server/mcp` |
+
+### Full Configuration
+
+```python
+from autogen_substrate.memory import SubstrateMemory, SubstrateMemoryConfig
+
+config = SubstrateMemoryConfig(
+    api_key="sk_sub_...",
+    mcp_url="https://substrate.garmolabs.com/mcp-server/mcp",
+    search_top_k=10,          # Number of memory results per query
+    include_emotion=True,     # Include emotional state in queries
+    include_identity=True,    # Include identity verification in context
+    include_values=True,      # Include core values in context
+    timeout_seconds=30.0,     # HTTP request timeout
+)
+
+memory = SubstrateMemory(config=config)
+```
+
+## How It Works
+
+### Memory Protocol
+
+`SubstrateMemory` implements AutoGen's `Memory` protocol:
+
+| Method | Behavior |
+|---|---|
+| `query(query)` | Hybrid search (semantic + keyword) across entity memory. Optionally includes emotional state. |
+| `update_context(model_context)` | Injects identity, emotion, values, and relevant memories as a SystemMessage. |
+| `add(content)` | Stores content via the SUBSTRATE `respond` tool with a `[memory-store]` prefix. |
+| `clear()` | No-op. SUBSTRATE manages its own memory lifecycle with causal consolidation. |
+| `close()` | No-op. Each operation creates its own HTTP connection. |
+
+### SUBSTRATE MCP Tools Used
+
+| Tool | Used In | Purpose |
+|---|---|---|
+| `hybrid_search` | `query()`, `update_context()` | Semantic + keyword memory retrieval |
+| `memory_search` | `query()` (fallback) | Keyword-only memory retrieval |
+| `get_emotion_state` | `query()`, `update_context()` | Current affective state (valence, arousal, dominance) |
+| `verify_identity` | `update_context()` | Cryptographic identity continuity check |
+| `get_values` | `update_context()` | Core value architecture |
+| `respond` | `add()` | Store new memories via conversational input |
+
+## Get an API Key
+
+Sign up at [garmolabs.com](https://garmolabs.com) to get a SUBSTRATE API key.
+
+## License
+
+MIT

autogen_substrate_memory-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+autogen_substrate/__init__.py,sha256=Z8GhWwdJAxB8nzDxqDOalpXXSimzejSJGZC-i2mAdus,179
+autogen_substrate/client.py,sha256=5Fcy32-vLUmM4UG3mZL9HRwKa7GMDzl4wN7PN8qPKNo,5858
+autogen_substrate/memory.py,sha256=V0f1t24WDVYvm97eG6hhsstK6-hnDxBRt3wLXxpY_QI,13330
+autogen_substrate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+autogen_substrate_memory-0.1.0.dist-info/METADATA,sha256=cPNxxRm6_G329J2YLVa6AMHiHBxf4_9Kqr1nCX1p6TE,4756
+autogen_substrate_memory-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+autogen_substrate_memory-0.1.0.dist-info/RECORD,,

autogen_substrate_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any