Skip to content

Commit 72166c0

Browse files
authored
Merge pull request #25 from EverMind-AI/feat/facade-context
feat(facade): context() for POST /api/v2/memory/context (1.3.0)
2 parents dfc0605 + 25dc08c commit 72166c0

4 files changed

Lines changed: 81 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ Add a conversation; EverOS turns it into structured, retrievable memory you can
3838
gets sharper the more your agent is used.
3939
- **Structured memory, not chat logs** — extracts episodes, user profiles, and reusable
4040
agent cases & skills from raw conversations, so retrieval returns meaning, not transcripts.
41-
- **Retrieval that fits the query** — keyword, vector, hybrid (default), or agentic multi-step search.
41+
- **Retrieval that fits the query** — keyword, vector, hybrid (default), or agentic multi-step search,
42+
plus Context Retrieval for questions that need several rounds of searching.
4243
- **Knowledge bases** — ingest documents into a searchable topic library alongside
4344
conversational memory; ingest is async and reports progress through the task API.
4445
- **Multimodal** — attach images, audio, and documents to any message.
@@ -94,7 +95,7 @@ multimodal upload — is in
9495

9596
`EverOS` covers the common calls with plain kwargs in and the response's `.data` out.
9697
Memory methods are bare verbs named after their route (`add`, `search`, `get`, `flush`,
97-
`edit`, `delete`, `update`, `delete_by_ids`, `feedback`); every other resource is
98+
`edit`, `delete`, `update`, `delete_by_ids`, `feedback`, `context`); every other resource is
9899
`<resource>_<verb>` (`kb_create`, `doc_ingest`, `task_wait`, `tag_bind`), so typing
99100
`client.kb` lists the knowledge-base surface.
100101

‎everos_cloud/client.py‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
``upload`` (storage), ``close``. They are public API and cannot be renamed. Memory
1717
methods added since follow the same bare-verb shape so the memory group stays one
1818
style and each name is the last segment of its route — ``update`` / ``delete_by_ids``
19-
/ ``feedback`` (1.2.0). Every other resource carries its name as a prefix — ``kb_`` /
19+
/ ``feedback`` (1.2.0), ``context`` (1.3.0). Every other resource carries its name as a prefix — ``kb_`` /
2020
``doc_`` / ``task_`` / ``tag_`` — so completion groups by resource and no facade method
2121
collides with the generated method it wraps.
2222
@@ -40,6 +40,7 @@
4040
AddOperation,
4141
Content,
4242
ContentItem,
43+
ContextInput,
4344
DeleteByIdsInput,
4445
DeleteInput,
4546
DeleteOperation,
@@ -87,7 +88,7 @@
8788
"add_memory": "add", "search_memory": "search", "get_memory": "get",
8889
"flush_memory": "flush", "edit_profile": "edit", "delete_memory": "delete",
8990
"update_memory": "update", "delete_memories_by_ids": "delete_by_ids",
90-
"submit_feedback": "feedback",
91+
"submit_feedback": "feedback", "retrieve_context": "context",
9192
"sign_objects": "presign",
9293
"bind_tags": "tag_bind", "unbind_tags": "tag_unbind", "replace_tags": "tag_replace",
9394
"create_knowledge_base": "kb_create", "list_knowledge_bases": "kb_list",
@@ -364,6 +365,38 @@ def search(
364365
)
365366
return self._call(self.memory.search_memory, payload).data
366367

368+
def context(
369+
self,
370+
query: str,
371+
*,
372+
user_id: str,
373+
top_k: int | None = None,
374+
include_profile: bool | None = None,
375+
filters: Any = None,
376+
app_id: str | None = None,
377+
project_id: str | None = None,
378+
) -> Any:
379+
"""Context Retrieval: an LLM searches in rounds until the evidence suffices.
380+
381+
Returns ``SearchData``, the same shape as :meth:`search` — memories, not an
382+
answer. ``episodes[].cited`` marks the ones the model's answer rested on, and
383+
``score`` is a rank-fusion score, not comparable with search scores. User owners
384+
only. The server caps the loop at 45 s and returns what it found so far, which
385+
fits the client's default 60 s timeout; a client built with a shorter timeout
386+
should raise it for this call's sake.
387+
"""
388+
payload = ContextInput(
389+
**_clean(
390+
query=query,
391+
user_id=user_id,
392+
top_k=top_k,
393+
include_profile=include_profile,
394+
filters=filters,
395+
**self._scope(app_id, project_id),
396+
)
397+
)
398+
return self._call(self.memory.retrieve_context, payload).data
399+
367400
def get(
368401
self,
369402
memory_type: str,

‎quickstart.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,14 @@ print(page.episodes)
4545
result = client.search("outdoor hobbies", user_id="user-1", top_k=10, include_profile=True)
4646
print(result.episodes)
4747

48+
# ── Context Retrieval (1.3.0) ─────────────────────────────────────────────────
49+
# An LLM searches in rounds until it can answer the question, then returns the
50+
# memories it found (not an answer). Seconds, not milliseconds: keep it off the hot
51+
# path. Same result shape as search; cited marks what the answer rested on.
52+
result = client.context("What did I decide about the Q3 budget after the finance meeting?",
53+
user_id="user-1", top_k=10)
54+
cited = [ep for ep in result.episodes if ep.cited] or result.episodes[:5]
55+
4856
# ── Edit a user's profile (bulk) ──────────────────────────────────────────────
4957
# action: add | update | delete · type: explicit_info | implicit_traits
5058
client.edit("user-1", operations=[
@@ -157,7 +165,7 @@ context manager (`with EverOS(...) as client:`) to release connections on exit.
157165

158166
Memory methods are bare verbs named after the last segment of their route (`add` /
159167
`search` / `get` / `flush` / `edit` / `delete` since 1.0.0, `update` / `delete_by_ids` /
160-
`feedback` since 1.2.0), as are `presign` / `upload` for storage and `close`. Every other
168+
`feedback` since 1.2.0, `context` since 1.3.0), as are `presign` / `upload` for storage and `close`. Every other
161169
resource is named `<resource>_<verb>`, so typing `client.kb` / `client.doc` /
162170
`client.task` / `client.tag` lists everything for that resource.
163171

@@ -167,6 +175,7 @@ resource is named `<resource>_<verb>`, so typing `client.kb` / `client.doc` /
167175
| `flush(session_id)` | `POST /api/v2/memory/flush` | Force extraction for a session. |
168176
| `get(memory_type, ...)` | `POST /api/v2/memory/get` | Paginated list by `memory_type`. |
169177
| `search(query, ...)` | `POST /api/v2/memory/search` | Keyword / vector / hybrid / agentic. |
178+
| `context(query, user_id, ...)` | `POST /api/v2/memory/context` | Multi-round LLM retrieval for multi-hop / temporal questions; user owners only. |
170179
| `edit(user_id, operations)` | `POST /api/v2/memory/edit` | Bulk profile add / update / delete. |
171180
| `delete(...)` | `POST /api/v2/memory/delete` | Scoped soft-delete (whole user / agent / session). |
172181
| `update(memory_id, ...)` | `POST /api/v2/memory/update` | Patch one episode's text / summary / subject; `unchanged` in the result when nothing differed. |

‎tests/test_client.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
from everos_cloud.exceptions import ApiException
88
from everos_cloud.models import (
99
AddInput,
10+
ContextInput,
1011
DeleteByIdsInput,
1112
DocIngestBody,
1213
DocIngestData,
@@ -82,6 +83,38 @@ def test_search_drops_none_so_defaults_survive():
8283
assert payload.method == "hybrid" # model default preserved (not overwritten with None)
8384

8485

86+
def test_context_builds_input_and_returns_data():
87+
mem = MagicMock()
88+
mem.retrieve_context.return_value = SimpleNamespace(data="C")
89+
c = _client(memory=mem)
90+
91+
assert c.context("what changed after the finance meeting?", user_id="u1", top_k=5) == "C"
92+
payload = mem.retrieve_context.call_args.args[0]
93+
assert isinstance(payload, ContextInput)
94+
assert payload.user_id == "u1" and payload.top_k == 5
95+
assert (payload.app_id, payload.project_id) == ("default", "default")
96+
assert mem.retrieve_context.call_args.kwargs["_request_timeout"] == 60.0
97+
98+
99+
def test_context_sends_none_of_the_fields_the_server_rejects():
100+
"""/context answers 422 to method != "context", min_score, radius,
101+
enable_llm_rerank and with_readable_episode; the body must carry none of them."""
102+
mem = MagicMock()
103+
mem.retrieve_context.return_value = SimpleNamespace(data=None)
104+
c = _client(memory=mem)
105+
106+
c.context("q", user_id="u1", include_profile=True)
107+
body = mem.retrieve_context.call_args.args[0].to_dict()
108+
assert body.get("method", "context") == "context"
109+
for field in ("min_score", "radius", "enable_llm_rerank", "with_readable_episode"):
110+
assert field not in body
111+
112+
113+
def test_context_requires_a_user():
114+
with pytest.raises(TypeError):
115+
_client(memory=MagicMock()).context("q")
116+
117+
85118
def test_get_and_delete():
86119
mem = MagicMock()
87120
mem.get_memory.return_value = SimpleNamespace(data="G")

0 commit comments

Comments
 (0)