autourgos-buffer-memory 1.0.0__tar.gz

autourgos_buffer_memory-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jitin Kumar Sengar
+
+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.

autourgos_buffer_memory-1.0.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: autourgos-buffer-memory
+Version: 1.0.0
+Summary: In-memory short-term buffer for Autourgos agents — RuntimeShortTermMemory, ConversationBufferMemory.
+Author-email: Jitin Kumar Sengar <devxjitin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/devxjitin/autourgos-buffer-memory
+Project-URL: Repository, https://github.com/devxjitin/autourgos-buffer-memory
+Project-URL: Issues, https://github.com/devxjitin/autourgos-buffer-memory/issues
+Keywords: autourgos,agent,memory,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# autourgos-buffer-memory
+
+In-memory short-term buffer for [Autourgos](https://github.com/devxjitin) agents.
+
+Two classes — a message-count bounded ring buffer and an unbounded conversation buffer. Fast, zero I/O, ideal for single-session use.
+
+---
+
+## Install
+
+```bash
+pip install autourgos-buffer-memory
+```
+
+---
+
+## Classes
+
+### RuntimeShortTermMemory
+
+Keeps the last N messages in RAM. Oldest messages are dropped when the cap is exceeded.
+
+```python
+from autourgos_buffer_memory import RuntimeShortTermMemory
+from autourgos_react_agent import ReactAgent
+
+memory = RuntimeShortTermMemory(max_messages=20)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+
+agent.invoke("My name is Jitin")
+agent.invoke("What is my name?")
+# → "Your name is Jitin."
+```
+
+### ConversationBufferMemory
+
+Same as `RuntimeShortTermMemory` but with no truncation — keeps every message for the session.
+
+```python
+from autourgos_buffer_memory import ConversationBufferMemory
+
+memory = ConversationBufferMemory()
+agent  = ReactAgent(llm=my_llm, memory=memory)
+```
+
+> For long conversations, use `autourgos-summary-memory` or `autourgos-token-memory` to stay within context window limits.
+
+---
+
+## Parameters
+
+### RuntimeShortTermMemory
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `max_messages` | int | `20` | Max messages kept. Oldest dropped when exceeded. |
+| `name` | str | `"runtime"` | Human-readable identifier. |
+
+### ConversationBufferMemory
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `name` | str | `"conversation"` | Human-readable identifier. |
+
+---
+
+## API
+
+```python
+memory.add_user_message("Hello")
+memory.add_agent_message("Hi there!")
+memory.add_tool_message("search", "Found 5 results")
+memory.add_system_message("You are a helpful assistant")
+
+messages = memory.get_messages()   # list of role/content dicts
+context  = memory.format_for_llm() # formatted string for LLM prompt
+memory.clear()
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-buffer-memory/
+- GitHub: https://github.com/devxjitin/autourgos-buffer-memory
+- Issues: https://github.com/devxjitin/autourgos-buffer-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_buffer_memory-1.0.0/README.md

@@ -0,0 +1,92 @@
+# autourgos-buffer-memory
+
+In-memory short-term buffer for [Autourgos](https://github.com/devxjitin) agents.
+
+Two classes — a message-count bounded ring buffer and an unbounded conversation buffer. Fast, zero I/O, ideal for single-session use.
+
+---
+
+## Install
+
+```bash
+pip install autourgos-buffer-memory
+```
+
+---
+
+## Classes
+
+### RuntimeShortTermMemory
+
+Keeps the last N messages in RAM. Oldest messages are dropped when the cap is exceeded.
+
+```python
+from autourgos_buffer_memory import RuntimeShortTermMemory
+from autourgos_react_agent import ReactAgent
+
+memory = RuntimeShortTermMemory(max_messages=20)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+
+agent.invoke("My name is Jitin")
+agent.invoke("What is my name?")
+# → "Your name is Jitin."
+```
+
+### ConversationBufferMemory
+
+Same as `RuntimeShortTermMemory` but with no truncation — keeps every message for the session.
+
+```python
+from autourgos_buffer_memory import ConversationBufferMemory
+
+memory = ConversationBufferMemory()
+agent  = ReactAgent(llm=my_llm, memory=memory)
+```
+
+> For long conversations, use `autourgos-summary-memory` or `autourgos-token-memory` to stay within context window limits.
+
+---
+
+## Parameters
+
+### RuntimeShortTermMemory
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `max_messages` | int | `20` | Max messages kept. Oldest dropped when exceeded. |
+| `name` | str | `"runtime"` | Human-readable identifier. |
+
+### ConversationBufferMemory
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `name` | str | `"conversation"` | Human-readable identifier. |
+
+---
+
+## API
+
+```python
+memory.add_user_message("Hello")
+memory.add_agent_message("Hi there!")
+memory.add_tool_message("search", "Found 5 results")
+memory.add_system_message("You are a helpful assistant")
+
+messages = memory.get_messages()   # list of role/content dicts
+context  = memory.format_for_llm() # formatted string for LLM prompt
+memory.clear()
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-buffer-memory/
+- GitHub: https://github.com/devxjitin/autourgos-buffer-memory
+- Issues: https://github.com/devxjitin/autourgos-buffer-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_buffer_memory-1.0.0/autourgos_buffer_memory/__init__.py

@@ -0,0 +1,14 @@
+"""
+autourgos-buffer-memory — In-memory short-term buffers for Autourgos agents.
+
+    from autourgos_buffer_memory import RuntimeShortTermMemory, ConversationBufferMemory
+"""
+from .memory import RuntimeShortTermMemory, ConversationBufferMemory
+
+try:
+    from importlib.metadata import version as _v
+    __version__ = _v("autourgos-buffer-memory")
+except Exception:
+    __version__ = "1.0.2"
+
+__all__ = ["RuntimeShortTermMemory", "ConversationBufferMemory"]

autourgos_buffer_memory-1.0.0/autourgos_buffer_memory/base.py

@@ -0,0 +1,101 @@
+"""
+base.py — Self-contained base classes. No external dependencies.
+"""
+from __future__ import annotations
+
+import warnings
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+_ALLOWED_ROLES = {"user", "agent", "system", "tool"}
+
+
+@dataclass(frozen=True)
+class MemoryMessage:
+    """A single message in memory."""
+    role: str
+    content: str
+    timestamp: datetime
+
+    def __post_init__(self) -> None:
+        if self.role not in _ALLOWED_ROLES:
+            raise ValueError(f"Invalid role {self.role!r}. Allowed: {sorted(_ALLOWED_ROLES)}")
+        if not isinstance(self.content, str):
+            raise ValueError("content must be a string")
+        if not isinstance(self.timestamp, datetime):
+            raise ValueError("timestamp must be a datetime")
+
+    def to_dict(self) -> Dict[str, str]:
+        return {
+            "role": self.role,
+            "content": self.content,
+            "timestamp": self.timestamp.astimezone(timezone.utc).isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "MemoryMessage":
+        ts = payload.get("timestamp")
+        if not isinstance(ts, str):
+            raise ValueError("timestamp must be a string")
+        dt = datetime.fromisoformat(ts)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return cls(role=str(payload.get("role", "")), content=str(payload.get("content", "")), timestamp=dt)
+
+
+class BaseMemory(ABC):
+    """Abstract interface for agent memory."""
+
+    @abstractmethod
+    def add_user_message(self, content: str) -> MemoryMessage: ...
+
+    def add_ai_message(self, content: str) -> MemoryMessage:
+        warnings.warn("add_ai_message() is deprecated; use add_agent_message().", DeprecationWarning, stacklevel=2)
+        return self.add_agent_message(content)
+
+    def add_agent_message(self, content: str) -> MemoryMessage:
+        if type(self).add_ai_message is not BaseMemory.add_ai_message:
+            return self.add_ai_message(content)
+        raise NotImplementedError("Subclasses must implement add_agent_message")
+
+    @abstractmethod
+    def add_tool_message(self, tool_name: str, result: str) -> MemoryMessage: ...
+
+    def get_context(self, query: Optional[str] = None) -> str:
+        warnings.warn("get_context() is deprecated; use format_for_llm().", DeprecationWarning, stacklevel=2)
+        return self.format_for_llm(query)
+
+    def format_for_llm(self, query: Optional[str] = None) -> str:
+        if type(self).get_context is not BaseMemory.get_context:
+            return self.get_context(query)
+        raise NotImplementedError("Subclasses must implement format_for_llm")
+
+    @abstractmethod
+    def clear(self) -> None: ...
+
+
+@dataclass
+class Document:
+    """A retrieved document chunk."""
+    content: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    score: float = 0.0
+    source: str = ""
+
+    def __str__(self) -> str:
+        src = f" (source: {self.source})" if self.source else ""
+        return f"{self.content}{src}"
+
+
+class BaseRetriever(ABC):
+    """Abstract retriever interface."""
+
+    @abstractmethod
+    def retrieve(self, query: str, top_k: int = 5) -> List[Document]: ...
+
+    async def aretrieve(self, query: str, top_k: int = 5) -> List[Document]:
+        import asyncio
+        return await asyncio.to_thread(self.retrieve, query, top_k)
+

autourgos_buffer_memory-1.0.0/autourgos_buffer_memory/memory.py

@@ -0,0 +1,72 @@
+"""
+memory.py — In-memory short-term buffers.
+"""
+from __future__ import annotations
+import sys
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from .base import BaseMemory, MemoryMessage
+
+
+class RuntimeShortTermMemory(BaseMemory):
+    """In-memory ring buffer bounded by message count.
+
+    Parameters
+    ----------
+    max_messages : int
+        Maximum messages kept. Oldest are dropped when exceeded. Default 20.
+    name : str
+        Human-readable identifier.
+    """
+
+    def __init__(self, max_messages: int = 20, name: str = "runtime") -> None:
+        if not isinstance(max_messages, int) or max_messages < 1:
+            raise ValueError("max_messages must be an integer >= 1")
+        self.max_messages = max_messages
+        self.name = name
+        self._messages: List[MemoryMessage] = []
+
+    def add_message(self, role: str, content: str, timestamp: Optional[datetime] = None) -> MemoryMessage:
+        msg = MemoryMessage(role=role, content=content, timestamp=timestamp or datetime.now(timezone.utc))
+        self._messages.append(msg)
+        if len(self._messages) > self.max_messages:
+            self._messages = self._messages[-self.max_messages:]
+        return msg
+
+    def add_user_message(self, content: str) -> MemoryMessage:
+        return self.add_message("user", content)
+
+    def add_agent_message(self, content: str) -> MemoryMessage:
+        return self.add_message("agent", content)
+
+    def add_system_message(self, content: str) -> MemoryMessage:
+        return self.add_message("system", content)
+
+    def add_tool_message(self, tool_name: str, result: str) -> MemoryMessage:
+        return self.add_message("tool", f"[{tool_name} returned]: {result}")
+
+    def get_messages(self) -> List[Dict[str, str]]:
+        _ROLE = {"user": "user", "agent": "assistant", "system": "system", "tool": "tool"}
+        return [{"role": _ROLE.get(m.role, m.role), "content": m.content} for m in self._messages]
+
+    def clear(self) -> None:
+        self._messages = []
+
+    def format_for_llm(self, query: Optional[str] = None) -> str:
+        if not self._messages:
+            return ""
+        lines = "\n".join(f"{m.role}: {m.content}" for m in self._messages)
+        return f"\n--- Previous Conversation Context ---\n{lines}\n--------------------------------------\n"
+
+
+class ConversationBufferMemory(RuntimeShortTermMemory):
+    """Unbounded in-memory conversation buffer (no truncation).
+
+    Use this when you want to keep every message in RAM for the session.
+    For long conversations, prefer :class:`RuntimeShortTermMemory` with a cap,
+    or :class:`~autourgos_summary_memory.SummaryBufferedMemory` for LLM compression.
+    """
+
+    def __init__(self, name: str = "conversation") -> None:
+        super().__init__(max_messages=sys.maxsize, name=name)

autourgos_buffer_memory-1.0.0/autourgos_buffer_memory.egg-info/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: autourgos-buffer-memory
+Version: 1.0.0
+Summary: In-memory short-term buffer for Autourgos agents — RuntimeShortTermMemory, ConversationBufferMemory.
+Author-email: Jitin Kumar Sengar <devxjitin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/devxjitin/autourgos-buffer-memory
+Project-URL: Repository, https://github.com/devxjitin/autourgos-buffer-memory
+Project-URL: Issues, https://github.com/devxjitin/autourgos-buffer-memory/issues
+Keywords: autourgos,agent,memory,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# autourgos-buffer-memory
+
+In-memory short-term buffer for [Autourgos](https://github.com/devxjitin) agents.
+
+Two classes — a message-count bounded ring buffer and an unbounded conversation buffer. Fast, zero I/O, ideal for single-session use.
+
+---
+
+## Install
+
+```bash
+pip install autourgos-buffer-memory
+```
+
+---
+
+## Classes
+
+### RuntimeShortTermMemory
+
+Keeps the last N messages in RAM. Oldest messages are dropped when the cap is exceeded.
+
+```python
+from autourgos_buffer_memory import RuntimeShortTermMemory
+from autourgos_react_agent import ReactAgent
+
+memory = RuntimeShortTermMemory(max_messages=20)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+
+agent.invoke("My name is Jitin")
+agent.invoke("What is my name?")
+# → "Your name is Jitin."
+```
+
+### ConversationBufferMemory
+
+Same as `RuntimeShortTermMemory` but with no truncation — keeps every message for the session.
+
+```python
+from autourgos_buffer_memory import ConversationBufferMemory
+
+memory = ConversationBufferMemory()
+agent  = ReactAgent(llm=my_llm, memory=memory)
+```
+
+> For long conversations, use `autourgos-summary-memory` or `autourgos-token-memory` to stay within context window limits.
+
+---
+
+## Parameters
+
+### RuntimeShortTermMemory
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `max_messages` | int | `20` | Max messages kept. Oldest dropped when exceeded. |
+| `name` | str | `"runtime"` | Human-readable identifier. |
+
+### ConversationBufferMemory
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `name` | str | `"conversation"` | Human-readable identifier. |
+
+---
+
+## API
+
+```python
+memory.add_user_message("Hello")
+memory.add_agent_message("Hi there!")
+memory.add_tool_message("search", "Found 5 results")
+memory.add_system_message("You are a helpful assistant")
+
+messages = memory.get_messages()   # list of role/content dicts
+context  = memory.format_for_llm() # formatted string for LLM prompt
+memory.clear()
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-buffer-memory/
+- GitHub: https://github.com/devxjitin/autourgos-buffer-memory
+- Issues: https://github.com/devxjitin/autourgos-buffer-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_buffer_memory-1.0.0/autourgos_buffer_memory.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+autourgos_buffer_memory/__init__.py
+autourgos_buffer_memory/base.py
+autourgos_buffer_memory/memory.py
+autourgos_buffer_memory/py.typed
+autourgos_buffer_memory.egg-info/PKG-INFO
+autourgos_buffer_memory.egg-info/SOURCES.txt
+autourgos_buffer_memory.egg-info/dependency_links.txt
+autourgos_buffer_memory.egg-info/top_level.txt

autourgos_buffer_memory-1.0.0/autourgos_buffer_memory.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

autourgos_buffer_memory-1.0.0/autourgos_buffer_memory.egg-info/top_level.txt

@@ -0,0 +1 @@
+autourgos_buffer_memory

autourgos_buffer_memory-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "autourgos-buffer-memory"
+version = "1.0.0"
+description = "In-memory short-term buffer for Autourgos agents — RuntimeShortTermMemory, ConversationBufferMemory."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Jitin Kumar Sengar", email = "devxjitin@gmail.com"}
+]
+keywords = ["autourgos", "agent", "memory", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/devxjitin/autourgos-buffer-memory"
+Repository = "https://github.com/devxjitin/autourgos-buffer-memory"
+Issues = "https://github.com/devxjitin/autourgos-buffer-memory/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["autourgos_buffer_memory*"]
+
+[tool.setuptools.package-data]
+autourgos_buffer_memory = ["py.typed"]

autourgos_buffer_memory-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+