Merge pull request #23 from EverMind-AI/feat/facade-memory-update-feedback

facade: update, delete_by_ids, feedback (1.2.0)

Author: dani1005

README.md

@@ -93,11 +93,12 @@ multimodal upload — is in
 ### Two ways to call the API
 
 `EverOS` covers the common calls with plain kwargs in and the response's `.data` out.
-New methods are named `<resource>_<verb>` (`kb_create`, `doc_ingest`, `task_wait`,
-`tag_bind`), so typing `client.kb` lists the knowledge-base surface; the methods 1.0.0
-shipped are bare verbs (`add`, `search`, `get`, `flush`, `edit`, `delete`, `upload`).
+Memory methods are bare verbs named after their route (`add`, `search`, `get`, `flush`,
+`edit`, `delete`, `update`, `delete_by_ids`, `feedback`); every other resource is
+`<resource>_<verb>` (`kb_create`, `doc_ingest`, `task_wait`, `tag_bind`), so typing
+`client.kb` lists the knowledge-base surface.
 
-Everything the API offers — all 31 operations, including knowledge-base categories and
+Everything the API offers — all 37 operations, including knowledge-base categories and
 document topics — is on the generated typed clients, reachable as `client.memory`,
 `client.storage`, `client.knowledge`, `client.tasks`. Those take and return the full
 typed models, so responses arrive as an envelope you read `.data` from. The

everos_cloud/client.py

@@ -13,11 +13,12 @@
 
 Naming: the nine methods 1.0.0 shipped are bare verbs and stay that way — ``add`` /
 ``search`` / ``get`` / ``flush`` / ``edit`` / ``delete`` (memory), ``presign`` /
-``upload`` (storage), ``close``. They are public API and cannot be renamed. Everything
-added since carries its resource as a prefix — ``kb_`` / ``doc_`` / ``task_`` /
-``tag_`` — so completion groups by resource and no facade method collides with the
-generated method it wraps. The two styles sitting side by side is a consequence of that
-freeze, not a convention worth copying.
+``upload`` (storage), ``close``. They are public API and cannot be renamed. Memory
+methods added since follow the same bare-verb shape so the memory group stays one
+style and each name is the last segment of its route — ``update`` / ``delete_by_ids``
+/ ``feedback`` (1.2.0). Every other resource carries its name as a prefix — ``kb_`` /
+``doc_`` / ``task_`` / ``tag_`` — so completion groups by resource and no facade method
+collides with the generated method it wraps.
 
 Errors: every failure raised by this facade derives from :class:`EverOSError` —
 ``EverOSAPIError`` for HTTP errors, ``EverOSStorageError`` for object-upload failures,
@@ -39,24 +40,29 @@
     AddOperation,
     Content,
     ContentItem,
+    DeleteByIdsInput,
     DeleteInput,
     DeleteOperation,
     DocIngestBody,
     DocPatchBody,
     EditInput,
     EditInputOperationsInner,
+    EpisodePatch,
+    FeedbackInput,
     FlushInput,
     GetInput,
     KbCreateInput,
     KbPatchBody,
     MessageItem,
+    Reason,
     SearchBody,
     SearchInput,
     SignObjectItem,
     SignRequest,
     TagBindInput,
     TagReplaceInput,
     TagUnbindInput,
+    UpdateInput,
     UpdateOperation,
 )
 
@@ -80,6 +86,8 @@
 _FACADE_FOR = {
     "add_memory": "add", "search_memory": "search", "get_memory": "get",
     "flush_memory": "flush", "edit_profile": "edit", "delete_memory": "delete",
+    "update_memory": "update", "delete_memories_by_ids": "delete_by_ids",
+    "submit_feedback": "feedback",
     "sign_objects": "presign",
     "bind_tags": "tag_bind", "unbind_tags": "tag_unbind", "replace_tags": "tag_replace",
     "create_knowledge_base": "kb_create", "list_knowledge_bases": "kb_list",
@@ -106,6 +114,7 @@
 
 MessageLike = Union[MessageItem, Mapping[str, Any]]
 ContentLike = Union[ContentItem, Mapping[str, Any], str]
+ReasonLike = Union[Reason, Mapping[str, Any], str]
 
 
 def _guess_file_type(name: str) -> str:
@@ -273,6 +282,15 @@ def _to_operation(op: Any) -> EditInputOperationsInner:
             raise ValueError(f"unknown edit operation action: {op.get('action')!r}")
         return EditInputOperationsInner(cls(**op))
 
+    @staticmethod
+    def _to_reason(reason: ReasonLike | None) -> Reason | None:
+        """``"redundant"`` / ``{"code": ..., "note": ...}`` / ``Reason`` -> ``Reason``."""
+        if reason is None or isinstance(reason, Reason):
+            return reason
+        if isinstance(reason, str):
+            return Reason(code=reason)
+        return Reason(**reason)
+
     @staticmethod
     def _to_content(content: ContentLike) -> ContentItem:
         """Coerce a document body into a ``ContentItem``.
@@ -422,6 +440,94 @@ def delete(
         )
         return self._call(self.memory.delete_memory, payload).data
 
+    # -- single-memory edits -------------------------------------------------
+    # These target memories by id, so like the tag calls they carry NO app_id /
+    # project_id and `_scope` does not apply. Facade names are the last segment of
+    # the route: /memory/update -> update, /memory/delete_by_ids -> delete_by_ids,
+    # /memory/feedback -> feedback.
+    def update(
+        self,
+        memory_id: str,
+        *,
+        episode: str | None = None,
+        summary: str | None = None,
+        subject: str | None = None,
+        reason: ReasonLike | None = None,
+        memory_type: str = "episode",
+    ) -> Any:
+        """Patch one episode's ``episode`` text, ``summary`` and/or ``subject``.
+
+        Only the fields you pass change (last write wins). ``reason`` is a code such as
+        ``"wrong_subject"`` or ``{"code": ..., "note": ...}``. Returns ``UpdateData``,
+        whose ``unchanged`` is true when the patch matched what was stored.
+
+        Profile items are edited with :meth:`edit`, not here.
+        """
+        patch = _clean(episode=episode, summary=summary, subject=subject)
+        if not patch:
+            raise ValueError("update needs at least one of episode / summary / subject")
+        payload = UpdateInput(
+            **_clean(
+                memory_type=memory_type,
+                memory_id=memory_id,
+                patch=EpisodePatch(**patch),
+                reason=self._to_reason(reason),
+            )
+        )
+        return self._call(self.memory.update_memory, payload).data
+
+    def delete_by_ids(
+        self,
+        memory_ids: Sequence[str],
+        *,
+        reason: ReasonLike | None = None,
+        memory_type: str = "episode",
+    ) -> Any:
+        """Soft-delete 1-50 memories by id. Returns ``DeleteByIdsData``.
+
+        Ids that do not exist are skipped; one malformed id fails the whole batch (422).
+        To clear a whole user / agent / session, use :meth:`delete`.
+        """
+        payload = DeleteByIdsInput(
+            **_clean(
+                memory_type=memory_type,
+                memory_ids=list(memory_ids),
+                reason=self._to_reason(reason),
+            )
+        )
+        return self._call(self.memory.delete_memories_by_ids, payload).data
+
+    def feedback(
+        self,
+        memory_id: str,
+        rating: str,
+        *,
+        reason: str | None = None,
+        note: str | None = None,
+        suggestion: str | None = None,
+        item_id: str | None = None,
+        memory_type: str = "episode",
+    ) -> Any:
+        """Rate a memory ``"positive"`` or ``"negative"``. Returns ``FeedbackData``.
+
+        ``reason`` (a code such as ``"outdated"``), ``note`` and ``suggestion`` go with a
+        negative rating only. ``item_id`` names the item inside a profile memory. This
+        only records the rating — nothing is edited; use :meth:`update` /
+        :meth:`delete_by_ids` to change the memory itself.
+        """
+        payload = FeedbackInput(
+            **_clean(
+                memory_type=memory_type,
+                memory_id=memory_id,
+                item_id=item_id,
+                rating=rating,
+                reason=reason,
+                note=note,
+                suggestion=suggestion,
+            )
+        )
+        return self._call(self.memory.submit_feedback, payload).data
+
     # -- memory tags ---------------------------------------------------------
     # Tag calls carry NO app_id / project_id: the scope of a tag operation is the
     # memory ids themselves, so `_scope` deliberately does not apply here.

quickstart.md

@@ -56,6 +56,18 @@ client.edit("user-1", operations=[
 # ── Delete memories (scoped soft-delete) ──────────────────────────────────────
 client.delete(user_id="user-1", session_id="session-1")
 
+# ── Fix or remove single memories (1.2.0) ─────────────────────────────────────
+# update patches one episode's text / summary / subject; only the fields you pass
+# change. reason is optional: a code, or {"code": ..., "note": ...}.
+client.update("mem-1", summary="Moved to Hangzhou; lives near West Lake.",
+              reason="wrong_subject")
+client.delete_by_ids(["mem-2", "mem-3"], reason="redundant")   # 1-50 ids, soft delete
+
+# ── Rate a memory ─────────────────────────────────────────────────────────────
+# Record-only: nothing is edited. reason / note / suggestion go with "negative".
+client.feedback("mem-1", "negative", reason="outdated",
+                suggestion="The user currently lives in Shanghai.")
+
 # ── Upload multimodal data ────────────────────────────────────────────────────
 # Presigns + POSTs the file directly to S3, returns the object key you then
 # reference in a message's multimodal content. file_type is inferred from the ext.
@@ -143,11 +155,11 @@ context manager (`with EverOS(...) as client:`) to release connections on exit.
 
 ## Method reference
 
-New facade methods are named `<resource>_<verb>`, so typing `client.kb` / `client.doc` /
-`client.task` / `client.tag` lists everything for that resource. The nine methods 1.0.0
-shipped are bare verbs with no prefix (`add` / `search` / `get` / `flush` / `edit` /
-`delete` for memory, `presign` / `upload` for storage, plus `close`) — that split is
-historical, not a rule: those names are public API since 1.0.0 and cannot be changed.
+Memory methods are bare verbs named after the last segment of their route (`add` /
+`search` / `get` / `flush` / `edit` / `delete` since 1.0.0, `update` / `delete_by_ids` /
+`feedback` since 1.2.0), as are `presign` / `upload` for storage and `close`. Every other
+resource is named `<resource>_<verb>`, so typing `client.kb` / `client.doc` /
+`client.task` / `client.tag` lists everything for that resource.
 
 | Method | Endpoint | Notes |
 |---|---|---|
@@ -156,7 +168,10 @@ historical, not a rule: those names are public API since 1.0.0 and cannot be cha
 | `get(memory_type, ...)` | `POST /api/v2/memory/get` | Paginated list by `memory_type`. |
 | `search(query, ...)` | `POST /api/v2/memory/search` | Keyword / vector / hybrid / agentic. |
 | `edit(user_id, operations)` | `POST /api/v2/memory/edit` | Bulk profile add / update / delete. |
-| `delete(...)` | `POST /api/v2/memory/delete` | Scoped soft-delete. |
+| `delete(...)` | `POST /api/v2/memory/delete` | Scoped soft-delete (whole user / agent / session). |
+| `update(memory_id, ...)` | `POST /api/v2/memory/update` | Patch one episode's text / summary / subject; `unchanged` in the result when nothing differed. |
+| `delete_by_ids(memory_ids, ...)` | `POST /api/v2/memory/delete_by_ids` | Soft-delete 1-50 memories by id; unknown ids are skipped. |
+| `feedback(memory_id, rating, ...)` | `POST /api/v2/memory/feedback` | Record a positive / negative rating; edits nothing. |
 | `upload(path)` | `POST /api/v2/object/sign` + S3 | Presign + direct-to-S3, returns `object_key`. |
 | `tag_bind` / `tag_unbind` / `tag_replace` | `POST /api/v2/memory/tag/*` | Add / remove / overwrite tags on memory ids. |
 | `kb_create(name, ...)` | `POST /api/v2/knowledge_bases` | Create a knowledge base. |

tests/test_client.py

@@ -7,17 +7,21 @@
 from everos_cloud.exceptions import ApiException
 from everos_cloud.models import (
     AddInput,
+    DeleteByIdsInput,
     DocIngestBody,
     DocIngestData,
     EditInput,
+    FeedbackInput,
     KbCreateInput,
     KbPatchBody,
     MessageItem,
+    Reason,
     SearchBody,
     SearchInput,
     TagBindInput,
     TagReplaceInput,
     TagUnbindInput,
+    UpdateInput,
 )
 
 
@@ -290,6 +294,118 @@ def test_tag_inputs_carry_no_scope():
     assert not hasattr(payload, "project_id") or payload.project_id is None
 
 
+# ── single-memory edits (1.2.0) ──────────────────────────────────────────────
+def test_update_builds_patch_and_reason():
+    mem = MagicMock()
+    mem.update_memory.return_value = SimpleNamespace(data="UP")
+    c = _client(memory=mem)
+
+    assert c.update("m1", summary="Moved to Hangzhou", reason="wrong_subject") == "UP"
+    payload = mem.update_memory.call_args.args[0]
+    assert isinstance(payload, UpdateInput)
+    assert payload.memory_type == "episode" and payload.memory_id == "m1"
+    assert payload.patch.summary == "Moved to Hangzhou"
+    assert payload.patch.episode is None and payload.patch.subject is None
+    assert isinstance(payload.reason, Reason)
+    assert payload.reason.code == "wrong_subject" and payload.reason.note is None
+
+
+def test_update_reason_accepts_dict_model_or_nothing():
+    mem = MagicMock()
+    mem.update_memory.return_value = SimpleNamespace(data=None)
+    c = _client(memory=mem)
+
+    c.update("m1", episode="x", reason={"code": "wrong_time", "note": "was 2024"})
+    r = mem.update_memory.call_args.args[0].reason
+    assert r.code == "wrong_time" and r.note == "was 2024"
+
+    c.update("m1", episode="x", reason=Reason(code="style"))
+    assert mem.update_memory.call_args.args[0].reason.code == "style"
+
+    c.update("m1", episode="x")
+    assert mem.update_memory.call_args.args[0].reason is None
+
+
+def test_update_rejects_an_empty_patch():
+    mem = MagicMock()
+    c = _client(memory=mem)
+    with pytest.raises(ValueError):
+        c.update("m1")
+    mem.update_memory.assert_not_called()
+
+
+def test_delete_by_ids_builds_input_and_returns_data():
+    mem = MagicMock()
+    mem.delete_memories_by_ids.return_value = SimpleNamespace(data="D")
+    c = _client(memory=mem)
+
+    assert c.delete_by_ids(("m1", "m2"), reason="redundant") == "D"
+    payload = mem.delete_memories_by_ids.call_args.args[0]
+    assert isinstance(payload, DeleteByIdsInput)
+    assert payload.memory_type == "episode"
+    assert payload.memory_ids == ["m1", "m2"]          # tuple -> list
+    assert payload.reason.code == "redundant"
+
+    c.delete_by_ids(["m3"])
+    assert mem.delete_memories_by_ids.call_args.args[0].reason is None
+
+
+_OID = "66dff0f8a9f84d8c9f62f011"   # feedback validates memory_id as a 24-char object id
+
+
+def test_feedback_builds_input_and_returns_data():
+    mem = MagicMock()
+    mem.submit_feedback.return_value = SimpleNamespace(data="F")
+    c = _client(memory=mem)
+
+    assert c.feedback(_OID, "negative", reason="outdated", note="moved",
+                      suggestion="Lives in Shanghai now.") == "F"
+    payload = mem.submit_feedback.call_args.args[0]
+    assert isinstance(payload, FeedbackInput)
+    assert payload.memory_type == "episode" and payload.memory_id == _OID
+    assert payload.rating == "negative" and payload.reason == "outdated"
+    assert payload.note == "moved" and payload.suggestion == "Lives in Shanghai now."
+    assert payload.item_id is None
+
+    c.feedback(_OID, "positive", memory_type="profile", item_id="it_" + "0" * 24)
+    payload = mem.submit_feedback.call_args.args[0]
+    assert payload.memory_type == "profile" and payload.rating == "positive"
+    assert payload.item_id == "it_" + "0" * 24
+    assert payload.reason is None and payload.note is None and payload.suggestion is None
+
+
+def test_by_id_calls_carry_no_scope():
+    """These target memory ids, so app_id / project_id must not be injected."""
+    mem = MagicMock()
+    for name in ("update_memory", "delete_memories_by_ids", "submit_feedback"):
+        getattr(mem, name).return_value = SimpleNamespace(data=None)
+    c = EverOS("sk-test", app_id="myapp", project_id="proj")
+    c.memory = mem
+
+    c.update("m1", subject="s")
+    c.delete_by_ids(["m1"])
+    c.feedback(_OID, "positive")
+    for name in ("update_memory", "delete_memories_by_ids", "submit_feedback"):
+        payload = getattr(mem, name).call_args.args[0]
+        assert getattr(payload, "app_id", None) is None
+        assert getattr(payload, "project_id", None) is None
+
+
+def test_by_id_errors_and_timeout_go_through_call():
+    mem = MagicMock()
+    mem.update_memory.side_effect = ApiException(status=422, reason="Unprocessable")
+    c = _client(memory=mem)
+    with pytest.raises(EverOSAPIError) as ei:
+        c.update("bad", episode="x")
+    assert ei.value.status == 422
+
+    mem.submit_feedback.return_value = SimpleNamespace(data=None)
+    c2 = EverOS("sk-test", timeout=7)
+    c2.memory = mem
+    c2.feedback(_OID, "positive")
+    assert mem.submit_feedback.call_args.kwargs["_request_timeout"] == 7
+
+
 # ── knowledge base ───────────────────────────────────────────────────────────
 def test_create_kb_builds_input_and_drops_none():
     kb = MagicMock()
@@ -681,6 +797,11 @@ def test_generated_name_on_the_facade_points_at_the_real_one():
     assert "client.kb_create" in msg                          # facade equivalent
     assert "client.knowledge.create_knowledge_base" in msg    # generated location
 
+    with pytest.raises(AttributeError) as ei:
+        c.submit_feedback
+    assert "client.feedback" in str(ei.value)
+    assert "client.memory.submit_feedback" in str(ei.value)
+
     # a generated method the facade does NOT cover: still says where it lives
     with pytest.raises(AttributeError) as ei:
         c.list_topics