sovant 1.0.7__tar.gz → 1.2.0__tar.gz

{sovant-1.0.7 → sovant-1.2.0}/PKG-INFO

@@ -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/src/sovant.egg-info/PKG-INFO → sovant-1.2.0/README.md

@@ -1,19 +1,7 @@
-Metadata-Version: 2.4
-Name: sovant
-Version: 1.0.7
-Summary: Sovant Memory-as-a-Service Python SDK
-Author: Sovant
-License: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: pydantic>=2.8.2
-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 +42,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 +484,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.
+MIT - See [LICENSE](LICENSE) file for details.

{sovant-1.0.7 → sovant-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sovant"
-version = "1.0.7"
+version = "1.2.0"
 description = "Sovant Memory-as-a-Service Python SDK"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -8,6 +8,11 @@ license = {text = "MIT"}
 authors = [{name = "Sovant"}]
 dependencies = ["httpx>=0.27.0","pydantic>=2.8.2"]
 
+[project.urls]
+"Documentation" = "https://sovant.ai/docs"
+"Source" = "https://github.com/hechin91/sovant-ai"
+"Tracker" = "https://github.com/hechin91/sovant-ai/issues"
+
 [build-system]
 requires = ["setuptools>=68","wheel","build"]
 build-backend = "setuptools.build_meta"

{sovant-1.0.7 → sovant-1.2.0}/src/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-1.2.0/src/sovant/client.py

@@ -0,0 +1,220 @@
+import os
+import json
+import time
+import httpx
+from typing import Any, Dict, Optional, Callable
+from .models import MemoryCreate, SearchQuery
+
+class SovantError(Exception):
+    def __init__(self, message: str, code: str, status: int | None = None, details: Any | None = None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.details = details
+
+class Sovant:
+    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={
+                "authorization": f"Bearer {self.api_key}",
+                "content-type": "application/json"
+            }
+        )
+
+    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:
+                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'
+
+        return self._request("POST", f"{self.base_url}/api/v1/memory", json=body)
+
+    def memory_get(self, id: str):
+        return self._request("GET", f"{self.base_url}/api/v1/memories/{id}")
+
+    def memory_search(self, q: SearchQuery):
+        params = {}
+        if q.query:
+            params['query'] = q.query
+        if q.type:
+            params['type'] = q.type
+        if q.tags:
+            params['tags'] = ','.join(q.tags)
+        if q.thread_id:
+            params['thread_id'] = q.thread_id
+        if q.limit:
+            params['limit'] = str(q.limit)
+        if q.from_date:
+            params['from_date'] = q.from_date
+        if q.to_date:
+            params['to_date'] = q.to_date
+        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')
+        return self._request("PATCH", f"{self.base_url}/api/v1/memories/{id}", json=patch)
+
+    def memory_delete(self, id: str):
+        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/README.md → sovant-1.2.0/src/sovant.egg-info/PKG-INFO

@@ -1,6 +1,23 @@
+Metadata-Version: 2.4
+Name: sovant
+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
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.8.2
+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)
@@ -41,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:
@@ -457,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.
+MIT - See [LICENSE](LICENSE) file for details.

sovant-1.0.7/src/sovant/client.py

@@ -1,90 +0,0 @@
-import os
-import json
-import httpx
-from typing import Any, Dict
-from .models import MemoryCreate, SearchQuery
-
-class SovantError(Exception):
-    def __init__(self, message: str, code: str, status: int | None = None, details: Any | None = None):
-        super().__init__(message)
-        self.code = code
-        self.status = status
-        self.details = details
-
-class Sovant:
-    def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: float = 30.0):
-        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._client = httpx.Client(
-            timeout=self.timeout,
-            headers={
-                "authorization": f"Bearer {self.api_key}",
-                "content-type": "application/json"
-            }
-        )
-
-    def _handle(self, r: httpx.Response):
-        if r.status_code >= 400:
-            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
-
-    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)
-
-    def memory_get(self, id: str):
-        r = self._client.get(f"{self.base_url}/api/v1/memories/{id}")
-        return self._handle(r)
-
-    def memory_search(self, q: SearchQuery):
-        params = {}
-        if q.query:
-            params['query'] = q.query
-        if q.type:
-            params['type'] = q.type
-        if q.tags:
-            params['tags'] = ','.join(q.tags)
-        if q.thread_id:
-            params['thread_id'] = q.thread_id
-        if q.limit:
-            params['limit'] = str(q.limit)
-        if q.from_date:
-            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)
-
-    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)
-
-    def memory_delete(self, id: str):
-        r = self._client.delete(f"{self.base_url}/api/v1/memories/{id}")
-        return self._handle(r)