rollmem 0.0.1__py3-none-any.whl

rollmem/__init__.py

@@ -0,0 +1,16 @@
+"""rollmem — standalone rolling conversation memory (summary + buffer)."""
+
+from .memory import RollingMemory, SummarizeFn, TokenCounter
+from .message import ASSISTANT, SYSTEM, USER, Message
+
+__all__ = [
+    "RollingMemory",
+    "Message",
+    "SummarizeFn",
+    "TokenCounter",
+    "USER",
+    "ASSISTANT",
+    "SYSTEM",
+]
+
+__version__ = "0.0.1"

rollmem/memory.py

@@ -0,0 +1,209 @@
+"""Core rolling memory: a running summary plus a recent-message buffer.
+
+The behaviour mirrors LangChain's ConversationSummaryBufferMemory but with zero
+dependencies. The two things that *would* tie us to an LLM provider — turning
+messages into a summary, and counting tokens — are injected by the caller:
+
+    summarize_fn(existing_summary, messages_to_fold) -> new_summary
+    token_counter(text) -> int
+
+This keeps rollmem usable with any model, or with no model at all (e.g. a fake
+counter and a no-op summarizer in tests).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence
+
+from .message import ASSISTANT, SYSTEM, USER, Message
+
+SummarizeFn = Callable[[str, Sequence[Message]], str]
+TokenCounter = Callable[[str], int]
+
+SCHEMA_VERSION = 1
+
+
+def _default_token_counter(text: str) -> int:
+    """Rough word-based estimate used when the caller injects nothing.
+
+    Intentionally crude — real deployments should pass a model-accurate counter
+    (e.g. tiktoken). Good enough to make the buffer roll in tests and demos.
+    """
+    return len(text.split())
+
+
+class RollingMemory:
+    """Keeps recent turns verbatim and folds older turns into a running summary.
+
+    The token budget applies only to the verbatim buffer. The running summary
+    is whatever ``summarize_fn`` returns and is not bounded here, so keeping it
+    compact is the caller's responsibility: a ``summarize_fn`` that compresses
+    keeps ``get_context()`` bounded, while one that merely concatenates lets the
+    summary grow without limit.
+
+    Args:
+        max_tokens: token budget for the verbatim buffer. When the buffer
+            exceeds this, the oldest messages are folded into the summary until
+            it fits again. This bounds the buffer only, not the summary, and is
+            unrelated to a model's generation ``max_tokens`` (output limit) — it
+            is purely the size of the recent-message buffer rollmem keeps.
+        summarize_fn: callback that produces an updated summary from the current
+            summary plus the messages being evicted. Required to actually
+            summarize; if omitted, evicted messages are dropped (buffer-only).
+            It should compress, not just append, to keep the summary bounded.
+        token_counter: callback returning a token count for a string. Defaults
+            to a word-count estimate.
+    """
+
+    def __init__(
+        self,
+        max_tokens: int = 2000,
+        summarize_fn: Optional[SummarizeFn] = None,
+        token_counter: Optional[TokenCounter] = None,
+    ) -> None:
+        if max_tokens <= 0:
+            raise ValueError("max_tokens must be positive")
+        self.max_tokens = max_tokens
+        self._summarize_fn = summarize_fn
+        self._token_counter = token_counter or _default_token_counter
+        self.summary: str = ""
+        self.buffer: List[Message] = []
+
+    # -- adding turns -----------------------------------------------------
+
+    def add_message(self, role: str, content: str) -> None:
+        self.buffer.append(Message(role=role, content=content))
+        self._prune()
+
+    def add_user_message(self, content: str) -> None:
+        self.add_message(USER, content)
+
+    def add_assistant_message(self, content: str) -> None:
+        self.add_message(ASSISTANT, content)
+
+    def add_system_message(self, content: str) -> None:
+        self.add_message(SYSTEM, content)
+
+    # -- reading back -----------------------------------------------------
+
+    def get_context(self) -> str:
+        """Summary (if any) followed by the verbatim buffer, as one string.
+
+        This is the string form of :meth:`get_messages`: the running summary,
+        when present, is rendered as a leading ``system`` turn so both methods
+        expose it identically and stay consistent. No language-specific label
+        is added — wrap or relabel the summary in your own prompt assembly if
+        you need to.
+        """
+        return "\n".join(str(m) for m in self.get_messages())
+
+    def get_messages(self) -> List[Message]:
+        """Buffer messages, with the running summary prepended as a system turn."""
+        messages: List[Message] = []
+        if self.summary:
+            messages.append(Message(role=SYSTEM, content=self.summary))
+        messages.extend(self.buffer)
+        return messages
+
+    def clear(self) -> None:
+        self.summary = ""
+        self.buffer.clear()
+
+    # -- serialization ----------------------------------------------------
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize the memory state to a plain ``dict``.
+
+        Only conversation state is captured — the running summary and the
+        verbatim buffer. The token budget and the injected callbacks are
+        considered runtime configuration, not state, so they are not included
+        and must be supplied again at :meth:`from_dict` time.
+
+        Returns:
+            A mapping with ``version``, ``summary``, and ``buffer`` keys,
+            suitable for JSON serialization (the caller chooses the format).
+        """
+        return {
+            "version": SCHEMA_VERSION,
+            "summary": self.summary,
+            "buffer": [m.to_dict() for m in self.buffer],
+        }
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Mapping[str, Any],
+        *,
+        max_tokens: int = 2000,
+        summarize_fn: Optional[SummarizeFn] = None,
+        token_counter: Optional[TokenCounter] = None,
+    ) -> RollingMemory:
+        """Reconstruct a memory from its ``dict`` representation.
+
+        The buffer is restored verbatim: this does not call the pruning logic,
+        so loading never triggers an unexpected ``summarize_fn`` call or drops
+        turns. The token budget is re-applied on the next ``add_message``; if
+        ``max_tokens`` is smaller than when the state was saved, the buffer may
+        momentarily exceed it until the next turn is added.
+
+        Args:
+            data: A mapping produced by :meth:`to_dict`.
+            max_tokens: Token budget for the restored buffer. Runtime
+                configuration, not part of the saved state.
+            summarize_fn: Summarizer callback to re-inject. Callbacks are not
+                serialized, so pass it again to keep summarization working.
+            token_counter: Token-counter callback to re-inject. Defaults to the
+                word-count estimate when omitted.
+
+        Returns:
+            The reconstructed ``RollingMemory``.
+
+        Raises:
+            ValueError: If ``data`` has an unsupported serialization version.
+        """
+        version = data.get("version")
+        if version != SCHEMA_VERSION:
+            raise ValueError(f"unsupported serialization version: {version!r}")
+        memory = cls(
+            max_tokens=max_tokens,
+            summarize_fn=summarize_fn,
+            token_counter=token_counter,
+        )
+        memory.summary = data.get("summary", "")
+        memory.buffer = [Message.from_dict(m) for m in data.get("buffer", [])]
+        return memory
+
+    # -- internals --------------------------------------------------------
+
+    def _buffer_tokens(self) -> int:
+        return sum(self._token_counter(m.content) for m in self.buffer)
+
+    def _prune(self) -> None:
+        """Fold oldest messages into the summary until the buffer fits budget.
+
+        Eviction is computed first, then summarized in a single ``summarize_fn``
+        call, and only after that succeeds are the messages dropped from the
+        buffer. This keeps the summarizer call cheap (one call, not one per
+        message) and means a summarizer failure leaves the buffer untouched
+        rather than silently losing turns.
+        """
+        # Figure out how many of the oldest messages must go, without mutating
+        # the buffer yet. Always keep at least one message in the buffer.
+        tokens = self._buffer_tokens()
+        evict_count = 0
+        while (
+            len(self.buffer) - evict_count > 1
+            and tokens > self.max_tokens
+        ):
+            tokens -= self._token_counter(self.buffer[evict_count].content)
+            evict_count += 1
+
+        if evict_count == 0:
+            return
+
+        evicted = self.buffer[:evict_count]
+        if self._summarize_fn is not None:
+            # If this raises, we have not touched the buffer yet — no data loss.
+            self.summary = self._summarize_fn(self.summary, evicted)
+
+        del self.buffer[:evict_count]

rollmem/message.py

@@ -0,0 +1,49 @@
+"""Provider-agnostic message representation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Mapping
+
+# Conventional roles. rollmem does not enforce these — any string is accepted —
+# but these are the values the built-in helpers (add_user_message, etc.) emit.
+USER = "user"
+ASSISTANT = "assistant"
+SYSTEM = "system"
+
+
+@dataclass(frozen=True)
+class Message:
+    """A single turn in a conversation.
+
+    Deliberately minimal so rollmem stays free of any LLM-provider schema.
+    Adapters (OpenAI, Anthropic, LangChain, ...) convert to/from this type.
+    """
+
+    role: str
+    content: str
+
+    def __str__(self) -> str:
+        return f"{self.role}: {self.content}"
+
+    def to_dict(self) -> Dict[str, str]:
+        """Return a plain ``dict`` representation of this message.
+
+        Returns:
+            A mapping with ``role`` and ``content`` keys, suitable for JSON
+            serialization (the caller chooses the serialization format).
+        """
+        return {"role": self.role, "content": self.content}
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, str]) -> Message:
+        """Reconstruct a message from its ``dict`` representation.
+
+        Args:
+            data: A mapping with ``role`` and ``content`` keys, as produced by
+                :meth:`to_dict`.
+
+        Returns:
+            The reconstructed ``Message``.
+        """
+        return cls(role=data["role"], content=data["content"])

rollmem-0.0.1.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: rollmem
+Version: 0.0.1
+Summary: Standalone, dependency-free rolling conversation memory (summary + buffer), inspired by LangChain's ConversationSummaryBufferMemory.
+Project-URL: Homepage, https://github.com/okdoittttt/rollmem
+Project-URL: Repository, https://github.com/okdoittttt/rollmem
+Project-URL: Issues, https://github.com/okdoittttt/rollmem/issues
+Author-email: son okmoo <sonokmoo@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chatbot,conversation,langchain,llm,memory,rag,summary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rollmem
+
+[![PyPI version](https://img.shields.io/pypi/v/rollmem.svg)](https://pypi.org/project/rollmem/)
+[![Python versions](https://img.shields.io/pypi/pyversions/rollmem.svg)](https://pypi.org/project/rollmem/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Standalone, **dependency-free** rolling conversation memory for LLM apps —
+a running summary plus a recent-message buffer, inspired by LangChain's
+`ConversationSummaryBufferMemory`, but with no LangChain (or any) dependency.
+
+Handy for **conversation memory**, **context compression**, **summarization**,
+and **gist**-style long-chat handling — a tiny **LangChain alternative** when
+you only need the summary-buffer pattern.
+
+## Why
+
+`ConversationSummaryBufferMemory` is a great pattern: keep recent turns
+verbatim, fold older turns into a running summary so context stays bounded.
+But pulling in all of LangChain just for that is heavy. `rollmem` extracts the
+idea into a tiny, provider-agnostic package. You inject how to summarize and
+how to count tokens — rollmem stays neutral.
+
+## Install
+
+```bash
+pip install rollmem
+```
+
+## Usage
+
+```python
+from rollmem import RollingMemory
+
+def summarize(existing_summary, messages):
+    # plug in any LLM here; return the new summary string
+    folded = " ".join(m.content for m in messages)
+    return (existing_summary + " " + folded).strip()
+
+mem = RollingMemory(
+    max_tokens=2000,
+    summarize_fn=summarize,   # optional; without it, evicted turns are dropped
+    # token_counter=...       # optional; defaults to a word-count estimate.
+    #                         # In production inject a model-accurate counter, e.g.
+    #                         # token_counter=lambda text: len(enc.encode(text))
+)
+
+mem.add_user_message("Hi, I'm planning a trip to Korea.")
+mem.add_assistant_message("Great! When are you going?")
+
+print(mem.get_context())    # -> str: summary (if any) + recent buffer, joined
+print(mem.get_messages())   # -> list[Message]: summary prepended as a system turn
+```
+
+`max_tokens` is the budget for the **verbatim recent-message buffer** — not the
+running summary, and not a model's generation `max_tokens` (output limit). When
+the buffer exceeds it, the oldest turns are folded into the summary.
+
+`token_counter` takes a single message's text (`str`) and returns an `int`. The
+default is a crude word count — fine for demos, but pass a model-accurate counter
+(such as `tiktoken`) for real token budgets.
+
+## Persistence
+
+`to_dict()` / `from_dict()` serialize the memory **state** (running summary plus
+buffer) to and from a plain `dict` — you choose the storage format:
+
+```python
+import json
+
+raw = json.dumps(mem.to_dict())   # save anywhere: file, DB column, cache...
+
+mem = RollingMemory.from_dict(
+    json.loads(raw),
+    max_tokens=2000,
+    summarize_fn=summarize,        # callbacks are NOT serialized — re-inject them
+    # token_counter=...
+)
+```
+
+`max_tokens` and the callbacks are runtime configuration, not saved state, so you
+pass them again on restore. The buffer is restored verbatim; the token budget is
+re-applied on the next added message.
+
+## How it works
+
+- New turns go into `buffer`.
+- When `buffer` exceeds `max_tokens`, the oldest turns are folded into `summary`
+  via `summarize_fn` (or dropped if none is provided).
+- `get_messages() -> list[Message]` returns the buffer with the summary
+  prepended as a `system` turn. `get_context() -> str` is the string form of
+  the same thing (prompt-ready), so the two never diverge. Neither adds a
+  language-specific label — relabel the summary in your own prompt assembly if
+  you need to.
+
+## Limitations
+
+- **Lossy by design.** Older turns are folded into the summary repeatedly, so
+  each pass can blur or drop detail (a "telephone game" effect). Keep
+  `max_tokens` large enough that anything you can't afford to lose stays in the
+  verbatim buffer.
+- **The summary is not bounded for you.** `max_tokens` limits only the verbatim
+  buffer, not the running summary. rollmem hands your `summarize_fn` the current
+  summary plus the evicted turns and stores whatever it returns — so keeping the
+  summary compact is your `summarize_fn`'s job. If it merely concatenates,
+  the summary (and thus `get_context()`) grows without limit. Prompt it to
+  compress, or cap the summary length inside the callback.
+- **Only as accurate as your counter.** The default token counter is a rough
+  word count; inject a model-accurate one (e.g. `tiktoken`) for real budgets.
+- **In-memory by default.** State lives in memory, but `to_dict()` / `from_dict()`
+  let you persist and restore it (see [Persistence](#persistence)). Callbacks are
+  not serialized and must be re-injected on restore.
+
+## License
+
+MIT

rollmem-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+rollmem/__init__.py,sha256=Xe6PMgyVT8TskAl5i544e5Tu5iT5jQzMXMfY9vbcKSs,349
+rollmem/memory.py,sha256=bdGncefZWw33solluDxGIChJr1Y1YuFBHxyO5dBCdwM,8498
+rollmem/message.py,sha256=8uamVUMQpdfY-mzNS-8aXDT3E8kbRJswV2_mJP4RwG4,1478
+rollmem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rollmem-0.0.1.dist-info/METADATA,sha256=mKHVFX_gw90xT7pvNsm811B_AZ7p6ij0Exm2sEbTPjg,6135
+rollmem-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+rollmem-0.0.1.dist-info/licenses/LICENSE,sha256=NBdRD4nIdWtt1GhhF6q-UKm15N-snL7ZKs3lF_RZ_9Y,1078
+rollmem-0.0.1.dist-info/RECORD,,

rollmem-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

rollmem-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 손옥무 | son okmoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.