autourgos-token-memory 1.0.0__tar.gz

autourgos_token_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_token_memory-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: autourgos-token-memory
+Version: 1.0.0
+Summary: Token-bounded short-term memory for Autourgos agents — TokenBufferedMemory.
+Author-email: Jitin Kumar Sengar <devxjitin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/devxjitin/autourgos-token-memory
+Project-URL: Repository, https://github.com/devxjitin/autourgos-token-memory
+Project-URL: Issues, https://github.com/devxjitin/autourgos-token-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
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.5; extra == "tiktoken"
+Dynamic: license-file
+
+# autourgos-token-memory
+
+Token-bounded short-term memory for [Autourgos](https://github.com/devxjitin) agents.
+
+Keeps messages in RAM and evicts the oldest ones when the total token count exceeds a budget. Automatically uses `tiktoken` for accurate counts if installed, with a fast character-based heuristic as fallback.
+
+---
+
+## Install
+
+```bash
+pip install autourgos-token-memory
+
+# For accurate tiktoken counts (recommended for OpenAI models)
+pip install 'autourgos-token-memory[tiktoken]'
+```
+
+---
+
+## Quick Start
+
+```python
+from autourgos_token_memory import TokenBufferedMemory
+from autourgos_react_agent import ReactAgent
+
+memory = TokenBufferedMemory(max_tokens=4000)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+agent.invoke("Long conversation task...")
+```
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `max_tokens` | int | `2000` | Token budget. Oldest messages evicted when exceeded. |
+| `token_estimator` | callable | `None` | Custom `(text: str) -> int`. Defaults to tiktoken / heuristic. |
+
+---
+
+## Custom token estimator
+
+```python
+from autourgos_token_memory import TokenBufferedMemory
+
+def my_estimator(text: str) -> int:
+    return len(text.split())  # word count
+
+memory = TokenBufferedMemory(max_tokens=500, token_estimator=my_estimator)
+```
+
+---
+
+## Token counting
+
+- **tiktoken installed**: uses `cl100k_base` encoding (accurate for GPT-3.5/4/4o).
+- **tiktoken not installed**: Unicode-aware heuristic — ~0.25 tokens per ASCII char, ~1.5 per CJK character.
+
+Check current usage:
+
+```python
+print(memory.total_tokens)  # → int
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-token-memory/
+- GitHub: https://github.com/devxjitin/autourgos-token-memory
+- Issues: https://github.com/devxjitin/autourgos-token-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_token_memory-1.0.0/README.md

@@ -0,0 +1,78 @@
+# autourgos-token-memory
+
+Token-bounded short-term memory for [Autourgos](https://github.com/devxjitin) agents.
+
+Keeps messages in RAM and evicts the oldest ones when the total token count exceeds a budget. Automatically uses `tiktoken` for accurate counts if installed, with a fast character-based heuristic as fallback.
+
+---
+
+## Install
+
+```bash
+pip install autourgos-token-memory
+
+# For accurate tiktoken counts (recommended for OpenAI models)
+pip install 'autourgos-token-memory[tiktoken]'
+```
+
+---
+
+## Quick Start
+
+```python
+from autourgos_token_memory import TokenBufferedMemory
+from autourgos_react_agent import ReactAgent
+
+memory = TokenBufferedMemory(max_tokens=4000)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+agent.invoke("Long conversation task...")
+```
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `max_tokens` | int | `2000` | Token budget. Oldest messages evicted when exceeded. |
+| `token_estimator` | callable | `None` | Custom `(text: str) -> int`. Defaults to tiktoken / heuristic. |
+
+---
+
+## Custom token estimator
+
+```python
+from autourgos_token_memory import TokenBufferedMemory
+
+def my_estimator(text: str) -> int:
+    return len(text.split())  # word count
+
+memory = TokenBufferedMemory(max_tokens=500, token_estimator=my_estimator)
+```
+
+---
+
+## Token counting
+
+- **tiktoken installed**: uses `cl100k_base` encoding (accurate for GPT-3.5/4/4o).
+- **tiktoken not installed**: Unicode-aware heuristic — ~0.25 tokens per ASCII char, ~1.5 per CJK character.
+
+Check current usage:
+
+```python
+print(memory.total_tokens)  # → int
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-token-memory/
+- GitHub: https://github.com/devxjitin/autourgos-token-memory
+- Issues: https://github.com/devxjitin/autourgos-token-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_token_memory-1.0.0/autourgos_token_memory/__init__.py

@@ -0,0 +1,18 @@
+"""
+autourgos-token-memory — Token-bounded short-term memory for Autourgos agents.
+
+    from autourgos_token_memory import TokenBufferedMemory
+
+Install with tiktoken for accurate counts::
+
+    pip install 'autourgos-token-memory[tiktoken]'
+"""
+from .memory import TokenBufferedMemory, _default_token_estimator
+
+try:
+    from importlib.metadata import version as _v
+    __version__ = _v("autourgos-token-memory")
+except Exception:
+    __version__ = "1.0.2"
+
+__all__ = ["TokenBufferedMemory"]

autourgos_token_memory-1.0.0/autourgos_token_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_token_memory-1.0.0/autourgos_token_memory/memory.py

@@ -0,0 +1,110 @@
+"""
+memory.py — Token-bounded short-term memory.
+"""
+from __future__ import annotations
+
+import threading
+from datetime import datetime, timezone
+from typing import Callable, List, Optional
+
+from .base import BaseMemory, MemoryMessage
+
+
+def _default_token_estimator(text: Optional[str]) -> int:
+    """Estimate tokens. Uses tiktoken if installed, otherwise a heuristic."""
+    if not text:
+        return 0
+    try:
+        import tiktoken
+        enc = tiktoken.get_encoding("cl100k_base")
+        return len(enc.encode(text, disallowed_special=()))
+    except Exception:
+        pass
+    # Unicode-aware heuristic
+    total = 0.0
+    for ch in text:
+        o = ord(ch)
+        if (0x4E00 <= o <= 0x9FFF or 0x3040 <= o <= 0x309F or
+                0x30A0 <= o <= 0x30FF or 0x1100 <= o <= 0x11FF or
+                0xAC00 <= o <= 0xD7AF):
+            total += 1.5
+        elif ch in ('{', '}', '[', ']', '"', "'", ':', ',', ';', '=', '+', '-', '*', '/', '<', '>', '&', '|', '^', '%'):
+            total += 0.5
+        else:
+            total += 0.25
+    return max(1, int(total))
+
+
+class TokenBufferedMemory(BaseMemory):
+    """Short-term memory bounded by maximum token count.
+
+    Oldest messages are evicted from the front whenever the total token
+    count exceeds ``max_tokens``. Optionally uses ``tiktoken`` for accurate
+    counts; falls back to a character-based heuristic if not installed.
+
+    Parameters
+    ----------
+    max_tokens : int
+        Token budget. Default 2000.
+    token_estimator : callable, optional
+        Custom ``(text: str) -> int`` estimator. Defaults to tiktoken / heuristic.
+    """
+
+    def __init__(
+        self,
+        max_tokens: int = 2000,
+        token_estimator: Optional[Callable[[str], int]] = None,
+    ) -> None:
+        if not isinstance(max_tokens, int) or max_tokens < 1:
+            raise ValueError("max_tokens must be an integer >= 1")
+        self.max_tokens      = max_tokens
+        self.token_estimator = token_estimator or _default_token_estimator
+        self._messages: List[MemoryMessage] = []
+        self._total_tokens = 0
+        self._lock = threading.RLock()
+
+    def _msg_tokens(self, msg: MemoryMessage) -> int:
+        return self.token_estimator(msg.role) + self.token_estimator(msg.content)
+
+    def _enforce_limit(self) -> None:
+        while self._messages and self._total_tokens > self.max_tokens:
+            removed = self._messages.pop(0)
+            self._total_tokens -= self._msg_tokens(removed)
+
+    def add_message(self, role: str, content: str, timestamp: Optional[datetime] = None) -> MemoryMessage:
+        with self._lock:
+            msg = MemoryMessage(role=role, content=content, timestamp=timestamp or datetime.now(timezone.utc))
+            self._messages.append(msg)
+            self._total_tokens += self._msg_tokens(msg)
+            self._enforce_limit()
+            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_tool_message(self, tool_name: str, result: str) -> MemoryMessage:
+        return self.add_message("tool", f"[{tool_name} returned]: {result}")
+
+    def get_messages(self) -> List[MemoryMessage]:
+        with self._lock:
+            return list(self._messages)
+
+    @property
+    def total_tokens(self) -> int:
+        with self._lock:
+            return self._total_tokens
+
+    def format_for_llm(self, query: Optional[str] = None) -> str:
+        with self._lock:
+            if not self._messages:
+                return ""
+            lines = "\n".join(f"[{m.timestamp.isoformat()}] {m.role}: {m.content}" for m in self._messages)
+            return f"\n--- Previous Conversation Context ---\n{lines}\n--------------------------------------\n"
+
+    def clear(self) -> None:
+        with self._lock:
+            self._messages.clear()
+            self._total_tokens = 0

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

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: autourgos-token-memory
+Version: 1.0.0
+Summary: Token-bounded short-term memory for Autourgos agents — TokenBufferedMemory.
+Author-email: Jitin Kumar Sengar <devxjitin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/devxjitin/autourgos-token-memory
+Project-URL: Repository, https://github.com/devxjitin/autourgos-token-memory
+Project-URL: Issues, https://github.com/devxjitin/autourgos-token-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
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.5; extra == "tiktoken"
+Dynamic: license-file
+
+# autourgos-token-memory
+
+Token-bounded short-term memory for [Autourgos](https://github.com/devxjitin) agents.
+
+Keeps messages in RAM and evicts the oldest ones when the total token count exceeds a budget. Automatically uses `tiktoken` for accurate counts if installed, with a fast character-based heuristic as fallback.
+
+---
+
+## Install
+
+```bash
+pip install autourgos-token-memory
+
+# For accurate tiktoken counts (recommended for OpenAI models)
+pip install 'autourgos-token-memory[tiktoken]'
+```
+
+---
+
+## Quick Start
+
+```python
+from autourgos_token_memory import TokenBufferedMemory
+from autourgos_react_agent import ReactAgent
+
+memory = TokenBufferedMemory(max_tokens=4000)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+agent.invoke("Long conversation task...")
+```
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `max_tokens` | int | `2000` | Token budget. Oldest messages evicted when exceeded. |
+| `token_estimator` | callable | `None` | Custom `(text: str) -> int`. Defaults to tiktoken / heuristic. |
+
+---
+
+## Custom token estimator
+
+```python
+from autourgos_token_memory import TokenBufferedMemory
+
+def my_estimator(text: str) -> int:
+    return len(text.split())  # word count
+
+memory = TokenBufferedMemory(max_tokens=500, token_estimator=my_estimator)
+```
+
+---
+
+## Token counting
+
+- **tiktoken installed**: uses `cl100k_base` encoding (accurate for GPT-3.5/4/4o).
+- **tiktoken not installed**: Unicode-aware heuristic — ~0.25 tokens per ASCII char, ~1.5 per CJK character.
+
+Check current usage:
+
+```python
+print(memory.total_tokens)  # → int
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-token-memory/
+- GitHub: https://github.com/devxjitin/autourgos-token-memory
+- Issues: https://github.com/devxjitin/autourgos-token-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

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

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

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

@@ -0,0 +1 @@
+

autourgos_token_memory-1.0.0/autourgos_token_memory.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[tiktoken]
+tiktoken>=0.5

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

@@ -0,0 +1 @@
+autourgos_token_memory

autourgos_token_memory-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "autourgos-token-memory"
+version = "1.0.0"
+description = "Token-bounded short-term memory for Autourgos agents — TokenBufferedMemory."
+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.optional-dependencies]
+tiktoken = ["tiktoken>=0.5"]
+
+[project.urls]
+Homepage = "https://github.com/devxjitin/autourgos-token-memory"
+Repository = "https://github.com/devxjitin/autourgos-token-memory"
+Issues = "https://github.com/devxjitin/autourgos-token-memory/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["autourgos_token_memory*"]
+
+[tool.setuptools.package-data]
+autourgos_token_memory = ["py.typed"]

autourgos_token_memory-1.0.0/setup.cfg

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