sovant 1.1.0__tar.gz → 1.3.0__tar.gz

{sovant-1.1.0/src/sovant.egg-info → sovant-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sovant
-Version: 1.1.0
+Version: 1.3.0
 Summary: Sovant Memory-as-a-Service Python SDK
 Author: Sovant
 License: MIT
@@ -16,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)
@@ -57,6 +58,94 @@ 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
+})
+```
+
+## Working with Threads
+
+Threads let you organize related memories into conversations or sessions. Each thread has a `title` and can contain multiple memories.
+
+```python
+from sovant import Sovant
+
+client = Sovant(api_key="sk_live_your_api_key_here")
+
+# Create a new thread
+thread = client.threads_create(
+    title="Project Alpha Discussion",
+    description="Q1 planning meeting notes",
+    metadata={"project": "alpha", "quarter": "Q1"}
+)
+
+# Store memories in the thread
+from sovant.models import MemoryCreate
+
+mem1 = client.memory_create(MemoryCreate(
+    data="Decided to launch in March",
+    type="journal",
+    thread_id=thread["id"]
+))
+
+mem2 = client.memory_create(MemoryCreate(
+    data="Budget approved: $50k",
+    type="insight",
+    thread_id=thread["id"]
+))
+
+# Recall memories from this specific thread
+thread_memories = client.memory_recall(
+    query="launch date",
+    thread_id=thread["id"],
+    limit=10
+)
+
+# Get thread with all its memories
+thread_with_memories = client.threads_get(
+    thread["id"],
+    include_memories=True,
+    limit=50
+)
+
+# List all threads
+threads = client.threads_list(limit=20, offset=0)
+
+# Update thread
+updated = client.threads_update(
+    thread["id"],
+    title="Project Alpha - Q1 Launch",
+    status="completed"
+)
+
+# Delete thread (keeps memories by default)
+client.threads_delete(thread["id"])
+
+# Delete thread AND all its memories
+client.threads_delete(thread["id"], delete_memories=True)
+```
+
 ## Chat in 60 Seconds
 
 Stream real-time chat responses with memory context:

{sovant-1.1.0 → sovant-1.3.0}/README.md

@@ -1,6 +1,7 @@
 # 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 +42,94 @@ 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
+})
+```
+
+## Working with Threads
+
+Threads let you organize related memories into conversations or sessions. Each thread has a `title` and can contain multiple memories.
+
+```python
+from sovant import Sovant
+
+client = Sovant(api_key="sk_live_your_api_key_here")
+
+# Create a new thread
+thread = client.threads_create(
+    title="Project Alpha Discussion",
+    description="Q1 planning meeting notes",
+    metadata={"project": "alpha", "quarter": "Q1"}
+)
+
+# Store memories in the thread
+from sovant.models import MemoryCreate
+
+mem1 = client.memory_create(MemoryCreate(
+    data="Decided to launch in March",
+    type="journal",
+    thread_id=thread["id"]
+))
+
+mem2 = client.memory_create(MemoryCreate(
+    data="Budget approved: $50k",
+    type="insight",
+    thread_id=thread["id"]
+))
+
+# Recall memories from this specific thread
+thread_memories = client.memory_recall(
+    query="launch date",
+    thread_id=thread["id"],
+    limit=10
+)
+
+# Get thread with all its memories
+thread_with_memories = client.threads_get(
+    thread["id"],
+    include_memories=True,
+    limit=50
+)
+
+# List all threads
+threads = client.threads_list(limit=20, offset=0)
+
+# Update thread
+updated = client.threads_update(
+    thread["id"],
+    title="Project Alpha - Q1 Launch",
+    status="completed"
+)
+
+# Delete thread (keeps memories by default)
+client.threads_delete(thread["id"])
+
+# Delete thread AND all its memories
+client.threads_delete(thread["id"], delete_memories=True)
+```
+
 ## Chat in 60 Seconds
 
 Stream real-time chat responses with memory context:

{sovant-1.1.0 → sovant-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sovant"
-version = "1.1.0"
+version = "1.3.0"
 description = "Sovant Memory-as-a-Service Python SDK"
 readme = "README.md"
 requires-python = ">=3.10"

{sovant-1.1.0 → sovant-1.3.0}/src/sovant/__init__.py

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

{sovant-1.1.0 → sovant-1.3.0}/src/sovant/client.py

@@ -131,7 +131,7 @@ class Sovant:
 
     def memory_create(self, create: MemoryCreate):
         # Convert data field to content field for API
-        body = create.model_dump()
+        body = create.model_dump(exclude_none=True)
         if 'data' in body:
             body['content'] = json.dumps(body.pop('data')) if not isinstance(body.get('data'), str) else body.pop('data')
 
@@ -162,9 +162,27 @@ class Sovant:
             params['to_date'] = q.to_date
         return self._request("GET", f"{self.base_url}/api/v1/memory/search", params=params)
 
-    def memory_recall(self, q: SearchQuery):
-        """Semantic search alias for memory_search()"""
-        return self.memory_search(q)
+    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
@@ -199,4 +217,108 @@ class Sovant:
                 "data": data
             })
 
-        return self._request("POST", f"{self.base_url}/api/v1/memory/batch", json=operations)
+        return self._request("POST", f"{self.base_url}/api/v1/memory/batch", json=operations)
+
+    # ==================== Thread Methods ====================
+
+    def threads_create(self, title: str, description: str | None = None, metadata: Dict[str, Any] | None = None):
+        """
+        Create a new thread
+
+        Args:
+            title: Thread title (required)
+            description: Optional thread description
+            metadata: Optional metadata dictionary
+
+        Returns:
+            Created thread object with id
+        """
+        body = {"title": title}
+        if description:
+            body["description"] = description
+        if metadata:
+            body["metadata"] = metadata
+        return self._request("POST", f"{self.base_url}/api/v1/threads", json=body)
+
+    def threads_list(self, limit: int = 20, offset: int = 0, status: str | None = None):
+        """
+        List threads with pagination
+
+        Args:
+            limit: Maximum number of threads to return (default: 20)
+            offset: Number of threads to skip (default: 0)
+            status: Filter by status: 'active', 'archived', or 'completed'
+
+        Returns:
+            Paginated list of threads
+        """
+        params = {"limit": str(limit), "offset": str(offset)}
+        if status:
+            params["status"] = status
+        return self._request("GET", f"{self.base_url}/api/v1/threads", params=params)
+
+    def threads_get(self, thread_id: str, include_memories: bool = False, limit: int = 50):
+        """
+        Get a thread by ID
+
+        Args:
+            thread_id: Thread UUID
+            include_memories: If True, include full memory objects (default: False)
+            limit: Maximum number of memories to include (default: 50)
+
+        Returns:
+            Thread object with optional memories
+        """
+        params = {}
+        if include_memories:
+            params["include_memories"] = "true"
+            params["limit"] = str(limit)
+        return self._request("GET", f"{self.base_url}/api/v1/threads/{thread_id}", params=params)
+
+    def threads_update(
+        self,
+        thread_id: str,
+        title: str | None = None,
+        description: str | None = None,
+        status: str | None = None,
+        metadata: Dict[str, Any] | None = None
+    ):
+        """
+        Update a thread
+
+        Args:
+            thread_id: Thread UUID
+            title: New title
+            description: New description
+            status: New status ('active', 'archived', or 'completed')
+            metadata: New metadata dictionary
+
+        Returns:
+            Updated thread object
+        """
+        body = {}
+        if title is not None:
+            body["title"] = title
+        if description is not None:
+            body["description"] = description
+        if status is not None:
+            body["status"] = status
+        if metadata is not None:
+            body["metadata"] = metadata
+        return self._request("PUT", f"{self.base_url}/api/v1/threads/{thread_id}", json=body)
+
+    def threads_delete(self, thread_id: str, delete_memories: bool = False):
+        """
+        Delete a thread
+
+        Args:
+            thread_id: Thread UUID
+            delete_memories: If True, also delete all associated memories (default: False)
+
+        Returns:
+            Deletion confirmation
+        """
+        params = {}
+        if delete_memories:
+            params["delete_memories"] = "true"
+        return self._request("DELETE", f"{self.base_url}/api/v1/threads/{thread_id}", params=params)

{sovant-1.1.0 → sovant-1.3.0/src/sovant.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sovant
-Version: 1.1.0
+Version: 1.3.0
 Summary: Sovant Memory-as-a-Service Python SDK
 Author: Sovant
 License: MIT
@@ -16,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)
@@ -57,6 +58,94 @@ 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
+})
+```
+
+## Working with Threads
+
+Threads let you organize related memories into conversations or sessions. Each thread has a `title` and can contain multiple memories.
+
+```python
+from sovant import Sovant
+
+client = Sovant(api_key="sk_live_your_api_key_here")
+
+# Create a new thread
+thread = client.threads_create(
+    title="Project Alpha Discussion",
+    description="Q1 planning meeting notes",
+    metadata={"project": "alpha", "quarter": "Q1"}
+)
+
+# Store memories in the thread
+from sovant.models import MemoryCreate
+
+mem1 = client.memory_create(MemoryCreate(
+    data="Decided to launch in March",
+    type="journal",
+    thread_id=thread["id"]
+))
+
+mem2 = client.memory_create(MemoryCreate(
+    data="Budget approved: $50k",
+    type="insight",
+    thread_id=thread["id"]
+))
+
+# Recall memories from this specific thread
+thread_memories = client.memory_recall(
+    query="launch date",
+    thread_id=thread["id"],
+    limit=10
+)
+
+# Get thread with all its memories
+thread_with_memories = client.threads_get(
+    thread["id"],
+    include_memories=True,
+    limit=50
+)
+
+# List all threads
+threads = client.threads_list(limit=20, offset=0)
+
+# Update thread
+updated = client.threads_update(
+    thread["id"],
+    title="Project Alpha - Q1 Launch",
+    status="completed"
+)
+
+# Delete thread (keeps memories by default)
+client.threads_delete(thread["id"])
+
+# Delete thread AND all its memories
+client.threads_delete(thread["id"], delete_memories=True)
+```
+
 ## Chat in 60 Seconds
 
 Stream real-time chat responses with memory context: