strands_session_mongodb 0.1.0__tar.gz

strands_session_mongodb-0.1.0/.gitignore

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

strands_session_mongodb-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: strands_session_mongodb
+Version: 0.1.0
+Summary: MongoDB session manager (storage backend) for Strands Agents — persists sessions, agent state, and messages
+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,mongodb,persistence,session,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: pymongo
+Requires-Dist: strands-agents
+Requires-Dist: strands-agents-session>=0.1.0
+Description-Content-Type: text/markdown
+
+# strands-session-mongodb
+
+MongoDB **session manager** (storage backend) for [Strands Agents](https://strandsagents.com). Persists an agent's sessions, agent state, conversation-manager state, and messages to MongoDB so conversations resume across runs.
+
+Part of the [`strands-agents-session`](https://pypi.org/project/strands-agents-session/) family — it implements the base `SessionStorage` interface, so all the Strands session-repository logic (message indexing, restore, `removed_message_count` offsetting, tool-use repair) comes from the core.
+
+> **Storage only, by design.** Message *pruning* in Strands is a `ConversationManager` concern, decoupled from storage. This package does not prune.
+
+## Installation
+
+```bash
+pip install strands-session-mongodb
+# or, via the family's extra:
+pip install "strands-agents-session[mongodb]"
+```
+
+**Requires Python 3.10+** and a reachable MongoDB (local, Atlas, or self-hosted).
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_session_mongodb import MongoDBSessionManager
+
+session_manager = MongoDBSessionManager(
+    session_id="user-123",
+    connection_string="mongodb://127.0.0.1:27017/",
+)
+
+agent = Agent(session_manager=session_manager)
+agent("Hi, I'm Kamal")
+agent("What's my name?")   # remembers within the session
+```
+
+Next run, same `session_id` → the agent restores its full history and state from MongoDB.
+
+## API
+
+### `MongoDBSessionManager(session_id, *, connection_string="mongodb://127.0.0.1:27017/", database_name="strands_sessions", collection_name="sessions", client=None, ttl_seconds=None)`
+
+| Parameter | Description |
+|---|---|
+| `session_id` | Session identifier |
+| `connection_string` | MongoDB URI (local, Atlas `mongodb+srv://…`, etc.) |
+| `database_name` | Database (default `strands_sessions`) |
+| `collection_name` | Collection (default `sessions`) |
+| `client` | Optional pre-built `pymongo.MongoClient` to reuse |
+| `ttl_seconds` | If set, adds a TTL index so documents expire automatically |
+
+## Data model
+
+A single collection; each document has a `pk` + `sk` (compound-indexed, unique) and a `data` field with the serialized payload:
+
+| Item | pk | sk |
+|---|---|---|
+| Session | `SESSION#<session_id>` | `META` |
+| Agent | `SESSION#<session_id>` | `AGENT#<agent_id>` |
+| Message | `SESSION#<session_id>#AGENT#<agent_id>` | `MSG#<zero-padded id>` |
+
+The `(pk, sk)` index gives ordered range scans, so `list_messages(offset, limit)` is a simple indexed `find(...).sort(sk).limit(...)` — matching the `removed_message_count` offset semantics Strands relies on.
+
+## License
+
+MIT

strands_session_mongodb-0.1.0/README.md

@@ -0,0 +1,64 @@
+# strands-session-mongodb
+
+MongoDB **session manager** (storage backend) for [Strands Agents](https://strandsagents.com). Persists an agent's sessions, agent state, conversation-manager state, and messages to MongoDB so conversations resume across runs.
+
+Part of the [`strands-agents-session`](https://pypi.org/project/strands-agents-session/) family — it implements the base `SessionStorage` interface, so all the Strands session-repository logic (message indexing, restore, `removed_message_count` offsetting, tool-use repair) comes from the core.
+
+> **Storage only, by design.** Message *pruning* in Strands is a `ConversationManager` concern, decoupled from storage. This package does not prune.
+
+## Installation
+
+```bash
+pip install strands-session-mongodb
+# or, via the family's extra:
+pip install "strands-agents-session[mongodb]"
+```
+
+**Requires Python 3.10+** and a reachable MongoDB (local, Atlas, or self-hosted).
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_session_mongodb import MongoDBSessionManager
+
+session_manager = MongoDBSessionManager(
+    session_id="user-123",
+    connection_string="mongodb://127.0.0.1:27017/",
+)
+
+agent = Agent(session_manager=session_manager)
+agent("Hi, I'm Kamal")
+agent("What's my name?")   # remembers within the session
+```
+
+Next run, same `session_id` → the agent restores its full history and state from MongoDB.
+
+## API
+
+### `MongoDBSessionManager(session_id, *, connection_string="mongodb://127.0.0.1:27017/", database_name="strands_sessions", collection_name="sessions", client=None, ttl_seconds=None)`
+
+| Parameter | Description |
+|---|---|
+| `session_id` | Session identifier |
+| `connection_string` | MongoDB URI (local, Atlas `mongodb+srv://…`, etc.) |
+| `database_name` | Database (default `strands_sessions`) |
+| `collection_name` | Collection (default `sessions`) |
+| `client` | Optional pre-built `pymongo.MongoClient` to reuse |
+| `ttl_seconds` | If set, adds a TTL index so documents expire automatically |
+
+## Data model
+
+A single collection; each document has a `pk` + `sk` (compound-indexed, unique) and a `data` field with the serialized payload:
+
+| Item | pk | sk |
+|---|---|---|
+| Session | `SESSION#<session_id>` | `META` |
+| Agent | `SESSION#<session_id>` | `AGENT#<agent_id>` |
+| Message | `SESSION#<session_id>#AGENT#<agent_id>` | `MSG#<zero-padded id>` |
+
+The `(pk, sk)` index gives ordered range scans, so `list_messages(offset, limit)` is a simple indexed `find(...).sort(sk).limit(...)` — matching the `removed_message_count` offset semantics Strands relies on.
+
+## License
+
+MIT

strands_session_mongodb-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strands_session_mongodb"
+version = "0.1.0"
+description = "MongoDB session manager (storage backend) for Strands Agents — persists sessions, agent state, and messages"
+authors = [{name = "Kamal", email = "skamalj@github.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "strands-agents-session>=0.1.0",
+    "strands-agents",
+    "pymongo",
+]
+keywords = [
+    "strands", "strands-agents", "session", "mongodb",
+    "agent-state", "memory", "persistence",
+]
+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"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strands_session_mongodb"]

strands_session_mongodb-0.1.0/src/strands_session_mongodb/__init__.py

@@ -0,0 +1,5 @@
+"""MongoDB session backend for Strands Agents."""
+
+from .session_manager import MongoDBSessionManager, MongoDBSessionStorage
+
+__all__ = ["MongoDBSessionManager", "MongoDBSessionStorage"]

strands_session_mongodb-0.1.0/src/strands_session_mongodb/session_manager.py

@@ -0,0 +1,102 @@
+"""MongoDB session backend for Strands Agents.
+
+Provides a ``MongoDBSessionStorage`` (implementing the ``SessionStorage``
+interface from ``strands-agents-session``) and a thin ``MongoDBSessionManager``
+that wires it into ``KeyValueSessionManager``. All the session-repository logic
+lives in the base package; this module is just the storage layer.
+
+Records are stored in a single collection with a compound ``_id`` of the form
+``{pk, sk}``, and a ``data`` field holding the serialized payload. A compound
+index on ``(pk, sk)`` gives ordered range scans for ``list_messages``.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pymongo import ASCENDING, MongoClient
+
+from strands_agents_session import KeyValueSessionManager, SessionStorage
+
+
+class MongoDBSessionStorage(SessionStorage):
+    """MongoDB implementation of the session ``SessionStorage`` interface."""
+
+    def __init__(
+        self,
+        *,
+        connection_string: str = "mongodb://127.0.0.1:27017/",
+        database_name: str = "strands_sessions",
+        collection_name: str = "sessions",
+        client: Optional[MongoClient] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> None:
+        self.client = client or MongoClient(connection_string)
+        self.collection = self.client[database_name][collection_name]
+        # Compound index on (pk, sk) — unique identity + ordered range scans.
+        self.collection.create_index([("pk", ASCENDING), ("sk", ASCENDING)], unique=True)
+        self.ttl_seconds = ttl_seconds
+        if ttl_seconds:
+            # MongoDB TTL index expires documents `ttl_seconds` after `created_at`.
+            self.collection.create_index("created_at", expireAfterSeconds=ttl_seconds)
+
+    # SessionStorage ----------------------------------------------------
+
+    def put(self, item: Dict[str, Any]) -> None:
+        doc = {"pk": item["pk"], "sk": item["sk"], "data": item["data"]}
+        if self.ttl_seconds:
+            import datetime
+
+            doc["created_at"] = datetime.datetime.now(datetime.timezone.utc)
+        self.collection.replace_one({"pk": item["pk"], "sk": item["sk"]}, doc, upsert=True)
+
+    def get(self, pk: str, sk: str) -> Optional[Dict[str, Any]]:
+        doc = self.collection.find_one({"pk": pk, "sk": sk})
+        if doc is None:
+            return None
+        return {"pk": doc["pk"], "sk": doc["sk"], "data": doc["data"]}
+
+    def query(
+        self, pk: str, sk_gte: Optional[str] = None, limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        query: Dict[str, Any] = {"pk": pk}
+        if sk_gte is not None:
+            query["sk"] = {"$gte": sk_gte}
+        cursor = self.collection.find(query).sort("sk", ASCENDING)
+        if limit is not None:
+            cursor = cursor.limit(limit)
+        return [{"pk": d["pk"], "sk": d["sk"], "data": d["data"]} for d in cursor]
+
+    def delete(self, pk: str, sk: str) -> None:
+        self.collection.delete_one({"pk": pk, "sk": sk})
+
+    def delete_partition(self, pk: str) -> None:
+        self.collection.delete_many({"pk": pk})
+
+
+class MongoDBSessionManager(KeyValueSessionManager):
+    """MongoDB-backed session manager for Strands Agents.
+
+        agent = Agent(session_manager=MongoDBSessionManager(
+            session_id="user-123",
+            connection_string="mongodb://127.0.0.1:27017/",
+        ))
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        connection_string: str = "mongodb://127.0.0.1:27017/",
+        database_name: str = "strands_sessions",
+        collection_name: str = "sessions",
+        client: Optional[MongoClient] = None,
+        ttl_seconds: Optional[int] = None,
+        **kwargs: Any,
+    ) -> None:
+        storage = MongoDBSessionStorage(
+            connection_string=connection_string,
+            database_name=database_name,
+            collection_name=collection_name,
+            client=client,
+            ttl_seconds=ttl_seconds,
+        )
+        super().__init__(session_id=session_id, storage=storage)

strands_session_mongodb-0.1.0/tests/test_agent_llm.py

@@ -0,0 +1,81 @@
+"""
+End-to-end tests: a real Strands Agent (OpenAI gpt-4o-mini) persisting to a real
+MongoDB via MongoDBSessionManager, then restoring in a fresh manager.
+
+Requires:
+  - A reachable MongoDB (MONGO_URI, default mongodb://127.0.0.1:27017/)
+  - OPENAI_API_KEY
+"""
+import os
+import uuid
+
+import pytest
+
+from strands import Agent
+from strands.models.openai import OpenAIModel
+
+from strands_session_mongodb import MongoDBSessionManager
+
+MONGO_URI = os.environ.get("MONGO_URI", "mongodb://127.0.0.1:27017/")
+DB = os.environ.get("MONGO_TEST_DB", "strands_sessions_test")
+OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")
+
+pytestmark = pytest.mark.skipif(not OPENAI_API_KEY, reason="OPENAI_API_KEY not set")
+
+
+def make_model():
+    return OpenAIModel(
+        client_args={"api_key": OPENAI_API_KEY},
+        model_id="gpt-4o-mini",
+        params={"temperature": 0},
+    )
+
+
+def make_manager(session_id):
+    return MongoDBSessionManager(
+        session_id=session_id, connection_string=MONGO_URI, database_name=DB
+    )
+
+
+def text_of(result):
+    try:
+        return " ".join(
+            b.get("text", "") for b in result.message["content"] if isinstance(b, dict)
+        )
+    except Exception:
+        return str(result)
+
+
+def test_conversation_persists_and_restores_across_managers():
+    session_id = f"llm-{uuid.uuid4()}"
+
+    a1 = Agent(model=make_model(), agent_id="assistant", session_manager=make_manager(session_id))
+    a1("Hi, my name is Kamal and I live in Pune.")
+
+    a2 = Agent(model=make_model(), agent_id="assistant", session_manager=make_manager(session_id))
+    reply = text_of(a2("What is my name?"))
+    assert "kamal" in reply.lower(), f"expected restored recall of 'kamal', got: {reply}"
+
+
+def test_messages_written_to_repository():
+    session_id = f"llm-{uuid.uuid4()}"
+    m1 = make_manager(session_id)
+    a1 = Agent(model=make_model(), agent_id="assistant", session_manager=m1)
+    a1("Say hello in one word.")
+
+    msgs = m1.list_messages(session_id, "assistant")
+    assert len(msgs) >= 2
+    assert [mm.message_id for mm in msgs] == sorted(mm.message_id for mm in msgs)
+    assert msgs[0].message["role"] == "user"
+
+
+def test_agent_record_persisted():
+    session_id = f"llm-{uuid.uuid4()}"
+    m1 = make_manager(session_id)
+    a1 = Agent(model=make_model(), agent_id="assistant", session_manager=m1)
+    a1("Hello there.")
+
+    got = m1.read_agent(session_id, "assistant")
+    assert got is not None
+    assert got.agent_id == "assistant"
+    assert isinstance(got.conversation_manager_state, dict)

strands_session_mongodb-0.1.0/tests/test_repository.py

@@ -0,0 +1,149 @@
+"""
+Comprehensive repository tests for MongoDBSessionManager against a real MongoDB.
+
+Deterministic (no LLM): exercises the SessionRepository CRUD surface — sessions,
+agents (with agent state), messages, pagination, updates/redaction, isolation.
+
+Requires a reachable MongoDB (default mongodb://127.0.0.1:27017/, override with
+MONGO_URI).
+"""
+import os
+import uuid
+
+import pytest
+
+from strands.types.exceptions import SessionException
+from strands.types.session import SessionAgent, SessionMessage
+from strands_session_mongodb import MongoDBSessionManager
+
+MONGO_URI = os.environ.get("MONGO_URI", "mongodb://127.0.0.1:27017/")
+DB = os.environ.get("MONGO_TEST_DB", "strands_sessions_test")
+
+
+def make_manager(session_id=None):
+    return MongoDBSessionManager(
+        session_id=session_id or f"sess-{uuid.uuid4()}",
+        connection_string=MONGO_URI,
+        database_name=DB,
+    )
+
+
+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(f"nope-{uuid.uuid4()}") is None
+
+
+def test_delete_session_removes_everything():
+    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))
+    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", "lang": "en"},
+        conversation_manager_state={"removed_message_count": 0}))
+    got = mgr.read_agent(mgr.session_id, "assistant")
+    assert got.state == {"tier": "gold", "lang": "en"}
+    assert got.conversation_manager_state == {"removed_message_count": 0}
+
+
+def test_read_missing_agent_returns_none():
+    mgr = make_manager()
+    assert mgr.read_agent(mgr.session_id, "ghost") is None
+
+
+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 4271")
+    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():
+    m1 = make_manager()
+    m2 = make_manager()
+    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"}