hebbrix 2.0.0__py3-none-any.whl

hebbrix/__init__.py

@@ -0,0 +1,69 @@
+"""
+Hebbrix Python SDK - Advanced Memory API for AI Agents
+
+A modern, async-first Python SDK for the Hebbrix Memory API.
+The only memory API with Reinforcement Learning for AI agents.
+
+Quick Start:
+
+    from hebbrix import MemoryClient, MemoryChat
+
+    # Option 1: Simple 3-line chat integration
+    chat = MemoryChat(api_key="hbx_...")
+    response = chat.send("Remember I love Python!", "user_123")
+    response = chat.send("What language do I like?", "user_123")
+
+    # Option 2: Full async API client
+    async with MemoryClient(api_key="hbx_...") as client:
+        # Create collection
+        collection = await client.collections.create(name="My Agent")
+
+        # Store memory
+        memory = await client.memories.create(
+            collection_id=collection["id"],
+            content="Important information"
+        )
+
+        # Search with hybrid vector + BM25 + graph
+        results = await client.search(query="What was important?", limit=5)
+
+        # AI-powered reasoning over memories
+        answer = await client.reason(query="Explain what I learned")
+
+Features:
+- ✅ Reinforcement Learning for memory optimization
+- ✅ Temporal Knowledge Graphs with bi-temporal model
+- ✅ Procedural Memory (skills and learned behaviors)
+- ✅ Working Memory (short-term context buffer)
+- ✅ Memory Consolidation (automatic compression)
+- ✅ 6-layer Hybrid Search (Vector + BM25 + KG + Decay + AI + RL)
+- ✅ Complete async/await support
+- ✅ Type hints throughout
+"""
+
+__version__ = "2.0.0"
+__author__ = "Hebbrix Team"
+__license__ = "MIT"
+
+from hebbrix.client import MemoryClient
+from hebbrix.chat import MemoryChat
+from hebbrix.exceptions import (
+    HebbrixError,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+
+__all__ = [
+    "MemoryClient",
+    "MemoryChat",
+    "HebbrixError",
+    "AuthenticationError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]

hebbrix/chat.py

@@ -0,0 +1,349 @@
+"""
+Hebbrix Chat Wrapper - 3-Line Integration
+
+The easiest way to add memory-powered conversations to your application.
+
+Example:
+    from hebbrix import MemoryChat
+
+    chat = MemoryChat(api_key="mem_sk_...")
+    response = chat.send("What's my favorite food?", session_id="user_123")
+"""
+from typing import Optional, Dict, Any, List
+import requests
+
+from hebbrix.client import MemoryClient
+
+
+class MemoryChat:
+    """
+    Simple chat interface with automatic memory integration.
+
+    This is the easiest way to use Hebbrix - just 3 lines of code!
+
+    Features:
+    - Automatic memory retrieval
+    - User profile injection
+    - Session management
+    - RL-powered personalization
+    - OpenAI-compatible responses
+
+    Example:
+        ```python
+        from hebbrix import MemoryChat
+
+        # Line 1: Initialize
+        chat = MemoryChat(api_key="mem_sk_...")
+
+        # Line 2: Send message
+        response = chat.send("Hi, remember that I love pizza?", "user_123")
+
+        # Line 3: Get response with memory
+        response = chat.send("What's my favorite food?", "user_123")
+        print(response)  # "Your favorite food is pizza!"
+        ```
+
+    Args:
+        api_key: Hebbrix API key
+        base_url: API base URL (default: https://api.hebbrix.com)
+        model: LLM model to use (default: gpt-4o-mini)
+        auto_memory: Enable automatic memory retrieval (default: True)
+        auto_profile: Enable user profile injection (default: True)
+        personalization: Enable RL-powered personalization (default: True)
+        learning: Enable RL trajectory logging (default: True)
+        prompt_strategy: Prompt template strategy (default: "default")
+        memory_limit: Max memories to retrieve per message (default: 10)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://localhost:8000",
+        model: str = "gpt-4o-mini",
+        auto_memory: bool = True,
+        auto_profile: bool = True,
+        personalization: bool = True,
+        learning: bool = True,
+        prompt_strategy: str = "default",
+        memory_limit: int = 10,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.prompt_strategy = prompt_strategy
+        self.memory_limit = memory_limit
+
+        # Feature configuration
+        self.features = {
+            "memory": auto_memory,
+            "user_profile": auto_profile,
+            "personalization": personalization,
+            "learning": learning,
+        }
+
+        # Also create full client for advanced operations
+        self.client = MemoryClient(api_key=api_key, base_url=base_url)
+
+    def send(
+        self,
+        message: str,
+        session_id: str,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+    ) -> str:
+        """
+        Send a message and get a response with automatic memory integration.
+
+        This is the main method - just call it and Hebbrix handles everything!
+
+        Args:
+            message: Your message
+            session_id: Session identifier (user ID or conversation ID)
+            temperature: Response randomness (0-2, default: 0.7)
+            max_tokens: Maximum response length (default: None)
+
+        Returns:
+            Assistant's response as a string
+
+        Example:
+            response = chat.send("What did I tell you earlier?", "user_123")
+        """
+        url = f"{self.base_url}/v1/chat/completions"
+
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": message}],
+            "session_id": session_id,
+            "features": self.features,
+            "prompt_strategy": self.prompt_strategy,
+            "memory_limit": self.memory_limit,
+            "temperature": temperature,
+        }
+
+        if max_tokens:
+            payload["max_tokens"] = max_tokens
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        response = requests.post(url, json=payload, headers=headers)
+        response.raise_for_status()
+
+        data = response.json()
+        return data["choices"][0]["message"]["content"]
+
+    def send_with_context(
+        self,
+        message: str,
+        session_id: str,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """
+        Send a message and get full response with memory context.
+
+        Use this when you want to see which memories were used.
+
+        Args:
+            message: Your message
+            session_id: Session identifier
+            temperature: Response randomness (0-2, default: 0.7)
+            max_tokens: Maximum response length (default: None)
+
+        Returns:
+            Full response dict with memory context
+
+        Example:
+            result = chat.send_with_context("What's my name?", "user_123")
+            print(result["message"])  # Assistant's response
+            print(result["memory_context"])  # Which memories were used
+        """
+        url = f"{self.base_url}/v1/chat/completions"
+
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": message}],
+            "session_id": session_id,
+            "features": self.features,
+            "prompt_strategy": self.prompt_strategy,
+            "memory_limit": self.memory_limit,
+            "temperature": temperature,
+        }
+
+        if max_tokens:
+            payload["max_tokens"] = max_tokens
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        response = requests.post(url, json=payload, headers=headers)
+        response.raise_for_status()
+
+        data = response.json()
+
+        return {
+            "message": data["choices"][0]["message"]["content"],
+            "memory_context": data["memory_context"],
+            "usage": data["usage"],
+            "model": data["model"],
+        }
+
+    def configure_features(
+        self,
+        auto_memory: Optional[bool] = None,
+        auto_profile: Optional[bool] = None,
+        personalization: Optional[bool] = None,
+        learning: Optional[bool] = None,
+    ) -> None:
+        """
+        Configure features on the fly.
+
+        Args:
+            auto_memory: Enable/disable automatic memory retrieval
+            auto_profile: Enable/disable user profile injection
+            personalization: Enable/disable RL personalization
+            learning: Enable/disable RL learning
+        """
+        if auto_memory is not None:
+            self.features["memory"] = auto_memory
+        if auto_profile is not None:
+            self.features["user_profile"] = auto_profile
+        if personalization is not None:
+            self.features["personalization"] = personalization
+        if learning is not None:
+            self.features["learning"] = learning
+
+    def set_model(self, model: str) -> None:
+        """
+        Change the LLM model.
+
+        Args:
+            model: Model name (e.g., "gpt-4o-mini", "claude-3-sonnet")
+        """
+        self.model = model
+
+    def set_strategy(self, strategy: str) -> None:
+        """
+        Change the prompt strategy.
+
+        Args:
+            strategy: Strategy name ("default", "concise", "detailed")
+        """
+        self.prompt_strategy = strategy
+
+    def list_sessions(self, active_only: bool = True) -> List[Dict[str, Any]]:
+        """
+        List all chat sessions.
+
+        Args:
+            active_only: Only return active sessions
+
+        Returns:
+            List of session dicts
+        """
+        url = f"{self.base_url}/v1/chat/sessions"
+        params = {"active_only": active_only}
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        response = requests.get(url, params=params, headers=headers)
+        response.raise_for_status()
+
+        return response.json()["sessions"]
+
+    def get_session_info(self, session_id: str) -> Dict[str, Any]:
+        """
+        Get information about a specific session.
+
+        Args:
+            session_id: Session identifier
+
+        Returns:
+            Session info and statistics
+        """
+        url = f"{self.base_url}/v1/chat/sessions/{session_id}"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        response = requests.get(url, headers=headers)
+        response.raise_for_status()
+
+        return response.json()
+
+    def delete_session(self, session_id: str) -> None:
+        """
+        Delete a chat session.
+
+        Args:
+            session_id: Session identifier
+        """
+        url = f"{self.base_url}/v1/chat/sessions/{session_id}"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        response = requests.delete(url, headers=headers)
+        response.raise_for_status()
+
+    # Convenience methods for memory operations
+    def add_memory(self, content: str, collection_id: str, importance: float = 0.5) -> Dict[str, Any]:
+        """
+        Add a memory manually.
+
+        Args:
+            content: Memory content
+            collection_id: Collection ID
+            importance: Memory importance (0-1)
+
+        Returns:
+            Created memory dict
+        """
+        return self.client.memories.create(
+            content=content,
+            collection_id=collection_id,
+            importance=importance,
+        )
+
+    def search_memories(self, query: str, collection_id: Optional[str] = None, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Search memories manually.
+
+        Args:
+            query: Search query
+            collection_id: Optional collection filter
+            limit: Number of results
+
+        Returns:
+            List of memory dicts
+        """
+        return self.client.memories.search(
+            query=query,
+            collection_id=collection_id,
+            limit=limit,
+        )["results"]
+
+
+# Convenience function for even simpler usage
+def quick_chat(api_key: str, message: str, session_id: str) -> str:
+    """
+    The absolute simplest way to use Hebbrix - single function call.
+
+    Args:
+        api_key: Hebbrix API key
+        message: Your message
+        session_id: Session identifier
+
+    Returns:
+        Assistant's response
+
+    Example:
+        from hebbrix.chat import quick_chat
+
+        response = quick_chat(
+            api_key="mem_sk_...",
+            message="What's my favorite color?",
+            session_id="user_123"
+        )
+    """
+    chat = MemoryChat(api_key=api_key)
+    return chat.send(message, session_id)

hebbrix/client.py

@@ -0,0 +1,226 @@
+"""
+Hebbrix Client
+
+Main client class for interacting with the Hebbrix api.
+"""
+from typing import Optional, Dict, Any, List
+import httpx
+
+from hebbrix.resources import (
+    AuthResource,
+    CollectionsResource,
+    MemoriesResource,
+    SearchResource,
+    RLResource,
+    ProceduralResource,
+    TemporalResource,
+    WorkingMemoryResource,
+    ConsolidationResource,
+    MemoryToolsResource,
+    WorldModelResource,
+)
+from hebbrix.exceptions import (
+    HebbrixError,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+
+class MemoryClient:
+    """
+    Hebbrix api client.
+
+    Args:
+        api_key: API key for authentication
+        base_url: Base URL of the API (default: https://api.hebbrix.com)
+        timeout: Request timeout in seconds (default: 30)
+
+    Example:
+        >>> client = MemoryClient(api_key="mem_sk_...")
+        >>> memory = await client.memories.create(
+        ...     collection_id="col_123",
+        ...     content="Important note"
+        ... )
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://memory-api.livelystone-78e9a45c.centralus.azurecontainerapps.io",
+        timeout: float = 120.0,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+        # HTTP client
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=self._get_headers(),
+        )
+
+        # Initialize resources
+        self.auth = AuthResource(self)
+        self.collections = CollectionsResource(self)
+        self.memories = MemoriesResource(self)
+        self.search_resource = SearchResource(self)
+        self.rl = RLResource(self)
+        self.procedural = ProceduralResource(self)
+        self.temporal = TemporalResource(self)
+        self.working_memory = WorkingMemoryResource(self)
+        self.consolidation = ConsolidationResource(self)
+        self.memory_tools = MemoryToolsResource(self)
+        self.world_model = WorldModelResource(self)
+
+    def _get_headers(self) -> Dict[str, str]:
+        """Get request headers."""
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "hebbrix-python/2.0.0",
+        }
+
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        return headers
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Handle error responses."""
+        status_code = response.status_code
+
+        try:
+            error_data = response.json()
+            message = error_data.get("error", {}).get("message", response.text)
+        except Exception:
+            message = response.text
+
+        if status_code == 401:
+            raise AuthenticationError(message)
+        elif status_code == 404:
+            raise NotFoundError(message)
+        elif status_code == 422:
+            errors = error_data.get("error", {}).get("details", [])
+            raise ValidationError(message, errors=errors)
+        elif status_code == 429:
+            raise RateLimitError(message)
+        elif status_code >= 500:
+            raise ServerError(message)
+        else:
+            raise HebbrixError(message, status_code=status_code)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Make an HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: API path
+            **kwargs: Additional arguments for httpx
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            HebbrixError: On API errors
+        """
+        url = f"{self.base_url}{path}"
+
+        response = await self._client.request(method, url, **kwargs)
+
+        if response.status_code >= 400:
+            self._handle_error(response)
+
+        return response.json() if response.text else {}
+
+    async def get(self, path: str, **kwargs) -> Dict[str, Any]:
+        """Make a GET request."""
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs) -> Dict[str, Any]:
+        """Make a POST request."""
+        return await self.request("POST", path, **kwargs)
+
+    async def patch(self, path: str, **kwargs) -> Dict[str, Any]:
+        """Make a PATCH request."""
+        return await self.request("PATCH", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs) -> Dict[str, Any]:
+        """Make a DELETE request."""
+        return await self.request("DELETE", path, **kwargs)
+
+    # Convenience methods
+    async def search(
+        self,
+        query: str,
+        collection_id: Optional[str] = None,
+        limit: int = 10,
+        search_type: str = "hybrid",
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Search memories.
+
+        Args:
+            query: Search query
+            collection_id: Optional collection filter
+            limit: Number of results
+            search_type: Type of search (hybrid, vector, bm25, graph)
+            filters: Additional filters
+
+        Returns:
+            List of search results
+        """
+        return await self.search_resource.search(
+            query=query,
+            collection_id=collection_id,
+            limit=limit,
+            search_type=search_type,
+            filters=filters or {},
+        )
+
+    async def reason(
+        self,
+        query: str,
+        collection_id: Optional[str] = None,
+        provider: Optional[str] = None,
+        include_steps: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Perform reasoning over memories.
+
+        Args:
+            query: Question or query
+            collection_id: Optional collection filter
+            provider: LLM provider (gemini, openai, anthropic)
+            include_steps: Include reasoning steps
+
+        Returns:
+            Reasoning result with answer and sources
+        """
+        return await self.search_resource.reason(
+            query=query,
+            collection_id=collection_id,
+            provider=provider,
+            include_steps=include_steps,
+        )
+
+    async def close(self):
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()

hebbrix/exceptions.py

@@ -0,0 +1,48 @@
+"""
+Hebbrix SDK Exceptions
+"""
+
+
+class HebbrixError(Exception):
+    """Base exception for Hebbrix SDK."""
+
+    def __init__(self, message: str, status_code: int = None):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(self.message)
+
+
+class AuthenticationError(HebbrixError):
+    """Raised when authentication fails."""
+
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(message, status_code=401)
+
+
+class ValidationError(HebbrixError):
+    """Raised when request validation fails."""
+
+    def __init__(self, message: str, errors: list = None):
+        self.errors = errors or []
+        super().__init__(message, status_code=422)
+
+
+class NotFoundError(HebbrixError):
+    """Raised when a resource is not found."""
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message, status_code=404)
+
+
+class RateLimitError(HebbrixError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded"):
+        super().__init__(message, status_code=429)
+
+
+class ServerError(HebbrixError):
+    """Raised when server returns 5xx error."""
+
+    def __init__(self, message: str = "Internal server error"):
+        super().__init__(message, status_code=500)