memorysync 1.7.3__tar.gz → 1.9.0__tar.gz

{memorysync-1.7.3 → memorysync-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memorysync
-Version: 1.7.3
+Version: 1.9.0
 Summary: Official Python client for the MemorySync API.
 Project-URL: Homepage, https://memorysync.io
 Project-URL: Documentation, https://docs.memorysync.io

memorysync-1.9.0/src/memorysync/_version.py

@@ -0,0 +1 @@
+__version__ = "1.9.0"

{memorysync-1.7.3 → memorysync-1.9.0}/src/memorysync/client.py

@@ -193,6 +193,7 @@ class _RequestBuilder:
         session_id: Optional[str],
         metadata: Optional[Dict[str, Any]],
         end_user_id: Optional[str],
+        client_ref: Optional[str] = None,
     ) -> Dict[str, Any]:
         return _strip_none(
             {
@@ -203,6 +204,7 @@ class _RequestBuilder:
                 "session_id": session_id,
                 "metadata": metadata,
                 "end_user_id": end_user_id,
+                "client_ref": client_ref,
             }
         )
 
@@ -364,7 +366,18 @@ class MemorySyncClient:
         session_id: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
         end_user_id: Optional[str] = None,
+        client_ref: Optional[str] = None,
     ) -> AddResult:
+        """Store one memory candidate.
+
+        Pass ``client_ref`` -- your own identifier for the record, at most 128
+        characters -- and re-sending it is recognised rather than stored a second
+        time: the call returns an :class:`AddSkippedResponse` with reason
+        ``already_ingested`` and the ids the first write produced. That makes an
+        interrupted write safe to retry without first checking whether it landed.
+        Near-duplicate detection is always on, but it compares *meaning*, so it is
+        a filter and not a guarantee.
+        """
         body = _RequestBuilder.add(
             text,
             source=source,
@@ -373,6 +386,7 @@ class MemorySyncClient:
             session_id=session_id,
             metadata=metadata,
             end_user_id=end_user_id,
+            client_ref=client_ref,
         )
         raw = self._request("POST", "/memory/add", json=body, end_user_override=end_user_id)
         skipped = _as_skipped(raw, default_reason="no_high_value_content")
@@ -598,6 +612,81 @@ class MemorySyncClient:
             return skipped
         return Memory.from_dict(raw)
 
+    # ── Bulk import ──────────────────────────────────────────────────
+
+    def create_import(
+        self,
+        file: Union[bytes, "IO[bytes]"],
+        *,
+        filename: str,
+        end_user_id: Optional[str] = None,
+        resume: bool = False,
+        continue_on_error: bool = False,
+    ) -> Dict[str, Any]:
+        """Upload a payload and get an import job back, without waiting for it.
+
+        ``bulk_add`` accepts fifty records per call because each one runs the
+        extraction pipeline. For a migration out of another system, upload the
+        whole file here and poll :meth:`get_import`.
+
+        ``resume`` requires ``client_ref`` on every record and is what makes
+        re-running the same file safe: records a previous run already stored come
+        back counted as ``already_imported`` rather than stored again.
+
+        The payload is JSONL, or JSON when ``filename`` ends in ``.json``. The
+        extension is how the server picks the reader, so it is required.
+        """
+        if not filename or not filename.strip():
+            raise ValidationError("filename is required so the server can pick a reader")
+        form = _strip_none(
+            {
+                "end_user_id": end_user_id,
+                "resume": "true" if resume else "false",
+                "continue_on_error": "true" if continue_on_error else "false",
+            }
+        )
+        return (
+            self._request(
+                "POST",
+                "/imports",
+                files={"file": (filename, file)},
+                data=form,
+                end_user_override=end_user_id,
+            )
+            or {}
+        )
+
+    def get_import(self, job_id: str) -> Dict[str, Any]:
+        """One import job's status, progress and per-outcome counters.
+
+        ``progress_percentage`` stays below 100 until the job is genuinely
+        finished, so reaching 100 means done.
+        """
+        if not job_id or not str(job_id).strip():
+            raise ValidationError("job_id is required")
+        return self._request("GET", f"/imports/{job_id}") or {}
+
+    def list_imports(
+        self, *, status: Optional[str] = None, limit: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """Recent import jobs, newest first."""
+        return (
+            self._request(
+                "GET", "/imports", params={"status": status, "limit": limit}
+            )
+            or {}
+        )
+
+    def cancel_import(self, job_id: str) -> Dict[str, Any]:
+        """Ask the worker to stop between batches.
+
+        Records already imported stay imported, and the counters report how far it
+        reached. Cancelling a finished job is a no-op rather than an error.
+        """
+        if not job_id or not str(job_id).strip():
+            raise ValidationError("job_id is required")
+        return self._request("POST", f"/imports/{job_id}/cancel") or {}
+
     # ── Bulk edit ────────────────────────────────────────────────────
 
     def batch_update(
@@ -1057,7 +1146,18 @@ class AsyncMemorySyncClient:
         session_id: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
         end_user_id: Optional[str] = None,
+        client_ref: Optional[str] = None,
     ) -> AddResult:
+        """Store one memory candidate.
+
+        Pass ``client_ref`` -- your own identifier for the record, at most 128
+        characters -- and re-sending it is recognised rather than stored a second
+        time: the call returns an :class:`AddSkippedResponse` with reason
+        ``already_ingested`` and the ids the first write produced. That makes an
+        interrupted write safe to retry without first checking whether it landed.
+        Near-duplicate detection is always on, but it compares *meaning*, so it is
+        a filter and not a guarantee.
+        """
         body = _RequestBuilder.add(
             text,
             source=source,
@@ -1066,6 +1166,7 @@ class AsyncMemorySyncClient:
             session_id=session_id,
             metadata=metadata,
             end_user_id=end_user_id,
+            client_ref=client_ref,
         )
         raw = await self._request("POST", "/memory/add", json=body, end_user_override=end_user_id)
         skipped = _as_skipped(raw, default_reason="no_high_value_content")
@@ -1270,6 +1371,61 @@ class AsyncMemorySyncClient:
 
     # ── Bulk edit ────────────────────────────────────────────────────
 
+    # ── Bulk import ──────────────────────────────────────────────────
+
+    async def create_import(
+        self,
+        file: Union[bytes, "IO[bytes]"],
+        *,
+        filename: str,
+        end_user_id: Optional[str] = None,
+        resume: bool = False,
+        continue_on_error: bool = False,
+    ) -> Dict[str, Any]:
+        """Async twin of :meth:`MemorySyncClient.create_import`."""
+        if not filename or not filename.strip():
+            raise ValidationError("filename is required so the server can pick a reader")
+        form = _strip_none(
+            {
+                "end_user_id": end_user_id,
+                "resume": "true" if resume else "false",
+                "continue_on_error": "true" if continue_on_error else "false",
+            }
+        )
+        return (
+            await self._request(
+                "POST",
+                "/imports",
+                files={"file": (filename, file)},
+                data=form,
+                end_user_override=end_user_id,
+            )
+            or {}
+        )
+
+    async def get_import(self, job_id: str) -> Dict[str, Any]:
+        """Async twin of :meth:`MemorySyncClient.get_import`."""
+        if not job_id or not str(job_id).strip():
+            raise ValidationError("job_id is required")
+        return await self._request("GET", f"/imports/{job_id}") or {}
+
+    async def list_imports(
+        self, *, status: Optional[str] = None, limit: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """Async twin of :meth:`MemorySyncClient.list_imports`."""
+        return (
+            await self._request(
+                "GET", "/imports", params={"status": status, "limit": limit}
+            )
+            or {}
+        )
+
+    async def cancel_import(self, job_id: str) -> Dict[str, Any]:
+        """Async twin of :meth:`MemorySyncClient.cancel_import`."""
+        if not job_id or not str(job_id).strip():
+            raise ValidationError("job_id is required")
+        return await self._request("POST", f"/imports/{job_id}/cancel") or {}
+
     async def batch_update(
         self,
         items: Sequence[Union[BatchUpdateItem, Dict[str, Any]]],

{memorysync-1.7.3 → memorysync-1.9.0}/src/memorysync/types.py

@@ -79,6 +79,14 @@ class BulkAddItem:
     metadata: Optional[Dict[str, Any]] = None
     importance: Optional[float] = None
     end_user_id: Optional[str] = None
+    #: Your own identifier for this record, at most 128 characters.
+    #:
+    #: Send it and re-submitting the record is recognised rather than stored a
+    #: second time: the item comes back ``skipped`` with reason
+    #: ``already_ingested`` and the ids the first submission produced. This is
+    #: what makes a large import safe to re-run. Near-duplicate detection is
+    #: always on but compares *meaning*, so it is a filter and not a guarantee.
+    client_ref: Optional[str] = None
 
     def to_dict(self) -> Dict[str, Any]:
         out: Dict[str, Any] = {"text": self.text}
@@ -94,6 +102,8 @@ class BulkAddItem:
             out["importance"] = self.importance
         if self.end_user_id is not None:
             out["end_user_id"] = self.end_user_id
+        if self.client_ref is not None:
+            out["client_ref"] = self.client_ref
         return out
 
 

memorysync-1.7.3/src/memorysync/_version.py

@@ -1 +0,0 @@
-__version__ = "1.7.3"