autourgos-memory 1.0.2__tar.gz

autourgos_memory-1.0.2/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_memory-1.0.2/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: autourgos-memory
+Version: 1.0.2
+Summary: Base memory interfaces for Autourgos agents — BaseMemory, MemoryMessage, Document, BaseRetriever.
+Author-email: Jitin Kumar Sengar <devxjitin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/devxjitin/autourgos-memory
+Project-URL: Repository, https://github.com/devxjitin/autourgos-memory
+Project-URL: Issues, https://github.com/devxjitin/autourgos-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-memory
+
+Base memory interfaces for [Autourgos](https://github.com/devxjitin) agents.
+
+This is the **foundation package** — it defines the abstract interfaces (`BaseMemory`, `BaseRetriever`, `MemoryMessage`, `Document`) that all concrete memory implementations use. Install it on its own, or install one of the concrete packages that depend on it.
+
+---
+
+## Install
+
+```bash
+# Base interfaces only
+pip install autourgos-memory
+
+# Or install concrete implementations individually
+pip install autourgos-buffer-memory    # in-memory ring buffer
+pip install autourgos-local-memory     # JSON file + SQLite
+pip install autourgos-semantic-memory  # TF-IDF keyword retrieval
+pip install autourgos-summary-memory   # LLM-compressed rolling summary
+pip install autourgos-token-memory     # token-bounded buffer
+```
+
+---
+
+## Memory types at a glance
+
+| Package | Class | Best for |
+|---|---|---|
+| `autourgos-buffer-memory` | `RuntimeShortTermMemory` | Fast in-memory buffer, message-count bounded |
+| `autourgos-buffer-memory` | `ConversationBufferMemory` | Unbounded in-memory buffer |
+| `autourgos-local-memory` | `LocalShortTermMemory` | Disk persistence via JSON file |
+| `autourgos-local-memory` | `SQLiteMemory` | Disk persistence via SQLite, concurrent-safe |
+| `autourgos-semantic-memory` | `KeywordMemory` | TF-IDF retrieval of relevant past context |
+| `autourgos-summary-memory` | `SummaryBufferedMemory` | LLM-compressed history to save tokens |
+| `autourgos-token-memory` | `TokenBufferedMemory` | Token-budget bounded buffer |
+
+---
+
+## Quick start (with concrete packages installed)
+
+`RuntimeShortTermMemory` is soft re-exported from `autourgos_memory` — it only resolves if `autourgos-buffer-memory` is also installed:
+
+```bash
+pip install autourgos-memory autourgos-buffer-memory autourgos-openaichat
+```
+
+```python
+from autourgos_memory import RuntimeShortTermMemory  # requires autourgos-buffer-memory installed
+from autourgos_react_agent import ReactAgent
+from autourgos_openaichat import OpenAIChatModel
+
+my_llm = OpenAIChatModel(model="gpt-4o-mini")  # needs OPENAI_API_KEY set
+memory = RuntimeShortTermMemory(max_messages=20)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+result = agent.invoke("What did I ask you last time?")
+```
+
+---
+
+## Base interfaces
+
+### MemoryMessage
+
+```python
+from autourgos_memory import MemoryMessage
+from datetime import datetime, timezone
+
+msg = MemoryMessage(role="user", content="Hello", timestamp=datetime.now(timezone.utc))
+print(msg.to_dict())
+# {"role": "user", "content": "Hello", "timestamp": "2024-..."}
+```
+
+Allowed roles: `user`, `agent`, `system`, `tool`.
+
+### BaseMemory
+
+Implement this to create your own memory backend:
+
+```python
+from autourgos_memory import BaseMemory, MemoryMessage
+
+class MyCustomMemory(BaseMemory):
+    def add_user_message(self, content: str) -> MemoryMessage: ...
+    def add_agent_message(self, content: str) -> MemoryMessage: ...
+    def add_tool_message(self, tool_name: str, result: str) -> MemoryMessage: ...
+    def format_for_llm(self, query: str = None) -> str: ...
+    def clear(self) -> None: ...
+```
+
+### BaseRetriever
+
+Implement this to plug in your own vector database:
+
+```python
+from autourgos_memory import BaseRetriever, Document
+
+class MyVectorDB(BaseRetriever):
+    def retrieve(self, query: str, top_k: int = 5) -> list[Document]: ...
+```
+
+### Document
+
+```python
+from autourgos_memory import Document
+
+doc = Document(content="Paris is the capital of France.", score=0.92, source="wiki")
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-memory/
+- GitHub: https://github.com/devxjitin/autourgos-memory
+- Issues: https://github.com/devxjitin/autourgos-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_memory-1.0.2/README.md

@@ -0,0 +1,121 @@
+# autourgos-memory
+
+Base memory interfaces for [Autourgos](https://github.com/devxjitin) agents.
+
+This is the **foundation package** — it defines the abstract interfaces (`BaseMemory`, `BaseRetriever`, `MemoryMessage`, `Document`) that all concrete memory implementations use. Install it on its own, or install one of the concrete packages that depend on it.
+
+---
+
+## Install
+
+```bash
+# Base interfaces only
+pip install autourgos-memory
+
+# Or install concrete implementations individually
+pip install autourgos-buffer-memory    # in-memory ring buffer
+pip install autourgos-local-memory     # JSON file + SQLite
+pip install autourgos-semantic-memory  # TF-IDF keyword retrieval
+pip install autourgos-summary-memory   # LLM-compressed rolling summary
+pip install autourgos-token-memory     # token-bounded buffer
+```
+
+---
+
+## Memory types at a glance
+
+| Package | Class | Best for |
+|---|---|---|
+| `autourgos-buffer-memory` | `RuntimeShortTermMemory` | Fast in-memory buffer, message-count bounded |
+| `autourgos-buffer-memory` | `ConversationBufferMemory` | Unbounded in-memory buffer |
+| `autourgos-local-memory` | `LocalShortTermMemory` | Disk persistence via JSON file |
+| `autourgos-local-memory` | `SQLiteMemory` | Disk persistence via SQLite, concurrent-safe |
+| `autourgos-semantic-memory` | `KeywordMemory` | TF-IDF retrieval of relevant past context |
+| `autourgos-summary-memory` | `SummaryBufferedMemory` | LLM-compressed history to save tokens |
+| `autourgos-token-memory` | `TokenBufferedMemory` | Token-budget bounded buffer |
+
+---
+
+## Quick start (with concrete packages installed)
+
+`RuntimeShortTermMemory` is soft re-exported from `autourgos_memory` — it only resolves if `autourgos-buffer-memory` is also installed:
+
+```bash
+pip install autourgos-memory autourgos-buffer-memory autourgos-openaichat
+```
+
+```python
+from autourgos_memory import RuntimeShortTermMemory  # requires autourgos-buffer-memory installed
+from autourgos_react_agent import ReactAgent
+from autourgos_openaichat import OpenAIChatModel
+
+my_llm = OpenAIChatModel(model="gpt-4o-mini")  # needs OPENAI_API_KEY set
+memory = RuntimeShortTermMemory(max_messages=20)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+result = agent.invoke("What did I ask you last time?")
+```
+
+---
+
+## Base interfaces
+
+### MemoryMessage
+
+```python
+from autourgos_memory import MemoryMessage
+from datetime import datetime, timezone
+
+msg = MemoryMessage(role="user", content="Hello", timestamp=datetime.now(timezone.utc))
+print(msg.to_dict())
+# {"role": "user", "content": "Hello", "timestamp": "2024-..."}
+```
+
+Allowed roles: `user`, `agent`, `system`, `tool`.
+
+### BaseMemory
+
+Implement this to create your own memory backend:
+
+```python
+from autourgos_memory import BaseMemory, MemoryMessage
+
+class MyCustomMemory(BaseMemory):
+    def add_user_message(self, content: str) -> MemoryMessage: ...
+    def add_agent_message(self, content: str) -> MemoryMessage: ...
+    def add_tool_message(self, tool_name: str, result: str) -> MemoryMessage: ...
+    def format_for_llm(self, query: str = None) -> str: ...
+    def clear(self) -> None: ...
+```
+
+### BaseRetriever
+
+Implement this to plug in your own vector database:
+
+```python
+from autourgos_memory import BaseRetriever, Document
+
+class MyVectorDB(BaseRetriever):
+    def retrieve(self, query: str, top_k: int = 5) -> list[Document]: ...
+```
+
+### Document
+
+```python
+from autourgos_memory import Document
+
+doc = Document(content="Paris is the capital of France.", score=0.92, source="wiki")
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-memory/
+- GitHub: https://github.com/devxjitin/autourgos-memory
+- Issues: https://github.com/devxjitin/autourgos-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_memory-1.0.2/autourgos_memory/__init__.py

@@ -0,0 +1,55 @@
+"""
+autourgos-memory — Base memory interfaces for Autourgos.
+
+Install the full suite::
+
+    pip install autourgos-memory autourgos-buffer-memory autourgos-local-memory
+    pip install autourgos-semantic-memory autourgos-summary-memory autourgos-token-memory
+
+Quick imports::
+
+    from autourgos_memory import BaseMemory, MemoryMessage, Document, BaseRetriever
+"""
+import logging
+
+from .base import BaseMemory, BaseRetriever, Document, MemoryMessage
+
+logger = logging.getLogger(__name__)
+
+# soft re-exports of concrete implementations
+try:
+    from autourgos_buffer_memory import RuntimeShortTermMemory, ConversationBufferMemory
+except ImportError:
+    pass
+try:
+    from autourgos_local_memory import LocalShortTermMemory, SQLiteMemory
+except ImportError:
+    pass
+try:
+    from autourgos_semantic_memory import KeywordRetriever, KeywordMemory, SimpleSemanticRetriever, HierarchicalSemanticMemory
+except ImportError:
+    pass
+try:
+    from autourgos_summary_memory import SummaryBufferedMemory
+except ImportError:
+    pass
+try:
+    from autourgos_token_memory import TokenBufferedMemory
+except ImportError:
+    pass
+
+try:
+    from importlib.metadata import version as _v
+    __version__ = _v("autourgos-memory")
+except Exception:
+    logger.debug("could not resolve installed version for autourgos-memory", exc_info=True)
+    __version__ = "1.0.2"
+
+__all__ = [
+    "BaseMemory", "BaseRetriever", "Document", "MemoryMessage",
+    "RuntimeShortTermMemory", "ConversationBufferMemory",
+    "LocalShortTermMemory", "SQLiteMemory",
+    "KeywordRetriever", "KeywordMemory", "SimpleSemanticRetriever", "HierarchicalSemanticMemory",
+    "SummaryBufferedMemory",
+    "TokenBufferedMemory",
+]

autourgos_memory-1.0.2/autourgos_memory/base.py

@@ -0,0 +1,102 @@
+"""
+base.py — Core memory interfaces for Autourgos.
+"""
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+import warnings
+
+_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}'. 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("Invalid message payload: 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_memory-1.0.2/autourgos_memory.egg-info/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: autourgos-memory
+Version: 1.0.2
+Summary: Base memory interfaces for Autourgos agents — BaseMemory, MemoryMessage, Document, BaseRetriever.
+Author-email: Jitin Kumar Sengar <devxjitin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/devxjitin/autourgos-memory
+Project-URL: Repository, https://github.com/devxjitin/autourgos-memory
+Project-URL: Issues, https://github.com/devxjitin/autourgos-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-memory
+
+Base memory interfaces for [Autourgos](https://github.com/devxjitin) agents.
+
+This is the **foundation package** — it defines the abstract interfaces (`BaseMemory`, `BaseRetriever`, `MemoryMessage`, `Document`) that all concrete memory implementations use. Install it on its own, or install one of the concrete packages that depend on it.
+
+---
+
+## Install
+
+```bash
+# Base interfaces only
+pip install autourgos-memory
+
+# Or install concrete implementations individually
+pip install autourgos-buffer-memory    # in-memory ring buffer
+pip install autourgos-local-memory     # JSON file + SQLite
+pip install autourgos-semantic-memory  # TF-IDF keyword retrieval
+pip install autourgos-summary-memory   # LLM-compressed rolling summary
+pip install autourgos-token-memory     # token-bounded buffer
+```
+
+---
+
+## Memory types at a glance
+
+| Package | Class | Best for |
+|---|---|---|
+| `autourgos-buffer-memory` | `RuntimeShortTermMemory` | Fast in-memory buffer, message-count bounded |
+| `autourgos-buffer-memory` | `ConversationBufferMemory` | Unbounded in-memory buffer |
+| `autourgos-local-memory` | `LocalShortTermMemory` | Disk persistence via JSON file |
+| `autourgos-local-memory` | `SQLiteMemory` | Disk persistence via SQLite, concurrent-safe |
+| `autourgos-semantic-memory` | `KeywordMemory` | TF-IDF retrieval of relevant past context |
+| `autourgos-summary-memory` | `SummaryBufferedMemory` | LLM-compressed history to save tokens |
+| `autourgos-token-memory` | `TokenBufferedMemory` | Token-budget bounded buffer |
+
+---
+
+## Quick start (with concrete packages installed)
+
+`RuntimeShortTermMemory` is soft re-exported from `autourgos_memory` — it only resolves if `autourgos-buffer-memory` is also installed:
+
+```bash
+pip install autourgos-memory autourgos-buffer-memory autourgos-openaichat
+```
+
+```python
+from autourgos_memory import RuntimeShortTermMemory  # requires autourgos-buffer-memory installed
+from autourgos_react_agent import ReactAgent
+from autourgos_openaichat import OpenAIChatModel
+
+my_llm = OpenAIChatModel(model="gpt-4o-mini")  # needs OPENAI_API_KEY set
+memory = RuntimeShortTermMemory(max_messages=20)
+agent  = ReactAgent(llm=my_llm, memory=memory)
+result = agent.invoke("What did I ask you last time?")
+```
+
+---
+
+## Base interfaces
+
+### MemoryMessage
+
+```python
+from autourgos_memory import MemoryMessage
+from datetime import datetime, timezone
+
+msg = MemoryMessage(role="user", content="Hello", timestamp=datetime.now(timezone.utc))
+print(msg.to_dict())
+# {"role": "user", "content": "Hello", "timestamp": "2024-..."}
+```
+
+Allowed roles: `user`, `agent`, `system`, `tool`.
+
+### BaseMemory
+
+Implement this to create your own memory backend:
+
+```python
+from autourgos_memory import BaseMemory, MemoryMessage
+
+class MyCustomMemory(BaseMemory):
+    def add_user_message(self, content: str) -> MemoryMessage: ...
+    def add_agent_message(self, content: str) -> MemoryMessage: ...
+    def add_tool_message(self, tool_name: str, result: str) -> MemoryMessage: ...
+    def format_for_llm(self, query: str = None) -> str: ...
+    def clear(self) -> None: ...
+```
+
+### BaseRetriever
+
+Implement this to plug in your own vector database:
+
+```python
+from autourgos_memory import BaseRetriever, Document
+
+class MyVectorDB(BaseRetriever):
+    def retrieve(self, query: str, top_k: int = 5) -> list[Document]: ...
+```
+
+### Document
+
+```python
+from autourgos_memory import Document
+
+doc = Document(content="Paris is the capital of France.", score=0.92, source="wiki")
+```
+
+---
+
+## Links
+
+- PyPI: https://pypi.org/project/autourgos-memory/
+- GitHub: https://github.com/devxjitin/autourgos-memory
+- Issues: https://github.com/devxjitin/autourgos-memory/issues
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_memory-1.0.2/autourgos_memory.egg-info/SOURCES.txt

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

autourgos_memory-1.0.2/autourgos_memory.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

autourgos_memory-1.0.2/autourgos_memory.egg-info/top_level.txt

@@ -0,0 +1 @@
+autourgos_memory

autourgos_memory-1.0.2/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "autourgos-memory"
+version = "1.0.2"
+description = "Base memory interfaces for Autourgos agents — BaseMemory, MemoryMessage, Document, BaseRetriever."
+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-memory"
+Repository = "https://github.com/devxjitin/autourgos-memory"
+Issues = "https://github.com/devxjitin/autourgos-memory/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["autourgos_memory*"]
+
+[tool.setuptools.package-data]
+autourgos_memory = ["py.typed"]

autourgos_memory-1.0.2/setup.cfg

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