redis-iris 0.1.0a1__py3-none-any.whl

redis_iris/__init__.py

@@ -0,0 +1,21 @@
+"""Redis Iris: the goal-level toolkit for the Iris products.
+
+``iris-sdks`` publishes one generated client per service; this package wraps what an agent
+developer is trying to do with them (``AgentMemory``, ``Playbook``, ``ContextRetriever``) with
+smart defaults, one ``IRIS_*`` configuration model, and the ``iris`` command line. Start with the
+product you need; ``Iris`` gathers them when the second one arrives.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from redis_iris.agent_memory import AgentMemory
+from redis_iris.context_retriever import ContextRetriever
+from redis_iris.iris import Iris, IrisSettings
+from redis_iris.playbook import Playbook
+
+try:
+    __version__ = version("redis-iris")
+except PackageNotFoundError:  # pragma: no cover - source trees are normally installed by uv
+    __version__ = "0.0.0"
+
+__all__ = ["AgentMemory", "ContextRetriever", "Iris", "IrisSettings", "Playbook", "__version__"]

redis_iris/__main__.py

@@ -0,0 +1,6 @@
+"""Run the CLI with ``python -m redis_iris``."""
+
+from redis_iris.cli.main import main
+
+if __name__ == "__main__":
+    main()

redis_iris/_settings.py

@@ -0,0 +1,30 @@
+"""Read product settings from ``IRIS_*`` environment variables."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from redis_iris.errors import ConfigurationError
+
+DEFAULT_TIMEOUT = 30.0  # seconds, every product
+
+
+def env_value(environ: Mapping[str, str] | None, name: str) -> str | None:
+    """Return the stripped value of ``name`` or None when unset or blank."""
+
+    source = os.environ if environ is None else environ
+    value = source.get(name, "").strip()
+    return value or None
+
+
+def env_float(environ: Mapping[str, str] | None, name: str, default: float) -> float:
+    """Return ``name`` as a float, ``default`` when unset. Non-numeric values are a config error."""
+
+    value = env_value(environ, name)
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        raise ConfigurationError(f"{name} must be a number, got {value!r}") from None

redis_iris/agent_memory/__init__.py

@@ -0,0 +1,43 @@
+"""Agent Memory the way an agent developer thinks about it.
+
+An agent has *conversations* with an *owner* (a user, a customer). Before it answers, it
+*recalls* what it knows about them and what the team knows today. Afterwards it *remembers*.
+When the owner asks, it *forgets* everything about them. Those are the verbs here.
+
+The full ``redis_agent_memory`` client is always one attribute away as ``AgentMemory.client``.
+Everything below is sensible defaults over it:
+
+* ownership scoping on every read, so one customer never sees another's memories;
+* shared namespaces (hierarchical memory) for what every conversation may read;
+* session ids the store accepts, derived from the owner when you do not supply one;
+* deterministic memory ids, so re-running a seed does not duplicate memories;
+* one ``Recall`` object that renders straight into a prompt.
+
+Sync methods for scripts and notebooks; ``a``-prefixed twins for async agents.
+
+Layout: ``memory`` (the goal object), ``conversation``, ``hooks`` (``before`` / ``after`` for
+any framework), ``values`` (what calls return), ``ids``, ``settings`` (``IRIS_AGENT_MEMORY_*``
+and the client factory). ``_wire`` is private.
+"""
+
+from redis_iris.agent_memory.conversation import Conversation
+from redis_iris.agent_memory.hooks import MemoryHooks
+from redis_iris.agent_memory.ids import memory_id_for, safe_id, session_id_for
+from redis_iris.agent_memory.memory import AgentMemory
+from redis_iris.agent_memory.settings import AgentMemorySettings, connect
+from redis_iris.agent_memory.values import Forgotten, Memory, Recall, Transcript
+
+__all__ = [
+    "AgentMemory",
+    "AgentMemorySettings",
+    "Conversation",
+    "Forgotten",
+    "Memory",
+    "MemoryHooks",
+    "Recall",
+    "Transcript",
+    "connect",
+    "memory_id_for",
+    "safe_id",
+    "session_id_for",
+]

redis_iris/agent_memory/_wire.py

@@ -0,0 +1,47 @@
+"""Translation to and from the generated ``redis_agent_memory`` client. Private."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from redis_iris.agent_memory.ids import memory_id_for
+from redis_iris.agent_memory.values import Memory, Transcript
+
+
+def memory(record: Any) -> Memory:
+    return Memory(
+        id=str(record.id),
+        text=str(record.text),
+        owner=getattr(record, "owner_id", None),
+        shared=getattr(record, "namespace_ref", None) is not None,
+        topics=tuple(getattr(record, "topics", None) or ()),
+    )
+
+
+def search_request(query: str, filter_: dict[str, Any], limit: int) -> Any:
+    return {"text": query, "filter_": filter_, "limit": limit}
+
+
+def memory_record(
+    text: str, owner: str, topics: Iterable[str], namespace_id: str | None, memory_id: str | None
+) -> Any:
+    record: dict[str, Any] = {
+        "id": memory_id or memory_id_for(owner, text),
+        "text": text,
+        "owner_id": owner,
+        "topics": list(topics) or None,
+    }
+    if namespace_id:
+        record["namespace_ref"] = {"namespace_id": namespace_id}
+    return record
+
+
+def transcript(session_id: str, response: Any) -> Transcript:
+    turns = []
+    for event in response.events:
+        role = getattr(event.role, "value", str(event.role)).lower()
+        text = " ".join(part.text for part in event.content if getattr(part, "text", None))
+        turns.append((role, text))
+    summary = response.summary.text if response.summary else None
+    return Transcript(session_id=session_id, turns=tuple(turns), summary=summary)

redis_iris/agent_memory/conversation.py

@@ -0,0 +1,81 @@
+"""One session between an owner and the assistant."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from redis_iris.agent_memory import _wire
+from redis_iris.agent_memory.values import Transcript
+
+if TYPE_CHECKING:
+    from redis_iris.agent_memory.memory import AgentMemory
+
+
+class Conversation:
+    """One session between an owner and the assistant. Every message is a session event."""
+
+    def __init__(
+        self,
+        memory: AgentMemory,
+        owner: str,
+        session_id: str,
+        namespace_id: str | None = None,
+    ) -> None:
+        self.memory = memory
+        self.owner = owner
+        self.session_id = session_id
+        self.namespace_id = namespace_id
+
+    def _event(self, actor_id: str, role: str, text: str) -> dict[str, Any]:
+        from redis_agent_memory import models
+
+        event: dict[str, Any] = {
+            "session_id": self.session_id,
+            "actor_id": actor_id,
+            "role": models.MessageRole[role.upper()],
+            "content": [{"text": text}],
+            "created_at": datetime.now(UTC),
+        }
+        if self.namespace_id:
+            event["namespace_ref"] = {"namespace_id": self.namespace_id}
+        return event
+
+    def user(self, text: str) -> None:
+        """The owner said something."""
+
+        self.memory.client.add_session_event(**self._event(self.owner, "user", text))
+
+    def assistant(self, text: str) -> None:
+        """The assistant answered."""
+
+        self.memory.client.add_session_event(
+            **self._event(self.memory.assistant_id, "assistant", text)
+        )
+
+    def transcript(self) -> Transcript:
+        """The session as stored, with the summary once the store has written one."""
+
+        return _wire.transcript(
+            self.session_id, self.memory.client.get_session_memory(session_id=self.session_id)
+        )
+
+    async def auser(self, text: str) -> None:
+        """Async ``user``."""
+
+        await self.memory.client.add_session_event_async(**self._event(self.owner, "user", text))
+
+    async def aassistant(self, text: str) -> None:
+        """Async ``assistant``."""
+
+        await self.memory.client.add_session_event_async(
+            **self._event(self.memory.assistant_id, "assistant", text)
+        )
+
+    async def atranscript(self) -> Transcript:
+        """Async ``transcript``."""
+
+        return _wire.transcript(
+            self.session_id,
+            await self.memory.client.get_session_memory_async(session_id=self.session_id),
+        )

redis_iris/agent_memory/hooks.py

@@ -0,0 +1,55 @@
+"""The two calls every framework adapter makes. Write your own adapter against these."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from redis_iris.agent_memory.memory import AgentMemory
+
+
+class MemoryHooks:
+    """Agent Memory as two hooks: ``before`` the model runs, ``after`` the turn ends.
+
+    ```python
+    hooks = memory.hooks(shared=["support-floor"])
+    system = f"{SYSTEM}\\n\\n{hooks.before(message, owner=user_id)}"
+    answer = call_model(system, message)              # your framework
+    hooks.after(message, answer, owner=user_id, session=thread_id)
+    ```
+
+    ``redis_iris.integrations.<framework>.attach`` is this pair placed at that framework's own
+    hook points. Any framework with a "before the model" and an "after the turn" seam fits.
+    """
+
+    name = "memory"
+
+    def __init__(self, memory: AgentMemory, *, shared: Iterable[str] = ()) -> None:
+        self.memory = memory
+        self.floors = [memory.shared_namespace(name) for name in shared]  # resolved once
+
+    def before(self, message: str, *, owner: str, session: str | None = None) -> str:
+        """What the agent knows about ``owner`` for this message, as a system-prompt block."""
+
+        return self.memory.recall(message, owner=owner, shared=self.floors).as_prompt()
+
+    def after(self, message: str, answer: str, *, owner: str, session: str) -> None:
+        """Record one exchange; the service extracts long-term memories from it."""
+
+        convo = self.memory.conversation(owner=owner, session_id=session)
+        convo.user(message)
+        convo.assistant(answer)
+
+    async def abefore(self, message: str, *, owner: str, session: str | None = None) -> str:
+        """Async ``before``."""
+
+        known = await self.memory.arecall(message, owner=owner, shared=self.floors)
+        return known.as_prompt()
+
+    async def aafter(self, message: str, answer: str, *, owner: str, session: str) -> None:
+        """Async ``after``."""
+
+        convo = self.memory.conversation(owner=owner, session_id=session)
+        await convo.auser(message)
+        await convo.aassistant(answer)

redis_iris/agent_memory/ids.py

@@ -0,0 +1,27 @@
+"""Identifiers the store accepts: session ids from owners, deterministic memory ids."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import UTC, datetime
+
+
+def session_id_for(owner: str, at: datetime | None = None) -> str:
+    """A session id the store accepts (alphanumerics and hyphens), unique per owner and time."""
+
+    stamp = (at or datetime.now(UTC)).strftime("%Y%m%d%H%M%S")
+    return safe_id(f"{owner}-{stamp}")
+
+
+def safe_id(value: str) -> str:
+    """``value`` with every run of characters the store rejects replaced by one hyphen."""
+
+    return re.sub(r"[^A-Za-z0-9-]+", "-", value).strip("-")
+
+
+def memory_id_for(owner: str, text: str) -> str:
+    """Deterministic, so remembering the same fact twice is a no-op instead of a duplicate."""
+
+    digest = hashlib.sha1(f"{owner}\n{text.strip()}".encode()).hexdigest()
+    return f"mem-{digest[:24]}"

redis_iris/agent_memory/memory.py

@@ -0,0 +1,309 @@
+"""``AgentMemory``: conversations, recall, remember and forget over Redis Agent Memory."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterable, Mapping
+from typing import TYPE_CHECKING, Any
+
+from redis_iris.agent_memory import _wire
+from redis_iris.agent_memory.conversation import Conversation
+from redis_iris.agent_memory.ids import safe_id, session_id_for
+from redis_iris.agent_memory.settings import AgentMemorySettings, connect
+from redis_iris.agent_memory.values import Forgotten, Memory, Recall
+
+if TYPE_CHECKING:
+    from redis_agent_memory import AgentMemory as AgentMemoryClient
+
+    from redis_iris.agent_memory.hooks import MemoryHooks
+
+
+class AgentMemory:
+    """Plug Redis Agent Memory into an agent you already have.
+
+    ```python
+    memory = AgentMemory.from_env()
+    floor = memory.shared_namespace("support-floor")
+    convo = memory.conversation(owner="cust-1042")
+    known = memory.recall("dispute", owner="cust-1042", shared=[floor])
+    ...  # answer with known.as_prompt() in the system prompt
+    convo.user(message); convo.assistant(answer)
+    ```
+    """
+
+    def __init__(
+        self,
+        settings: AgentMemorySettings | None = None,
+        *,
+        assistant_id: str = "assistant",
+        client: AgentMemoryClient | None = None,
+    ) -> None:
+        self.settings = settings or AgentMemorySettings()
+        self.assistant_id = assistant_id
+        self._client = client
+
+    @classmethod
+    def from_env(
+        cls, environ: Mapping[str, str] | None = None, *, assistant_id: str = "assistant"
+    ) -> AgentMemory:
+        """Settings from ``IRIS_AGENT_MEMORY_*``; ``assistant_id`` names the agent in sessions."""
+
+        return cls(AgentMemorySettings.from_env(environ), assistant_id=assistant_id)
+
+    @property
+    def client(self) -> AgentMemoryClient:
+        """The generated ``redis_agent_memory`` client: everything this module does not wrap."""
+
+        if self._client is None:
+            self._client = connect(self.settings)
+        return self._client
+
+    def __enter__(self) -> AgentMemory:
+        self.client.__enter__()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.client.__exit__(*exc)
+
+    async def __aenter__(self) -> AgentMemory:
+        await self.client.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.client.__aexit__(*exc)
+
+    # hooks for any framework
+
+    def hooks(self, *, shared: Iterable[str] = ()) -> MemoryHooks:
+        """``before`` / ``after`` for the two seams every agent framework has."""
+
+        from redis_iris.agent_memory.hooks import MemoryHooks
+
+        return MemoryHooks(self, shared=shared)
+
+    # conversations
+
+    def conversation(
+        self, owner: str, session_id: str | None = None, *, namespace_id: str | None = None
+    ) -> Conversation:
+        """Start or continue a session.
+
+        Without ``session_id`` a new session starts, named from the owner and the current time.
+        Keep ``Conversation.session_id`` and pass it back to continue the same session later.
+        """
+
+        return Conversation(self, owner, safe_id(session_id or session_id_for(owner)), namespace_id)
+
+    # namespaces
+
+    def _find_shared(self, response: Any, name: str) -> str | None:
+        return next((str(ns.namespace_id) for ns in response.items if ns.name == name), None)
+
+    def shared_namespace(self, name: str) -> str:
+        """Get or create a SHARED namespace by name and return its id. Idempotent."""
+
+        from redis_agent_memory import models
+
+        page = self.client.list_namespaces(scope=models.NamespaceScope.SHARED)
+        found = self._find_shared(page, name)
+        if found:
+            return found
+        created = self.client.create_namespace(
+            request={"name": name, "scope": models.NamespaceScope.SHARED}
+        )
+        return str(created.namespace.namespace_id)
+
+    async def ashared_namespace(self, name: str) -> str:
+        """Async ``shared_namespace``."""
+
+        from redis_agent_memory import models
+
+        page = await self.client.list_namespaces_async(scope=models.NamespaceScope.SHARED)
+        found = self._find_shared(page, name)
+        if found:
+            return found
+        created = await self.client.create_namespace_async(
+            request={"name": name, "scope": models.NamespaceScope.SHARED}
+        )
+        return str(created.namespace.namespace_id)
+
+    # recall
+
+    def _recall_requests(
+        self, query: str, owner: str, shared: Iterable[str], limit: int
+    ) -> list[Any]:
+        requests = [_wire.search_request(query, {"owner_id": {"eq": owner}}, limit)]
+        requests += [
+            _wire.search_request(query, {"namespace_ref": {"eq": namespace_id}}, limit)
+            for namespace_id in shared
+        ]
+        return requests
+
+    @staticmethod
+    def _recall(memories: Iterable[Memory]) -> Recall:
+        # A memory that is both owned and in a shared namespace matches two searches; keep one.
+        unique: dict[str, Memory] = {}
+        for memory in memories:
+            unique.setdefault(memory.id, memory)
+        return Recall(tuple(unique.values()))
+
+    def recall(
+        self, query: str, *, owner: str, shared: Iterable[str] = (), limit: int = 5
+    ) -> Recall:
+        """What the agent may know: the owner's memories, then each shared namespace.
+
+        One search per source, up to ``limit`` each, de-duplicated by memory id.
+        """
+
+        memories: list[Memory] = []
+        for request in self._recall_requests(query, owner, shared, limit):
+            memories += [
+                _wire.memory(r) for r in self.client.search_long_term_memory(request=request).items
+            ]
+        return self._recall(memories)
+
+    async def arecall(
+        self, query: str, *, owner: str, shared: Iterable[str] = (), limit: int = 5
+    ) -> Recall:
+        """Async ``recall``. The searches are independent, so they run at once."""
+
+        pages = await asyncio.gather(
+            *(
+                self.client.search_long_term_memory_async(request=request)
+                for request in self._recall_requests(query, owner, shared, limit)
+            )
+        )
+        # gather keeps request order, so the owner's memories still come first.
+        return self._recall(_wire.memory(r) for page in pages for r in page.items)
+
+    # remember
+
+    def remember(
+        self,
+        text: str,
+        *,
+        owner: str,
+        topics: Iterable[str] = (),
+        namespace_id: str | None = None,
+        memory_id: str | None = None,
+    ) -> Memory:
+        """Write one long-term memory explicitly; the store also extracts them from sessions."""
+
+        record = _wire.memory_record(text, owner, topics, namespace_id, memory_id)
+        self.client.bulk_create_long_term_memories(memories=[record])
+        return Memory(record["id"], text, owner, namespace_id is not None, tuple(topics))
+
+    async def aremember(
+        self,
+        text: str,
+        *,
+        owner: str,
+        topics: Iterable[str] = (),
+        namespace_id: str | None = None,
+        memory_id: str | None = None,
+    ) -> Memory:
+        """Async ``remember``."""
+
+        record = _wire.memory_record(text, owner, topics, namespace_id, memory_id)
+        await self.client.bulk_create_long_term_memories_async(memories=[record])
+        return Memory(record["id"], text, owner, namespace_id is not None, tuple(topics))
+
+    # inventory and erasure
+
+    @staticmethod
+    def _inventory_request(owner: str, token: str | None) -> Any:
+        request: Any = {"filter_": {"owner_id": {"eq": owner}}, "limit": 100}
+        if token:
+            request["page_token"] = token
+        return request
+
+    def memories(self, owner: str) -> list[Memory]:
+        """Every long-term memory the owner holds, seeded or extracted."""
+
+        items: list[Memory] = []
+        token = None
+        while True:
+            page = self.client.search_long_term_memory(
+                request=self._inventory_request(owner, token)
+            )
+            items += [_wire.memory(r) for r in page.items]
+            token = page.next_page_token
+            if not token:
+                return items
+
+    async def amemories(self, owner: str) -> list[Memory]:
+        """Async ``memories``."""
+
+        items: list[Memory] = []
+        token = None
+        while True:
+            page = await self.client.search_long_term_memory_async(
+                request=self._inventory_request(owner, token)
+            )
+            items += [_wire.memory(r) for r in page.items]
+            token = page.next_page_token
+            if not token:
+                return items
+
+    def sessions(self, owner: str) -> list[str]:
+        """Every session id the owner holds."""
+
+        ids: list[str] = []
+        token = None
+        while True:
+            page = self.client.list_sessions(filter_owner_id=owner, limit=100, page_token=token)
+            ids.extend(page.items)
+            token = page.next_page_token
+            if not token:
+                return ids
+
+    async def asessions(self, owner: str) -> list[str]:
+        """Async ``sessions``."""
+
+        ids: list[str] = []
+        token = None
+        while True:
+            page = await self.client.list_sessions_async(
+                filter_owner_id=owner, limit=100, page_token=token
+            )
+            ids.extend(page.items)
+            token = page.next_page_token
+            if not token:
+                return ids
+
+    def forget(self, owner: str) -> Forgotten:
+        """Right to erasure: every session and long-term memory the owner holds."""
+
+        sessions = self.sessions(owner)
+        memories = self.memories(owner)
+        for session_id in sessions:
+            self.client.delete_session_memory(session_id=session_id)
+        if memories:
+            self.client.bulk_delete_long_term_memories(memory_ids=[m.id for m in memories])
+        return Forgotten(owner, len(sessions), len(memories))
+
+    async def aforget(self, owner: str) -> Forgotten:
+        """Async ``forget``. The two inventory reads are independent, so they run at once."""
+
+        sessions, memories = await asyncio.gather(self.asessions(owner), self.amemories(owner))
+        for session_id in sessions:
+            await self.client.delete_session_memory_async(session_id=session_id)
+        if memories:
+            await self.client.bulk_delete_long_term_memories_async(
+                memory_ids=[m.id for m in memories]
+            )
+        return Forgotten(owner, len(sessions), len(memories))
+
+    def delete(self, memory_ids: Iterable[str]) -> None:
+        """Delete specific long-term memories by id. Empty input is a no-op."""
+
+        ids = list(memory_ids)
+        if ids:
+            self.client.bulk_delete_long_term_memories(memory_ids=ids)
+
+    async def adelete(self, memory_ids: Iterable[str]) -> None:
+        """Async ``delete``."""
+
+        ids = list(memory_ids)
+        if ids:
+            await self.client.bulk_delete_long_term_memories_async(memory_ids=ids)