strands-agents-session 0.1.0__tar.gz

strands_agents_session-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/
+uv.lock

strands_agents_session-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: strands-agents-session
+Version: 0.1.0
+Summary: Backend-agnostic session management for Strands Agents — a SessionStorage interface + KeyValueSessionManager to build session backends (DynamoDB, Redis, MongoDB, …)
+Project-URL: Homepage, https://github.com/skamalj/strands_agents_session
+Project-URL: Repository, https://github.com/skamalj/strands_agents_session.git
+Author-email: Kamal <skamalj@github.com>
+Keywords: agent-state,memory,persistence,session,session-manager,strands,strands-agents
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: strands-agents
+Description-Content-Type: text/markdown
+
+# strands-agents-session
+
+Backend-agnostic **session management** for [Strands Agents](https://strandsagents.com). Provides the shared machinery so you can build a session storage backend (DynamoDB, Redis, MongoDB, Postgres, …) by implementing just a handful of methods.
+
+This is the base package of a family. Concrete backends are shipped separately, e.g. [`strands-session-dynamodb`](https://pypi.org/project/strands-session-dynamodb/).
+
+## What it gives you
+
+- **`KeyValueSessionManager`** — implements the full Strands `SessionRepository` (all 8 CRUD methods) and mixes in `RepositorySessionManager`, so the Strands session lifecycle (message indexing, restore, `removed_message_count` offsetting, tool-use repair, change detection) is reused unchanged.
+- **`SessionStorage`** — a tiny ordered keyed-record interface (`put` / `get` / `query` / `delete` / `delete_partition`). Implement it and you have a working Strands session backend.
+- **`InMemorySessionStorage`** — a ready in-memory backend for tests and local development.
+- **`keys`** — shared key/serialization conventions (zero-padded message sort keys so `list_messages(offset, limit)` is a native ordered range scan).
+
+> **Storage only, by design.** Message *pruning* in Strands is a `ConversationManager` concern, deliberately decoupled from storage. This package (and its backends) never prune — doing so at the storage layer would corrupt Strands' message-index/offset restore logic.
+
+## Installation
+
+```bash
+pip install strands-agents-session
+```
+
+**Requires Python 3.10+.**
+
+## Using the in-memory backend
+
+```python
+from strands import Agent
+from strands_agents_session import KeyValueSessionManager, InMemorySessionStorage
+
+session_manager = KeyValueSessionManager(
+    session_id="user-123",
+    storage=InMemorySessionStorage(),
+)
+agent = Agent(session_manager=session_manager)
+```
+
+## Building a backend
+
+Implement `SessionStorage` and hand it to `KeyValueSessionManager`:
+
+```python
+from strands_agents_session import KeyValueSessionManager, SessionStorage
+
+class MyStorage(SessionStorage):
+    def put(self, item): ...                 # item = {"pk", "sk", "data"}
+    def get(self, pk, sk): ...               # -> item | None
+    def query(self, pk, sk_gte=None, limit=None): ...  # ordered by sk asc
+    def delete(self, pk, sk): ...
+    def delete_partition(self, pk): ...
+
+class MySessionManager(KeyValueSessionManager):
+    def __init__(self, session_id, **cfg):
+        super().__init__(session_id=session_id, storage=MyStorage(**cfg))
+```
+
+That's it — all the `SessionRepository` methods, restore logic, and pagination come from the base.
+
+## License
+
+MIT

strands_agents_session-0.1.0/README.md

@@ -0,0 +1,60 @@
+# strands-agents-session
+
+Backend-agnostic **session management** for [Strands Agents](https://strandsagents.com). Provides the shared machinery so you can build a session storage backend (DynamoDB, Redis, MongoDB, Postgres, …) by implementing just a handful of methods.
+
+This is the base package of a family. Concrete backends are shipped separately, e.g. [`strands-session-dynamodb`](https://pypi.org/project/strands-session-dynamodb/).
+
+## What it gives you
+
+- **`KeyValueSessionManager`** — implements the full Strands `SessionRepository` (all 8 CRUD methods) and mixes in `RepositorySessionManager`, so the Strands session lifecycle (message indexing, restore, `removed_message_count` offsetting, tool-use repair, change detection) is reused unchanged.
+- **`SessionStorage`** — a tiny ordered keyed-record interface (`put` / `get` / `query` / `delete` / `delete_partition`). Implement it and you have a working Strands session backend.
+- **`InMemorySessionStorage`** — a ready in-memory backend for tests and local development.
+- **`keys`** — shared key/serialization conventions (zero-padded message sort keys so `list_messages(offset, limit)` is a native ordered range scan).
+
+> **Storage only, by design.** Message *pruning* in Strands is a `ConversationManager` concern, deliberately decoupled from storage. This package (and its backends) never prune — doing so at the storage layer would corrupt Strands' message-index/offset restore logic.
+
+## Installation
+
+```bash
+pip install strands-agents-session
+```
+
+**Requires Python 3.10+.**
+
+## Using the in-memory backend
+
+```python
+from strands import Agent
+from strands_agents_session import KeyValueSessionManager, InMemorySessionStorage
+
+session_manager = KeyValueSessionManager(
+    session_id="user-123",
+    storage=InMemorySessionStorage(),
+)
+agent = Agent(session_manager=session_manager)
+```
+
+## Building a backend
+
+Implement `SessionStorage` and hand it to `KeyValueSessionManager`:
+
+```python
+from strands_agents_session import KeyValueSessionManager, SessionStorage
+
+class MyStorage(SessionStorage):
+    def put(self, item): ...                 # item = {"pk", "sk", "data"}
+    def get(self, pk, sk): ...               # -> item | None
+    def query(self, pk, sk_gte=None, limit=None): ...  # ordered by sk asc
+    def delete(self, pk, sk): ...
+    def delete_partition(self, pk): ...
+
+class MySessionManager(KeyValueSessionManager):
+    def __init__(self, session_id, **cfg):
+        super().__init__(session_id=session_id, storage=MyStorage(**cfg))
+```
+
+That's it — all the `SessionRepository` methods, restore logic, and pagination come from the base.
+
+## License
+
+MIT

strands_agents_session-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strands-agents-session"
+version = "0.1.0"
+description = "Backend-agnostic session management for Strands Agents — a SessionStorage interface + KeyValueSessionManager to build session backends (DynamoDB, Redis, MongoDB, …)"
+authors = [{name = "Kamal", email = "skamalj@github.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "strands-agents",
+]
+keywords = [
+    "strands", "strands-agents", "session", "agent-state", "memory",
+    "persistence", "session-manager",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/skamalj/strands_agents_session"
+Repository = "https://github.com/skamalj/strands_agents_session.git"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strands_agents_session"]

strands_agents_session-0.1.0/src/strands_agents_session/__init__.py

@@ -0,0 +1,18 @@
+"""Backend-agnostic session management for Strands Agents.
+
+Provides a ``SessionStorage`` interface and a ``KeyValueSessionManager`` that
+implements the full Strands ``SessionRepository`` over it, so new storage
+backends (DynamoDB, Redis, MongoDB, …) only need to implement a handful of
+keyed-record methods.
+"""
+
+from . import keys
+from .manager import KeyValueSessionManager
+from .storage import InMemorySessionStorage, SessionStorage
+
+__all__ = [
+    "KeyValueSessionManager",
+    "SessionStorage",
+    "InMemorySessionStorage",
+    "keys",
+]

strands_agents_session-0.1.0/src/strands_agents_session/keys.py

@@ -0,0 +1,37 @@
+"""Key construction helpers shared across session storage backends.
+
+Single-logical-table layout (keys are opaque strings, so any KV/range store fits):
+
+    Session : pk = "SESSION#<session_id>"                  sk = "META"
+    Agent   : pk = "SESSION#<session_id>"                  sk = "AGENT#<agent_id>"
+    Message : pk = "SESSION#<session_id>#AGENT#<agent_id>" sk = "MSG#<zero-padded id>"
+
+Message sort keys are zero-padded so that lexical ordering matches numeric
+ordering — making ``list_messages(offset, limit)`` a simple ordered range scan,
+matching the ``removed_message_count`` offset semantics Strands relies on.
+"""
+
+# Width for zero-padding message ids so lexical sort == numeric sort.
+MESSAGE_ID_WIDTH = 20
+
+SESSION_SK = "META"
+
+
+def session_pk(session_id: str) -> str:
+    return f"SESSION#{session_id}"
+
+
+def agent_sk(agent_id: str) -> str:
+    return f"AGENT#{agent_id}"
+
+
+def agent_id_from_sk(sk: str) -> str:
+    return sk.split("AGENT#", 1)[1]
+
+
+def messages_pk(session_id: str, agent_id: str) -> str:
+    return f"SESSION#{session_id}#AGENT#{agent_id}"
+
+
+def message_sk(message_id: int) -> str:
+    return f"MSG#{int(message_id):0{MESSAGE_ID_WIDTH}d}"

strands_agents_session-0.1.0/src/strands_agents_session/manager.py

@@ -0,0 +1,146 @@
+"""Backend-agnostic Strands session manager over a ``SessionStorage``.
+
+Implements the Strands ``SessionRepository`` (all 8 CRUD methods) in terms of a
+small ``SessionStorage`` interface, and mixes in ``RepositorySessionManager`` so
+the Strands session lifecycle (message indexing, restore, offsetting, tool-use
+repair, change detection) is reused unchanged.
+
+A concrete backend only needs to provide a ``SessionStorage`` — see
+``strands_session_dynamodb`` for an example.
+"""
+
+import json
+from typing import Any, List, Optional
+
+from strands.session.repository_session_manager import RepositorySessionManager
+from strands.session.session_repository import SessionRepository
+from strands.types.exceptions import SessionException
+from strands.types.session import Session, SessionAgent, SessionMessage
+
+from .keys import (
+    SESSION_SK,
+    agent_id_from_sk,
+    agent_sk,
+    message_sk,
+    messages_pk,
+    session_pk,
+)
+from .storage import SessionStorage
+
+
+class KeyValueSessionManager(RepositorySessionManager, SessionRepository):
+    """Strands session manager backed by any ``SessionStorage`` implementation."""
+
+    def __init__(self, session_id: str, storage: SessionStorage, **kwargs: Any) -> None:
+        self.storage = storage
+        super().__init__(session_id=session_id, session_repository=self)
+
+    # ------------------------------------------------------------------
+    # helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _record(pk: str, sk: str, payload: dict) -> dict:
+        return {"pk": pk, "sk": sk, "data": json.dumps(payload)}
+
+    # ------------------------------------------------------------------
+    # sessions
+    # ------------------------------------------------------------------
+
+    def create_session(self, session: Session, **kwargs: Any) -> Session:
+        pk = session_pk(session.session_id)
+        if self.storage.get(pk, SESSION_SK) is not None:
+            raise SessionException(f"Session {session.session_id} already exists")
+        self.storage.put(self._record(pk, SESSION_SK, session.to_dict()))
+        return session
+
+    def read_session(self, session_id: str, **kwargs: Any) -> Optional[Session]:
+        rec = self.storage.get(session_pk(session_id), SESSION_SK)
+        if rec is None:
+            return None
+        return Session.from_dict(json.loads(rec["data"]))
+
+    def delete_session(self, session_id: str, **kwargs: Any) -> None:
+        pk = session_pk(session_id)
+        items = self.storage.query(pk)
+        agent_ids = [agent_id_from_sk(i["sk"]) for i in items if i["sk"].startswith("AGENT#")]
+        for agent_id in agent_ids:
+            self.storage.delete_partition(messages_pk(session_id, agent_id))
+        self.storage.delete_partition(pk)
+
+    # ------------------------------------------------------------------
+    # agents
+    # ------------------------------------------------------------------
+
+    def create_agent(self, session_id: str, session_agent: SessionAgent, **kwargs: Any) -> None:
+        self.storage.put(
+            self._record(session_pk(session_id), agent_sk(session_agent.agent_id), session_agent.to_dict())
+        )
+
+    def read_agent(self, session_id: str, agent_id: str, **kwargs: Any) -> Optional[SessionAgent]:
+        rec = self.storage.get(session_pk(session_id), agent_sk(agent_id))
+        if rec is None:
+            return None
+        return SessionAgent.from_dict(json.loads(rec["data"]))
+
+    def update_agent(self, session_id: str, session_agent: SessionAgent, **kwargs: Any) -> None:
+        previous = self.read_agent(session_id, session_agent.agent_id)
+        if previous is None:
+            raise SessionException(
+                f"Agent {session_agent.agent_id} in session {session_id} does not exist"
+            )
+        session_agent.created_at = previous.created_at  # preserve creation timestamp
+        self.storage.put(
+            self._record(session_pk(session_id), agent_sk(session_agent.agent_id), session_agent.to_dict())
+        )
+
+    # ------------------------------------------------------------------
+    # messages
+    # ------------------------------------------------------------------
+
+    def create_message(
+        self, session_id: str, agent_id: str, session_message: SessionMessage, **kwargs: Any
+    ) -> None:
+        self.storage.put(
+            self._record(
+                messages_pk(session_id, agent_id),
+                message_sk(session_message.message_id),
+                session_message.to_dict(),
+            )
+        )
+
+    def read_message(
+        self, session_id: str, agent_id: str, message_id: int, **kwargs: Any
+    ) -> Optional[SessionMessage]:
+        rec = self.storage.get(messages_pk(session_id, agent_id), message_sk(message_id))
+        if rec is None:
+            return None
+        return SessionMessage.from_dict(json.loads(rec["data"]))
+
+    def update_message(
+        self, session_id: str, agent_id: str, session_message: SessionMessage, **kwargs: Any
+    ) -> None:
+        previous = self.read_message(session_id, agent_id, session_message.message_id)
+        if previous is None:
+            raise SessionException(f"Message {session_message.message_id} does not exist")
+        session_message.created_at = previous.created_at
+        self.storage.put(
+            self._record(
+                messages_pk(session_id, agent_id),
+                message_sk(session_message.message_id),
+                session_message.to_dict(),
+            )
+        )
+
+    def list_messages(
+        self,
+        session_id: str,
+        agent_id: str,
+        limit: Optional[int] = None,
+        offset: int = 0,
+        **kwargs: Any,
+    ) -> List[SessionMessage]:
+        records = self.storage.query(
+            messages_pk(session_id, agent_id), sk_gte=message_sk(offset), limit=limit
+        )
+        return [SessionMessage.from_dict(json.loads(r["data"])) for r in records]

strands_agents_session-0.1.0/src/strands_agents_session/storage.py

@@ -0,0 +1,69 @@
+"""Storage interface for session backends.
+
+A backend implements this small keyed-record interface; the
+``KeyValueSessionManager`` builds the full Strands ``SessionRepository`` on top
+of it. Records are plain dicts with at least ``pk``, ``sk``, and ``data`` keys
+(``data`` is a serialized payload string).
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+
+class SessionStorage(ABC):
+    """Minimal ordered keyed-record store backing a session manager."""
+
+    @abstractmethod
+    def put(self, item: Dict[str, Any]) -> None:
+        """Insert or overwrite a record. ``item`` has ``pk``, ``sk``, ``data``."""
+
+    @abstractmethod
+    def get(self, pk: str, sk: str) -> Optional[Dict[str, Any]]:
+        """Return the record for (pk, sk), or None."""
+
+    @abstractmethod
+    def query(
+        self, pk: str, sk_gte: Optional[str] = None, limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Return records under ``pk`` ordered by ``sk`` ascending.
+
+        If ``sk_gte`` is given, only records with ``sk >= sk_gte``. If ``limit``
+        is given, return at most that many.
+        """
+
+    @abstractmethod
+    def delete(self, pk: str, sk: str) -> None:
+        """Delete the record for (pk, sk) if present."""
+
+    @abstractmethod
+    def delete_partition(self, pk: str) -> None:
+        """Delete every record under ``pk``."""
+
+
+class InMemorySessionStorage(SessionStorage):
+    """In-memory storage — useful for tests and local development."""
+
+    def __init__(self) -> None:
+        self._data: Dict[str, Dict[str, Dict[str, Any]]] = {}
+
+    def put(self, item: Dict[str, Any]) -> None:
+        self._data.setdefault(item["pk"], {})[item["sk"]] = dict(item)
+
+    def get(self, pk: str, sk: str) -> Optional[Dict[str, Any]]:
+        rec = self._data.get(pk, {}).get(sk)
+        return dict(rec) if rec is not None else None
+
+    def query(
+        self, pk: str, sk_gte: Optional[str] = None, limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        partition = self._data.get(pk, {})
+        keys = sorted(k for k in partition if sk_gte is None or k >= sk_gte)
+        if limit is not None:
+            keys = keys[:limit]
+        return [dict(partition[k]) for k in keys]
+
+    def delete(self, pk: str, sk: str) -> None:
+        self._data.get(pk, {}).pop(sk, None)
+
+    def delete_partition(self, pk: str) -> None:
+        self._data.pop(pk, None)

strands_agents_session-0.1.0/tests/test_keyvalue_manager.py

@@ -0,0 +1,137 @@
+"""
+Offline tests for KeyValueSessionManager over InMemorySessionStorage.
+
+Fully deterministic, no cloud — exercises the backend-agnostic SessionRepository
+implementation (sessions, agents + agent state, messages, pagination,
+update/redaction, isolation, delete). Every concrete backend inherits this
+behavior, so these cover the shared logic once.
+"""
+import uuid
+
+import pytest
+
+from strands.types.exceptions import SessionException
+from strands.types.session import SessionAgent, SessionMessage
+from strands_agents_session import InMemorySessionStorage, KeyValueSessionManager
+
+
+def make_manager(storage=None, session_id=None):
+    return KeyValueSessionManager(
+        session_id=session_id or f"sess-{uuid.uuid4()}",
+        storage=storage or InMemorySessionStorage(),
+    )
+
+
+def msg(i, role="user", text=None):
+    return SessionMessage.from_message({"role": role, "content": [{"text": text or f"m{i}"}]}, i)
+
+
+# sessions ------------------------------------------------------------------
+
+def test_session_created_on_init():
+    mgr = make_manager()
+    got = mgr.read_session(mgr.session_id)
+    assert got is not None and got.session_id == mgr.session_id
+
+
+def test_create_duplicate_session_raises():
+    mgr = make_manager()
+    with pytest.raises(SessionException):
+        mgr.create_session(mgr.session)
+
+
+def test_read_missing_session_returns_none():
+    assert make_manager().read_session("nope") is None
+
+
+def test_delete_session_removes_everything():
+    storage = InMemorySessionStorage()
+    mgr = make_manager(storage)
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    mgr.create_message(sid, "a1", msg(0))
+    mgr.delete_session(sid)
+    assert mgr.read_session(sid) is None
+    assert mgr.read_agent(sid, "a1") is None
+    assert mgr.list_messages(sid, "a1") == []
+
+
+# agents (+ state) ----------------------------------------------------------
+
+def test_agent_state_round_trip():
+    mgr = make_manager()
+    mgr.create_agent(mgr.session_id, SessionAgent(
+        agent_id="assistant", state={"tier": "gold"}, conversation_manager_state={"removed_message_count": 0}))
+    got = mgr.read_agent(mgr.session_id, "assistant")
+    assert got.state == {"tier": "gold"}
+    assert got.conversation_manager_state == {"removed_message_count": 0}
+
+
+def test_update_agent_preserves_created_at():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={"v": 1}, conversation_manager_state={}))
+    created_at = mgr.read_agent(sid, "a1").created_at
+    mgr.update_agent(sid, SessionAgent(agent_id="a1", state={"v": 2}, conversation_manager_state={}))
+    got = mgr.read_agent(sid, "a1")
+    assert got.state == {"v": 2}
+    assert got.created_at == created_at
+
+
+def test_update_missing_agent_raises():
+    mgr = make_manager()
+    with pytest.raises(SessionException):
+        mgr.update_agent(mgr.session_id, SessionAgent(agent_id="x", state={}, conversation_manager_state={}))
+
+
+# messages + pagination -----------------------------------------------------
+
+def test_message_round_trip():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    mgr.create_message(sid, "a1", msg(0, text="hello"))
+    got = mgr.read_message(sid, "a1", 0)
+    assert got.message["content"][0]["text"] == "hello"
+
+
+def test_list_messages_sorted():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    for i in [2, 0, 4, 1, 3]:
+        mgr.create_message(sid, "a1", msg(i))
+    assert [m.message_id for m in mgr.list_messages(sid, "a1")] == [0, 1, 2, 3, 4]
+
+
+def test_list_messages_offset_and_limit():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    for i in range(10):
+        mgr.create_message(sid, "a1", msg(i))
+    assert [m.message_id for m in mgr.list_messages(sid, "a1", offset=2)] == [2, 3, 4, 5, 6, 7, 8, 9]
+    assert [m.message_id for m in mgr.list_messages(sid, "a1", limit=3)] == [0, 1, 2]
+    assert [m.message_id for m in mgr.list_messages(sid, "a1", offset=3, limit=4)] == [3, 4, 5, 6]
+
+
+def test_update_message_redaction():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    m = msg(0, text="secret")
+    mgr.create_message(sid, "a1", m)
+    m.redact_message = {"role": "user", "content": [{"text": "[REDACTED]"}]}
+    mgr.update_message(sid, "a1", m)
+    got = mgr.read_message(sid, "a1", 0)
+    assert got.redact_message["content"][0]["text"] == "[REDACTED]"
+
+
+def test_sessions_isolated():
+    storage = InMemorySessionStorage()
+    m1 = make_manager(storage)
+    m2 = make_manager(storage)
+    m1.create_agent(m1.session_id, SessionAgent(agent_id="a", state={"who": "one"}, conversation_manager_state={}))
+    m2.create_agent(m2.session_id, SessionAgent(agent_id="a", state={"who": "two"}, conversation_manager_state={}))
+    assert m1.read_agent(m1.session_id, "a").state == {"who": "one"}
+    assert m2.read_agent(m2.session_id, "a").state == {"who": "two"}