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

sovant/__init__.py

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

sovant-1.0.7.dist-info/METADATA

@@ -0,0 +1,475 @@
+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.
+
+[![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)
+
+## Installation
+
+```bash
+pip install sovant
+```
+
+## Quick Start
+
+```python
+from sovant import Sovant
+
+# Initialize the client
+client = Sovant(api_key="sk_live_your_api_key_here", base_url="https://sovant.ai")
+
+# Create a memory
+mem = client.memory.create({
+    "content": "User prefers dark mode",
+    "type": "preference",
+    "tags": ["ui", "settings"]
+})
+
+# Search memories
+results = client.memory.search({
+    "query": "user preferences",
+    "limit": 10
+})
+
+# Update a memory
+updated = client.memory.update(mem["id"], {
+    "tags": ["ui", "settings", "theme"]
+})
+
+# Delete a memory
+client.memory.delete(mem["id"])
+```
+
+## Chat in 60 Seconds
+
+Stream real-time chat responses with memory context:
+
+```python
+from sovant import Sovant
+import sys
+
+client = Sovant(api_key="sk_live_your_api_key_here", base_url="https://sovant.ai")
+
+# Create a chat session
+session = client.chat.create_session({"title": "Demo"})
+
+# Stream a response
+stream = client.chat.send_message(
+    session["id"],
+    "hello",
+    {
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "use_memory": True
+    },
+    stream=True
+)
+
+for ev in stream:
+    if ev["type"] == "delta":
+        sys.stdout.write(ev.get("data", ""))
+    elif ev["type"] == "done":
+        print("\n[done]")
+
+# Get chat history
+messages = client.chat.get_messages(session["id"])
+```
+
+## Profile Recall Helpers
+
+Save and recall user profile facts with canonical patterns:
+
+```python
+# Extract profile entity from text
+fact = client.recall.extract_profile("i'm from kuching")
+# -> {"entity": "location", "value": "kuching"} | None
+
+if fact:
+    client.recall.save_profile_fact(fact)  # canonicalizes and persists
+
+# Get all profile facts
+profile = client.recall.get_profile_facts()
+# -> {"name": "...", "age": "...", "location": "...", "preferences": [...]}
+```
+
+## Configuration
+
+```python
+from sovant import Sovant
+
+client = Sovant(
+    api_key="sk_live_your_api_key_here",  # Required
+    base_url="https://sovant.ai",         # Optional, API endpoint
+    timeout=30.0,                          # Optional, request timeout in seconds (default: 30.0)
+    max_retries=3,                         # Optional, max retry attempts (default: 3)
+    debug=False,                           # Optional, enable debug logging (default: False)
+)
+```
+
+The SDK handles dual authentication automatically, preferring the `x-sovant-api-key` header over `Authorization: Bearer`.
+
+## API Reference
+
+### Memory Operations
+
+#### Create Memory
+
+```python
+memory = client.memory.create({
+    "content": "Customer contacted support about billing",
+    "type": "observation",          # 'journal' | 'insight' | 'observation' | 'task' | 'preference'
+    "tags": ["support", "billing"],
+    "metadata": {"ticket_id": "12345"},
+    "thread_id": "thread_abc123",   # Optional thread association
+})
+```
+
+#### List Memories
+
+```python
+memories = client.memory.list({
+    "limit": 20,                    # Max items per page (default: 20)
+    "offset": 0,                    # Pagination offset
+    "tags": ["billing"],            # Filter by tags
+    "type": "observation",          # Filter by type
+    "is_archived": False,           # Filter archived status
+})
+
+print(memories["memories"])         # Array of memories
+print(memories["total"])            # Total count
+print(memories["has_more"])         # More pages available
+```
+
+#### Get Memory by ID
+
+```python
+memory = client.memory.get("mem_123abc")
+```
+
+#### Update Memory (Partial)
+
+```python
+updated = client.memory.update("mem_123abc", {
+    "tags": ["support", "billing", "resolved"],
+    "metadata": {
+        **memory.get("metadata", {}),
+        "resolved": True,
+    },
+    "is_archived": True,
+})
+```
+
+#### Replace Memory (Full)
+
+```python
+replaced = client.memory.put("mem_123abc", {
+    "content": "Updated content here",  # Required for PUT
+    "type": "observation",
+    "tags": ["updated"],
+})
+```
+
+#### Delete Memory
+
+```python
+client.memory.delete("mem_123abc")
+```
+
+#### Search Memories
+
+```python
+# Semantic search
+semantic_results = client.memory.search({
+    "query": "customer preferences about notifications",
+    "limit": 10,
+    "type": "preference",
+})
+
+# Filter-based search
+filter_results = client.memory.search({
+    "tags": ["settings", "notifications"],
+    "from_date": "2024-01-01",
+    "to_date": "2024-12-31",
+    "limit": 20,
+})
+```
+
+#### Batch Operations
+
+```python
+batch = client.memory.batch({
+    "operations": [
+        {
+            "op": "create",
+            "data": {
+                "content": "First memory",
+                "type": "journal",
+            },
+        },
+        {
+            "op": "update",
+            "id": "mem_123abc",
+            "data": {
+                "tags": ["updated"],
+            },
+        },
+        {
+            "op": "delete",
+            "id": "mem_456def",
+        },
+    ],
+})
+
+print(batch["results"])         # Individual operation results
+print(batch["summary"])         # Summary statistics
+```
+
+### Thread Management
+
+Associate memories with conversation threads:
+
+```python
+# Create a thread
+thread = client.threads.create({
+    "title": "Customer Support Session",
+    "metadata": {"user_id": "user_123"}
+})
+
+# List threads
+threads = client.threads.list({
+    "limit": 10,
+    "offset": 0
+})
+
+# Get thread by ID
+thread = client.threads.get("thread_abc123")
+
+# Update thread
+updated_thread = client.threads.update("thread_abc123", {
+    "title": "Resolved: Billing Issue",
+    "metadata": {"status": "resolved"}
+})
+
+# Delete thread
+client.threads.delete("thread_abc123")
+
+# Link memory to thread
+client.threads.link_memory("thread_abc123", "mem_123abc")
+
+# Create memories within a thread
+memory1 = client.memory.create({
+    "content": "User asked about pricing",
+    "type": "observation",
+    "thread_id": "thread_abc123",
+})
+
+memory2 = client.memory.create({
+    "content": "User selected enterprise plan",
+    "type": "observation",
+    "thread_id": "thread_abc123",
+})
+
+# List memories in a thread
+thread_memories = client.memory.list({
+    "thread_id": "thread_abc123",
+})
+```
+
+### API Key Management
+
+Manage API keys programmatically:
+
+```python
+# List all API keys
+keys = client.keys.list()
+print(keys)  # Array of key objects
+
+# Create a new API key
+new_key = client.keys.create({"name": "CI key"})
+print(new_key["key"])  # The actual secret key (only shown once!)
+
+# Update key metadata
+client.keys.update(new_key["id"], {"name": "Production key"})
+
+# Revoke a key
+client.keys.revoke(new_key["id"])
+```
+
+## Memory Types
+
+- **journal** - Chronological entries and logs
+- **insight** - Derived patterns and conclusions
+- **observation** - Factual, observed information
+- **task** - Action items and todos
+- **preference** - User preferences and settings
+
+## Error Handling
+
+The SDK provides typed errors for better error handling:
+
+```python
+from sovant import Sovant, SovantError, AuthError, RateLimitError, NetworkError, TimeoutError
+
+try:
+    memory = client.memory.get("invalid_id")
+except AuthError as e:
+    print(f"Authentication failed: {e}")
+    # Handle authentication error
+except RateLimitError as e:
+    print(f"Rate limit exceeded: {e}")
+    print(f"Retry after: {e.retry_after}")
+    # Handle rate limiting
+except NetworkError as e:
+    print(f"Network error: {e}")
+    # Handle network issues
+except TimeoutError as e:
+    print(f"Request timed out: {e}")
+    # Handle timeout
+except SovantError as e:
+    print(f"API Error: {e}")
+    print(f"Status: {e.status}")
+    print(f"Request ID: {e.request_id}")
+
+    if e.status == 404:
+        # Handle not found
+        pass
+    elif e.status == 400:
+        # Handle bad request
+        pass
+```
+
+## Advanced Features
+
+### Retry Configuration
+
+The SDK automatically retries failed requests with exponential backoff:
+
+```python
+client = Sovant(
+    api_key="sk_live_...",
+    max_retries=5,           # Increase retry attempts
+    timeout=60.0,            # Increase timeout for slow connections
+)
+```
+
+### Debug Mode
+
+Enable debug logging to see detailed request/response information:
+
+```python
+client = Sovant(
+    api_key="sk_live_...",
+    debug=True,              # Enable debug output
+)
+```
+
+### Custom Base URL
+
+Connect to different environments:
+
+```python
+client = Sovant(
+    api_key="sk_live_...",
+    base_url="https://staging.sovant.ai",
+)
+```
+
+## Best Practices
+
+1. **Use appropriate memory types** - Choose the correct type for your use case
+2. **Add meaningful tags** - Tags improve searchability and organization
+3. **Use threads** - Group related memories together
+4. **Handle errors gracefully** - Implement proper error handling
+5. **Batch operations** - Use batch API for multiple operations
+6. **Archive don't delete** - Consider archiving instead of deleting
+
+## Examples
+
+### Customer Support Integration
+
+```python
+# Track customer interaction
+interaction = client.memory.create({
+    "content": "Customer reported slow dashboard loading",
+    "type": "observation",
+    "thread_id": f"ticket_{ticket_id}",
+    "tags": ["support", "performance", "dashboard"],
+    "metadata": {
+        "ticket_id": ticket_id,
+        "customer_id": customer_id,
+        "priority": "high",
+    },
+})
+
+# Record resolution
+resolution = client.memory.create({
+    "content": "Resolved by clearing cache and upgrading plan",
+    "type": "insight",
+    "thread_id": f"ticket_{ticket_id}",
+    "tags": ["support", "resolved"],
+    "metadata": {
+        "ticket_id": ticket_id,
+        "resolution_time": "2h",
+    },
+})
+```
+
+### User Preference Tracking
+
+```python
+# Store preference
+preference = client.memory.create({
+    "content": "User prefers email notifications over SMS",
+    "type": "preference",
+    "tags": ["notifications", "email", "settings"],
+    "metadata": {
+        "user_id": user_id,
+        "setting": "notification_channel",
+        "value": "email",
+    },
+})
+
+# Query preferences
+preferences = client.memory.search({
+    "query": "notification preferences",
+    "type": "preference",
+    "tags": ["notifications"],
+})
+```
+
+## Rate Limiting
+
+The API implements rate limiting. The SDK automatically handles rate limit responses with retries. Rate limit headers are included in responses:
+
+- `X-RateLimit-Limit` - Request limit per window
+- `X-RateLimit-Remaining` - Remaining requests
+- `X-RateLimit-Reset` - Reset timestamp
+
+## Support
+
+- Documentation: [https://sovant.ai/docs](https://sovant.ai/docs)
+- API/Auth docs: [https://sovant.ai/docs/security/auth](https://sovant.ai/docs/security/auth)
+- Issues: [GitHub Issues](https://github.com/sovant-ai/python-sdk/issues)
+- Support: support@sovant.ai
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for a detailed history of changes.
+
+## License
+
+MIT - See [LICENSE](LICENSE) file for details.

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

@@ -1,4 +1,4 @@
-sovant/__init__.py,sha256=1GYQzmb1Ni5-y874HOs1J-rYrpx-iBzR4_cCEBFIjpk,122
+sovant/__init__.py,sha256=hmpXJBx3oFfXlSlmJrTh79Dy6LwvpI11jdaix-fyt88,122
 sovant/base_client.py,sha256=Vmn6OGywGwLbH5cEeflSjVOFwn5iX_YdfTdUq9pWWxA,8778
 sovant/client.py,sha256=B1SlHvUKKRSf1NYOOEkfukBmxhpsop4lHY2X_-EBFek,3372
 sovant/exceptions.py,sha256=MQMSgk7ckXnAbe7hPPpbKOnRBHSPxuCY7WSjqfJAvd0,1557
@@ -7,8 +7,8 @@ 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.5.dist-info/licenses/LICENSE,sha256=rnNP6-elrMIlQ9jf2aqnHZMyyQ_wvF3y1hTpVUusCWU,1062
-sovant-1.0.5.dist-info/METADATA,sha256=GmaGl7CztLd-e_iqfvn35tQE3peBCnhEfGzwDARAHV8,3834
-sovant-1.0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sovant-1.0.5.dist-info/top_level.txt,sha256=za6eVEsYd_ZQQs8vrmEWNcAR58r1wCDge_jA60e4CvQ,7
-sovant-1.0.5.dist-info/RECORD,,
+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.0.5.dist-info/METADATA

@@ -1,118 +0,0 @@
-Metadata-Version: 2.4
-Name: sovant
-Version: 1.0.5
-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
-
-**AI Infrastructure: Memory-as-a-Service for AI systems.**  
-The official Python client for the Sovant Memory API.
-
-[![PyPI version](https://img.shields.io/pypi/v/sovant)](https://pypi.org/project/sovant/)
-[![Documentation](https://img.shields.io/badge/docs-sovant.ai-blue)](https://sovant.ai/docs)
-[![GitHub](https://img.shields.io/badge/github-sovant-lightgrey)](https://github.com/sovant-ai/sovant)
-
----
-
-## What is Sovant?
-
-Sovant is an **AI infrastructure company** providing the **memory layer for AI systems**.  
-Our platform makes it simple to persist, search, and manage conversational/context data securely across sessions, channels, and applications.
-
-- **Problem:** Most AI systems forget once a session ends → compliance risk, knowledge loss, poor UX.  
-- **Solution:** Sovant provides a **Memory-as-a-Service API** — store, retrieve, and search memories with audit-ready controls.  
-- **Built for:** Developers & enterprises building AI agents, copilots, or compliance-driven apps that need persistent context.
-
----
-
-## Installation
-
-```bash
-pip install sovant
-```
-
-## 60-Second Quickstart
-
-```python
-from sovant import Sovant, MemoryCreate, SearchQuery
-
-client = Sovant(api_key="YOUR_API_KEY")
-
-# Create a memory (SDK uses 'data' field, automatically converts to 'content' for API)
-created = client.memory_create(MemoryCreate(
-    data="User prefers morning meetings",  # Note: 'data' field (not 'content')
-    type="preference",
-    tags=["customer:123"],
-    # metadata={"source": "crm"},
-    # thread_id="00000000-0000-0000-0000-000000000000",
-))
-print(created)
-
-# Search memories
-results = client.memory_search(SearchQuery(
-    query="meeting preferences",
-    topK=3,
-    # tags=["customer:123"],
-    # thread_id="...",
-))
-print(results)
-```
-
-## Features
-
-- **Memory CRUD** — create, retrieve, update (PATCH/PUT), delete
-- **Semantic Search** — full-text/semantic with topK and filters
-- **Threads** — group related memories via thread_id (REST API)
-- **Batch Operations (Beta)** — atomic multi-operation requests
-- **Compliance-ready** — audit trails, PDPA/GDPR-friendly design
-- **SDKs** — official Python & TypeScript clients + REST reference
-
-## SDKs & Documentation
-
-- **Python** (this package) on PyPI: https://pypi.org/project/sovant/
-- **TypeScript** on npm: https://www.npmjs.com/package/@sovant/sdk
-- **REST API Reference**: https://sovant.ai/docs/api
-- **Full Documentation**: https://sovant.ai/docs
-
-## API Overview
-
-### Endpoints Summary
-
-- `POST /api/v1/memory` — Create memory
-- `GET /api/v1/memory` — List memories
-- `GET /api/v1/memories/{id}` — Get by ID
-- `PATCH | PUT /api/v1/memories/{id}` — Update
-- `DELETE /api/v1/memories/{id}` — Delete
-- `GET /api/v1/memory/search` — Search
-- `POST /api/v1/memory/batch` — Batch (Beta)
-
-**Auth:** Bearer token in the `Authorization` header.
-
-## Field Mapping Note
-
-- **SDK uses:** `data` field in MemoryCreate (more intuitive for developers)
-- **API expects:** `content` field (SDK automatically converts `data` → `content`)
-- **Deprecated:** `subject` is ignored by the API. Use `thread_id`, `tags`, or `metadata` for grouping.
-
-## Status of Advanced Features
-
-- **Batch API:** Available, marked Beta (contract may evolve).
-- **Threads:** Fully supported via REST API.
-- **Webhooks / Personalization / Multi-Channel Sync:** Coming soon.
-
-## Versioning & Changelog
-
-- **Stable release:** 1.0.5
-- See [CHANGELOG.md](https://github.com/sovant-ai/sovant) in the repo for details.
-
-## License
-
-MIT © Sovant AI