fruxon 2.2.0__tar.gz → 2.2.1__tar.gz

{fruxon-2.2.0 → fruxon-2.2.1}/HISTORY.md

@@ -1,5 +1,24 @@
 # History
 
+## Unreleased — `chat_user` is deprecated: the server ignores it
+
+- `execute`, `stream` and `stream_text` no longer send `chat_user` (as
+  `chatUser`). The execution endpoints have no field for it, so the server
+  dropped it unread: it did not identify the end user to the agent, gave no
+  per-user memory and filled no `{{sender.*}}` values. The argument is still
+  accepted, so existing calls keep working, but passing it emits a
+  `DeprecationWarning`. To give the agent details about the user, pass them in
+  `parameters`.
+
+## Unreleased — `agents memory` names a person by participant id or address
+
+- `fruxon agents memory forget-subject` and `list --subject` document the
+  subject the server takes: the person's participant id, or one of their
+  addresses as `provider:identifier` (e.g. `telegram:123456789`). The old
+  example, `user_42`, matched nothing. With fruxon-backend's fix either form
+  reaches every memory about the person — those filed under the participant
+  id since memory follows the person, and older ones filed under an address.
+
 ## Unreleased — whoami and the 403 hint read the role cap off the key
 
 - On a server with fruxon-backend #1571, `fruxon whoami` and the 403

{fruxon-2.2.0 → fruxon-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fruxon
-Version: 2.2.0
+Version: 2.2.1
 Summary: The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.
 Project-URL: bugs, https://github.com/fruxon-ai/fruxon-sdk/issues
 Project-URL: changelog, https://github.com/fruxon-ai/fruxon-sdk/blob/main/HISTORY.md

{fruxon-2.2.0 → fruxon-2.2.1}/src/fruxon/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.0'
-__version_tuple__ = version_tuple = (2, 2, 0)
+__version__ = version = '2.2.1'
+__version_tuple__ = version_tuple = (2, 2, 1)
 
 __commit_id__ = commit_id = None

{fruxon-2.2.0 → fruxon-2.2.1}/src/fruxon/cli/agents_memory.py

@@ -51,7 +51,13 @@ def memory_list(
     agent: Annotated[str, typer.Argument(help="Agent whose memories to list.")],
     subject: Annotated[
         str | None,
-        typer.Option("--subject", help="Only memories about this subject (person / end-user key)."),
+        typer.Option(
+            "--subject",
+            help=(
+                "Only memories about this person: their participant id, or a channel address as "
+                "provider:identifier (e.g. telegram:123456789)."
+            ),
+        ),
     ] = None,
     query: Annotated[str | None, typer.Option("--query", "-q", help="Full-text filter over title + content.")] = None,
     scope: Annotated[
@@ -75,10 +81,13 @@ def memory_list(
     """List what an agent remembers — narrow with --subject / --query / --scope.
 
     The filters run server-side, so "what does my agent remember about
-    user_42" is `--subject user_42`, not a client-side scan.
+    the Telegram user 123456789" is `--subject telegram:123456789`, not a
+    client-side scan. A subject is the person's participant id or one of
+    their addresses as provider:identifier; either matches every memory
+    about them.
 
     Examples:
-        fruxon agents memory list my-agent --subject user_42
+        fruxon agents memory list my-agent --subject telegram:123456789
         fruxon agents memory list my-agent --query "dark mode"
         fruxon agents memory list my-agent --scope AGENT --output id
     """
@@ -228,7 +237,15 @@ def memory_get(
 @memory_app.command("forget-subject")
 def memory_forget_subject(
     agent: Annotated[str, typer.Argument(help="Agent whose memories to prune.")],
-    subject: Annotated[str, typer.Argument(help="The subject (person / end-user key) to forget entirely.")],
+    subject: Annotated[
+        str,
+        typer.Argument(
+            help=(
+                "The person to forget entirely: their participant id, or a channel address as "
+                "provider:identifier (e.g. telegram:123456789)."
+            )
+        ),
+    ],
     yes: Annotated[
         bool,
         typer.Option("--yes", "-y", help="Skip the confirmation prompt. REQUIRED under agent mode (CLAUDECODE / CI)."),
@@ -242,11 +259,17 @@ def memory_forget_subject(
 ):
     """Forget every memory an agent holds about one subject (GDPR-style).
 
-    Irreversible — it deletes all of the subject's memories. Confirms
-    first, and under agent mode refuses without [bold]--yes[/bold].
+    Irreversible — it deletes all of the person's memories, whether they
+    are filed under the participant id or under any of the person's
+    addresses, and records each deletion in the agent's deletion trail.
+    Confirms first, and under agent mode refuses without [bold]--yes[/bold].
+
+    Name the person by participant id (the `subject` column of
+    `agents memory subjects`) or by an address as provider:identifier.
 
     Examples:
-        fruxon agents memory forget-subject my-agent user_42 --yes
+        fruxon agents memory forget-subject my-agent telegram:123456789 --yes
+        fruxon agents memory forget-subject my-agent 0199f3c2-5b1e-7c4a-9d2e-3f6a8b1c0d4e --yes
     """
     output = resolve_output_format(output, human_default="text", agent_default="json")
     if output not in {"text", "json"}:

{fruxon-2.2.0 → fruxon-2.2.1}/src/fruxon/cli/examples.py

@@ -384,10 +384,16 @@ _EXAMPLES: dict[str, list[tuple[str, str]]] = {
         ),
     ],
     "memory": [
-        ("fruxon agents memory list my-agent --subject user_42", "What the agent remembers about one person"),
+        (
+            "fruxon agents memory list my-agent --subject telegram:123456789",
+            "What the agent remembers about one person (participant id or provider:identifier)",
+        ),
         ("fruxon agents memory list my-agent --query 'dark mode'", "Full-text over its memories"),
         ("fruxon agents memory subjects my-agent", "Which subjects it has memories about (+ counts)"),
-        ("fruxon agents memory forget-subject my-agent user_42 --yes", "GDPR-forget everything about a subject"),
+        (
+            "fruxon agents memory forget-subject my-agent telegram:123456789 --yes",
+            "GDPR-forget everything about a person",
+        ),
     ],
     "metrics": [
         ("fruxon metrics list", "Browse evaluation metrics (ids for quality checks)"),

{fruxon-2.2.0 → fruxon-2.2.1}/src/fruxon/fruxon.py

@@ -15,6 +15,7 @@ import urllib.error
 import urllib.parse
 import urllib.request
 import uuid
+import warnings
 from collections.abc import Callable, Iterator
 from datetime import datetime, timezone
 from typing import Any, NoReturn
@@ -275,6 +276,21 @@ _STATUS_EXCEPTIONS: dict[int, type[FruxonAPIError]] = {
 }
 
 
+# ``chat_user`` on execute / stream / stream_text. The execution body
+# (``AgentExecutionRequestView``) has no field for it — end-user identity is
+# deliberately not settable there — so the server dropped it unread.
+_CHAT_USER_IGNORED = (
+    "chat_user is deprecated and has no effect: the agent execution endpoints have no field for it, "
+    "so it does not identify the end user to the agent (no per-user memory, no {{sender.*}} values) "
+    "and is no longer sent. To give the agent details about the user, pass them in `parameters`."
+)
+
+
+def _warn_chat_user_ignored() -> None:
+    # stacklevel=3: past this helper and the client method, to the caller.
+    warnings.warn(_CHAT_USER_IGNORED, DeprecationWarning, stacklevel=3)
+
+
 def _detect_actor() -> str | None:
     """Identify the tool making the request, for the ``X-Fruxon-Actor`` header.
 
@@ -376,17 +392,22 @@ class FruxonClient:
             agent: The agent identifier.
             parameters: Execution parameters and inputs.
             attachments: File attachments.
-            chat_user: Chat user information.
+            chat_user: Deprecated, and ignored: it is not sent, and passing it
+                emits a :class:`DeprecationWarning`. The execution endpoints
+                have no end-user field, so it does not identify the user to
+                the agent. Pass what the agent should know about the user in
+                ``parameters``.
             session_id: Session identifier for multi-turn conversations.
             environment_slug: End-customer environment to attribute this run
                 to (per-environment cost tracking, quota enforcement, and
                 analytics). Sent as ``environmentSlug`` in the request body.
         """
+        if chat_user is not None:
+            _warn_chat_user_ignored()
         url = self._agent_url(agent, ":execute")
         body = self._build_execution_body(
             parameters=parameters,
             attachments=attachments,
-            chat_user=chat_user,
             session_id=session_id,
             environment_slug=environment_slug,
         )
@@ -411,12 +432,16 @@ class FruxonClient:
         For the common case of "stream and print the model's text chunks,"
         prefer :meth:`stream_text`, which yields just the concatenable text
         pieces.
+
+        Arguments are those of :meth:`execute`; ``chat_user`` is deprecated
+        and ignored there too.
         """
+        if chat_user is not None:
+            _warn_chat_user_ignored()
         url = self._agent_url(agent, ":stream")
         body = self._build_execution_body(
             parameters=parameters,
             attachments=attachments,
-            chat_user=chat_user,
             session_id=session_id,
             environment_slug=environment_slug,
         )
@@ -438,12 +463,17 @@ class FruxonClient:
         ``chunk`` payload as a string. Use this when you want to mirror the
         chat-style streaming UX without dealing with tool calls, step traces,
         or terminal events.
+
+        Arguments are those of :meth:`execute`; ``chat_user`` is deprecated
+        and ignored there too. Being a generator, it warns on the first
+        iteration rather than at the call.
         """
+        if chat_user is not None:
+            _warn_chat_user_ignored()
         for event in self.stream(
             agent,
             parameters=parameters,
             attachments=attachments,
-            chat_user=chat_user,
             session_id=session_id,
             environment_slug=environment_slug,
         ):
@@ -1406,7 +1436,10 @@ class FruxonClient:
         ``...ListPage`` envelope). The filters answer the question an
         author actually has:
 
-        * ``subject`` — only memories about one person/end-user;
+        * ``subject`` — only memories about one person/end-user, named by
+          participant id or by a channel address as ``provider:identifier``
+          (e.g. ``telegram:123456789``); either matches every memory about
+          them;
         * ``query`` — full-text over title/content;
         * ``scope`` — ``AGENT`` (cross-everyone facts) or ``SUBJECT``
           (per-person facts).
@@ -1450,8 +1483,10 @@ class FruxonClient:
         """Forget every memory an agent holds about one subject (GDPR-style).
 
         Hits ``POST .../memories:forgetSubject`` with ``{"subject": …}`` →
-        ``{"deletedCount": N}``. Irreversible — the CLI gates it behind a
-        confirmation.
+        ``{"deletedCount": N}``. ``subject`` is the person's participant id or
+        a channel address as ``provider:identifier``; either forgets the
+        memories filed under the participant id and under each of their
+        addresses. Irreversible — the CLI gates it behind a confirmation.
         """
         return self._post_json(self._memories_url(agent, ":forgetSubject"), {"subject": subject})
 
@@ -8031,7 +8066,6 @@ class FruxonClient:
         *,
         parameters: dict[str, object] | None,
         attachments: list[dict[str, object]] | None,
-        chat_user: dict[str, object] | None,
         session_id: str | None,
         environment_slug: str | None = None,
     ) -> dict[str, object]:
@@ -8040,8 +8074,6 @@ class FruxonClient:
             body["parameters"] = parameters
         if attachments is not None:
             body["attachments"] = attachments
-        if chat_user is not None:
-            body["chatUser"] = chat_user
         if session_id is not None:
             body["sessionId"] = session_id
         if environment_slug is not None:

{fruxon-2.2.0 → fruxon-2.2.1}/tests/test_client.py

@@ -5,6 +5,7 @@ import json
 import urllib.error
 import urllib.parse
 import urllib.request
+import warnings
 
 import pytest
 
@@ -139,7 +140,9 @@ class TestFruxonClientExecute:
         client.execute("my-agent")
         assert captured["body"] == {}
 
-    def test_maps_chat_user(self, client, monkeypatch):
+    def test_chat_user_is_deprecated_and_not_sent(self, client, monkeypatch):
+        # The execution body has no end-user field: the server dropped
+        # ``chatUser`` unread while the caller believed the user was identified.
         captured = {}
 
         def mock_urlopen(req, timeout=None, context=None):
@@ -148,8 +151,22 @@ class TestFruxonClientExecute:
 
         monkeypatch.setattr(urllib.request, "urlopen", mock_urlopen)
 
-        client.execute("my-agent", chat_user={"id": "user-1", "name": "Alice"})
-        assert captured["body"]["chatUser"] == {"id": "user-1", "name": "Alice"}
+        with pytest.warns(DeprecationWarning, match="does not identify the end user") as record:
+            client.execute("my-agent", parameters={"q": "hi"}, chat_user={"id": "user-1", "name": "Alice"})
+
+        assert captured["body"] == {"parameters": {"q": "hi"}}
+        assert len(record) == 1
+        # Attributed to the caller's line, not to the SDK.
+        assert record[0].filename == __file__
+
+    def test_no_warning_without_chat_user(self, client, monkeypatch):
+        monkeypatch.setattr(
+            urllib.request, "urlopen", lambda req, timeout=None, context=None: _MockResponse(SAMPLE_RESPONSE)
+        )
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            client.execute("my-agent", parameters={"q": "hi"})
 
     def test_maps_environment_slug(self, client, monkeypatch):
         captured = {}
@@ -485,6 +502,24 @@ class TestFruxonClientStream:
         chunks = list(client.stream_text("my-agent"))
         assert chunks == ["Hello ", "world"]
 
+    @pytest.mark.parametrize("method", ["stream", "stream_text"])
+    def test_chat_user_is_deprecated_and_not_sent(self, client, monkeypatch, method):
+        captured = {}
+
+        def mock_urlopen(req, timeout=None, context=None):
+            captured["body"] = json.loads(req.data.decode("utf-8"))
+            return self._mock_stream(self._sse_body(("text", '{"chunk": "x"}'), ("done", "{}")))
+
+        monkeypatch.setattr(urllib.request, "urlopen", mock_urlopen)
+
+        with pytest.warns(DeprecationWarning, match="does not identify the end user") as record:
+            list(getattr(client, method)("my-agent", parameters={"q": "hi"}, chat_user={"id": "user-1"}))
+
+        assert captured["body"] == {"parameters": {"q": "hi"}}
+        # stream_text rides on stream, but warns once, and from the caller's line.
+        assert len(record) == 1
+        assert record[0].filename == __file__
+
     def test_ignores_sse_comments_and_heartbeats(self, client, monkeypatch):
         # `:` lines are SSE comments — used as keep-alives by some servers.
         # Bare blank lines without a preceding event should also not yield.