sovant 1.0.7__py3-none-any.whl → 1.2.0__py3-none-any.whl

sovant/__init__.py

@@ -1,4 +1,4 @@
 from .client import Sovant, SovantError
 from .models import MemoryCreate, MemoryResult, SearchQuery
 
-__version__ = "1.0.7"
+__version__ = "0.1.0"

sovant/client.py

@@ -1,7 +1,8 @@
 import os
 import json
+import time
 import httpx
-from typing import Any, Dict
+from typing import Any, Dict, Optional, Callable
 from .models import MemoryCreate, SearchQuery
 
 class SovantError(Exception):
@@ -12,12 +13,27 @@ class SovantError(Exception):
         self.details = details
 
 class Sovant:
-    def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: float = 30.0):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        on_request: Optional[Callable[[Dict[str, Any]], None]] = None,
+        on_response: Optional[Callable[[Dict[str, Any]], None]] = None,
+        on_error: Optional[Callable[[SovantError], None]] = None
+    ):
         self.api_key = api_key or os.getenv("SOVANT_API_KEY")
         if not self.api_key:
             raise ValueError("Missing api_key")
         self.base_url = (base_url or os.getenv("SOVANT_BASE_URL") or "https://sovant.ai").rstrip("/")
         self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.on_request = on_request
+        self.on_response = on_response
+        self.on_error = on_error
         self._client = httpx.Client(
             timeout=self.timeout,
             headers={
@@ -26,38 +42,107 @@ class Sovant:
             }
         )
 
-    def _handle(self, r: httpx.Response):
-        if r.status_code >= 400:
+    def _request(self, method: str, url: str, **kwargs):
+        """Internal request method with retry logic and telemetry"""
+        start_time = time.time()
+
+        # Telemetry: onRequest hook
+        if self.on_request:
+            try:
+                self.on_request({
+                    "method": method,
+                    "url": url,
+                    "body": kwargs.get("json") or kwargs.get("content")
+                })
+            except:
+                pass
+
+        last_error = None
+
+        for attempt in range(self.max_retries + 1):
             try:
-                body = r.json()
-            except Exception:
-                body = {"message": r.text}
-            msg = body.get("message") or r.reason_phrase
-            code = body.get("code") or f"HTTP_{r.status_code}"
-            raise SovantError(msg, code, r.status_code, body)
-        if not r.text:
-            return None
-        try:
-            return r.json()
-        except Exception:
-            return r.text
+                r = self._client.request(method, url, **kwargs)
+
+                if r.status_code >= 400:
+                    try:
+                        body = r.json()
+                    except Exception:
+                        body = {"message": r.text}
+                    msg = body.get("message") or str(r.reason_phrase) if hasattr(r, 'reason_phrase') else 'Error'
+                    code = body.get("code") or f"HTTP_{r.status_code}"
+                    error = SovantError(msg, code, r.status_code, body)
+
+                    # Retry on 429 (rate limit) or 5xx errors
+                    if attempt < self.max_retries and (r.status_code == 429 or r.status_code >= 500):
+                        last_error = error
+                        delay = self.retry_delay * (2 ** attempt)  # Exponential backoff
+                        time.sleep(delay)
+                        continue
+
+                    # Telemetry: onError hook
+                    if self.on_error:
+                        try:
+                            self.on_error(error)
+                        except:
+                            pass
+
+                    raise error
+
+                # Success - telemetry: onResponse hook
+                duration = (time.time() - start_time) * 1000  # Convert to ms
+                if self.on_response:
+                    try:
+                        self.on_response({
+                            "method": method,
+                            "url": url,
+                            "status": r.status_code,
+                            "duration": duration
+                        })
+                    except:
+                        pass
+
+                if not r.text:
+                    return None
+                try:
+                    return r.json()
+                except Exception:
+                    return r.text
+
+            except httpx.TimeoutException as e:
+                error = SovantError("Request timeout", "TIMEOUT", 408)
+                if attempt < self.max_retries:
+                    last_error = error
+                    delay = self.retry_delay * (2 ** attempt)
+                    time.sleep(delay)
+                    continue
+                raise error
+
+            except httpx.NetworkError as e:
+                error = SovantError(str(e), "NETWORK_ERROR", 0)
+                if attempt < self.max_retries:
+                    last_error = error
+                    delay = self.retry_delay * (2 ** attempt)
+                    time.sleep(delay)
+                    continue
+                raise error
+
+        # If we exhausted retries, raise the last error
+        raise last_error or SovantError("Max retries exceeded", "MAX_RETRIES", 0)
 
     def memory_create(self, create: MemoryCreate):
         # Convert data field to content field for API
         body = create.model_dump()
         if 'data' in body:
             body['content'] = json.dumps(body.pop('data')) if not isinstance(body.get('data'), str) else body.pop('data')
-        
+
         # Ensure type has a default
         if 'type' not in body or body['type'] is None:
             body['type'] = 'journal'
-            
-        r = self._client.post(f"{self.base_url}/api/v1/memory", content=json.dumps(body))
-        return self._handle(r)
+
+        return self._request("POST", f"{self.base_url}/api/v1/memory", json=body)
 
     def memory_get(self, id: str):
-        r = self._client.get(f"{self.base_url}/api/v1/memories/{id}")
-        return self._handle(r)
+        return self._request("GET", f"{self.base_url}/api/v1/memories/{id}")
 
     def memory_search(self, q: SearchQuery):
         params = {}
@@ -75,16 +160,61 @@ class Sovant:
             params['from_date'] = q.from_date
         if q.to_date:
             params['to_date'] = q.to_date
-        r = self._client.get(f"{self.base_url}/api/v1/memory/search", params=params)
-        return self._handle(r)
+        return self._request("GET", f"{self.base_url}/api/v1/memory/search", params=params)
+
+    def memory_recall(self, query: str, thread_id: str | None = None, limit: int | None = None):
+        """
+        Hybrid recall with profile awareness
+
+        Uses multi-stage pipeline (profile fast-path + lexical + semantic)
+        Guarantees profile facts (name/age/location) when available
+
+        Use recall() for conversational queries ("who am I?", "what do you know about me?")
+        Use memory_search() for pure semantic topic lookup
+
+        Args:
+            query: The search query (required)
+            thread_id: Optional thread context for thread-scoped recall
+            limit: Maximum results to return (default 8, max 50)
+        """
+        params = {'query': query}
+        if thread_id:
+            params['thread_id'] = thread_id
+        if limit:
+            params['limit'] = str(limit)
+        return self._request("GET", f"{self.base_url}/api/v1/memory/recall", params=params)
 
     def memory_update(self, id: str, patch: Dict[str, Any]):
         # Convert data field to content field if present
         if 'data' in patch:
             patch['content'] = json.dumps(patch.pop('data')) if not isinstance(patch.get('data'), str) else patch.pop('data')
-        r = self._client.patch(f"{self.base_url}/api/v1/memories/{id}", content=json.dumps(patch))
-        return self._handle(r)
+        return self._request("PATCH", f"{self.base_url}/api/v1/memories/{id}", json=patch)
 
     def memory_delete(self, id: str):
-        r = self._client.delete(f"{self.base_url}/api/v1/memories/{id}")
-        return self._handle(r)
+        return self._request("DELETE", f"{self.base_url}/api/v1/memories/{id}")
+
+    def memory_create_batch(self, memories: list[Dict[str, Any]]):
+        """
+        Batch create multiple memories in a single request
+
+        Args:
+            memories: List of memory objects (max 100)
+
+        Returns:
+            BatchResponse with individual results
+        """
+        operations = []
+        for mem in memories:
+            data = mem.copy()
+            # Convert data field to content field
+            if 'data' in data:
+                data['content'] = json.dumps(data.pop('data')) if not isinstance(data.get('data'), str) else data.pop('data')
+            # Ensure type has default
+            if 'type' not in data or data['type'] is None:
+                data['type'] = 'journal'
+            operations.append({
+                "operation": "create",
+                "data": data
+            })
+
+        return self._request("POST", f"{self.base_url}/api/v1/memory/batch", json=operations)

{sovant-1.0.7.dist-info → sovant-1.2.0.dist-info}/METADATA

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: sovant
-Version: 1.0.7
+Version: 1.2.0
 Summary: Sovant Memory-as-a-Service Python SDK
 Author: Sovant
 License: MIT
+Project-URL: Documentation, https://sovant.ai/docs
+Project-URL: Source, https://github.com/hechin91/sovant-ai
+Project-URL: Tracker, https://github.com/hechin91/sovant-ai/issues
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -13,7 +16,8 @@ Dynamic: license-file
 
 # Sovant Python SDK
 
-Sovant is Memory-as-a-Service: a durable, queryable memory layer for AI apps with cross-model recall, hybrid (semantic + deterministic) retrieval, and simple SDKs.
+**Sovant is a governed AI memory layer for AI agents and applications.**
+Use it to store, search, and recall memories with profile awareness and enterprise-grade control over how memory is captured and used.
 
 [![PyPI version](https://img.shields.io/pypi/v/sovant.svg)](https://pypi.org/project/sovant/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -54,6 +58,32 @@ updated = client.memory.update(mem["id"], {
 client.memory.delete(mem["id"])
 ```
 
+## Recall vs Search
+
+Sovant provides two ways to query memories:
+
+- **`memory_recall()`** – Hybrid recall, profile-aware
+  Use for conversational queries: "What do you know about me?", "What happened on Project X?".
+  Uses Sovant's hybrid pipeline (profile fast-path + thread-scoped lexical + vector semantic search) and prioritizes profile facts (name/age/location) when available.
+
+- **`memory_search()`** – Semantic search
+  Use for topic lookup and discovery. Pure vector similarity search without profile logic.
+  Behavior unchanged from previous versions.
+
+```python
+# Recall for conversational queries
+context = client.memory_recall(
+    query="what do you know about me?",
+    limit=10
+)
+
+# Search for topic discovery
+topics = client.memory_search({
+    "query": "project updates",
+    "limit": 5
+})
+```
+
 ## Chat in 60 Seconds
 
 Stream real-time chat responses with memory context:
@@ -470,6 +500,13 @@ The API implements rate limiting. The SDK automatically handles rate limit respo
 
 See [CHANGELOG.md](./CHANGELOG.md) for a detailed history of changes.
 
+## License & Use
+
+- This SDK is MIT-licensed for integration convenience.
+- The Sovant API and platform are proprietary to Sovant Technologies Sdn. Bhd.
+- You may use this SDK to integrate with Sovant's hosted API.
+- Hosting/redistributing the Sovant backend or any proprietary components is not permitted.
+
 ## License
 
 MIT - See [LICENSE](LICENSE) file for details.

{sovant-1.0.7.dist-info → sovant-1.2.0.dist-info}/RECORD

@@ -1,14 +1,14 @@
-sovant/__init__.py,sha256=hmpXJBx3oFfXlSlmJrTh79Dy6LwvpI11jdaix-fyt88,122
+sovant/__init__.py,sha256=1GYQzmb1Ni5-y874HOs1J-rYrpx-iBzR4_cCEBFIjpk,122
 sovant/base_client.py,sha256=Vmn6OGywGwLbH5cEeflSjVOFwn5iX_YdfTdUq9pWWxA,8778
-sovant/client.py,sha256=B1SlHvUKKRSf1NYOOEkfukBmxhpsop4lHY2X_-EBFek,3372
+sovant/client.py,sha256=KQZ5yi4-5gPc7QxuRzJC0tBSfZ6Cohkdl397yuCCA0I,8331
 sovant/exceptions.py,sha256=MQMSgk7ckXnAbe7hPPpbKOnRBHSPxuCY7WSjqfJAvd0,1557
 sovant/models.py,sha256=avDAITMptDDdDfNH_ed854Q7kF6z_1OzjwJ9Xeft_-8,979
 sovant/types.py,sha256=gnvdXksJt8LObti7nc6eHSBCB7Pz7SNpS5o_HRTq_kA,6098
 sovant/resources/__init__.py,sha256=cPFIM7h8duviDdeHudnVEAmv3F89RHQxdH5BCRWFteQ,193
 sovant/resources/memories.py,sha256=bKKE0uWqFkPa1OEvbK1LrdSD7v6N04RhJ_2VDoPPQBA,11379
 sovant/resources/threads.py,sha256=mN29xP0JODmZBKyfhpeqJyViUWNVMAx3TlYAW-1ruTs,12558
-sovant-1.0.7.dist-info/licenses/LICENSE,sha256=rnNP6-elrMIlQ9jf2aqnHZMyyQ_wvF3y1hTpVUusCWU,1062
-sovant-1.0.7.dist-info/METADATA,sha256=PLokxYhdgIjz8eEFRx3epAIYwIngF-EFUf-Lu6OXzXk,11407
-sovant-1.0.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sovant-1.0.7.dist-info/top_level.txt,sha256=za6eVEsYd_ZQQs8vrmEWNcAR58r1wCDge_jA60e4CvQ,7
-sovant-1.0.7.dist-info/RECORD,,
+sovant-1.2.0.dist-info/licenses/LICENSE,sha256=rnNP6-elrMIlQ9jf2aqnHZMyyQ_wvF3y1hTpVUusCWU,1062
+sovant-1.2.0.dist-info/METADATA,sha256=cPnJTbYhtsWr77V7AJ8CkWCnZwk3p0Uz0eI7vAxK1KA,12753
+sovant-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sovant-1.2.0.dist-info/top_level.txt,sha256=za6eVEsYd_ZQQs8vrmEWNcAR58r1wCDge_jA60e4CvQ,7
+sovant-1.2.0.dist-info/RECORD,,