argon-agents 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- argon_agents/__init__.py +19 -0
- argon_agents/client.py +237 -0
- argon_agents/langgraph.py +96 -0
- argon_agents/mem0.py +48 -0
- argon_agents-0.1.0.dist-info/METADATA +121 -0
- argon_agents-0.1.0.dist-info/RECORD +8 -0
- argon_agents-0.1.0.dist-info/WHEEL +4 -0
- argon_agents-0.1.0.dist-info/licenses/LICENSE +23 -0
argon_agents/__init__.py
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Argon adapters for AI agent frameworks.
|
|
2
|
+
|
|
3
|
+
Argon versions MongoDB the way Git versions code. These adapters give
|
|
4
|
+
agent frameworks the two things they are missing: a disposable, isolated
|
|
5
|
+
copy of state to work against (a sandbox with a TTL), and an undo/merge
|
|
6
|
+
story for whatever the agent did to it.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from .client import ArgonClient, ArgonError, Sandbox
|
|
10
|
+
from .mem0 import sandboxed_mem0_config
|
|
11
|
+
|
|
12
|
+
__all__ = ["ArgonClient", "ArgonError", "Sandbox", "sandboxed_mem0_config"]
|
|
13
|
+
|
|
14
|
+
try: # langgraph extras are optional
|
|
15
|
+
from .langgraph import ArgonCheckpointSaver # noqa: F401
|
|
16
|
+
|
|
17
|
+
__all__.append("ArgonCheckpointSaver")
|
|
18
|
+
except ImportError: # pragma: no cover
|
|
19
|
+
pass
|
argon_agents/client.py
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
"""REST client for the Argon control plane.
|
|
2
|
+
|
|
3
|
+
The control plane (this client) manages projects, branches, sandboxes,
|
|
4
|
+
merges and undos over the Argon API server. The data plane is native
|
|
5
|
+
MongoDB: sandboxes and checked-out branches hand back ordinary connection
|
|
6
|
+
strings, and the API server captures every write into versioned history
|
|
7
|
+
through the branch's change stream.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import datetime
|
|
13
|
+
from dataclasses import dataclass, field
|
|
14
|
+
from typing import Any, Optional
|
|
15
|
+
|
|
16
|
+
import requests
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class ArgonError(RuntimeError):
|
|
20
|
+
"""An Argon control-plane call failed."""
|
|
21
|
+
|
|
22
|
+
def __init__(self, status: int, message: str):
|
|
23
|
+
super().__init__(f"{message} (HTTP {status})")
|
|
24
|
+
self.status = status
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class ArgonClient:
|
|
28
|
+
"""Client for the Argon REST API (default http://localhost:8080)."""
|
|
29
|
+
|
|
30
|
+
def __init__(self, api_url: str = "http://localhost:8080", timeout: float = 30.0):
|
|
31
|
+
self.api_url = api_url.rstrip("/")
|
|
32
|
+
self.timeout = timeout
|
|
33
|
+
self._session = requests.Session()
|
|
34
|
+
|
|
35
|
+
# -- plumbing ---------------------------------------------------------
|
|
36
|
+
|
|
37
|
+
def _call(self, method: str, path: str, json: Optional[dict] = None) -> dict:
|
|
38
|
+
response = self._session.request(
|
|
39
|
+
method, f"{self.api_url}/api/v1{path}", json=json or {}, timeout=self.timeout
|
|
40
|
+
)
|
|
41
|
+
body: dict[str, Any] = {}
|
|
42
|
+
if response.content:
|
|
43
|
+
try:
|
|
44
|
+
body = response.json()
|
|
45
|
+
except ValueError:
|
|
46
|
+
pass
|
|
47
|
+
if response.status_code >= 400:
|
|
48
|
+
raise ArgonError(response.status_code, body.get("error", response.text))
|
|
49
|
+
return body
|
|
50
|
+
|
|
51
|
+
# -- projects & branches ----------------------------------------------
|
|
52
|
+
|
|
53
|
+
def create_project(self, name: str) -> dict:
|
|
54
|
+
return self._call("POST", "/projects", {"name": name})
|
|
55
|
+
|
|
56
|
+
def get_or_create_project(self, name: str) -> None:
|
|
57
|
+
try:
|
|
58
|
+
self.create_project(name)
|
|
59
|
+
except ArgonError as exc:
|
|
60
|
+
if exc.status != 409:
|
|
61
|
+
raise
|
|
62
|
+
|
|
63
|
+
def list_branches(self, project: str) -> list[dict]:
|
|
64
|
+
return self._call("GET", f"/projects/{project}/branches")["branches"]
|
|
65
|
+
|
|
66
|
+
def branch_info(self, project: str, branch: str) -> dict:
|
|
67
|
+
return self._call("GET", f"/projects/{project}/branches/{branch}")
|
|
68
|
+
|
|
69
|
+
def create_branch(self, project: str, name: str, from_branch: str = "main") -> dict:
|
|
70
|
+
return self._call(
|
|
71
|
+
"POST", f"/projects/{project}/branches", {"name": name, "from": from_branch}
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
def delete_branch(self, project: str, branch: str) -> None:
|
|
75
|
+
self._call("DELETE", f"/projects/{project}/branches/{branch}")
|
|
76
|
+
|
|
77
|
+
def checkout(self, project: str, branch: str) -> str:
|
|
78
|
+
"""Materialize a branch and return its MongoDB connection string."""
|
|
79
|
+
return self._call("POST", f"/projects/{project}/branches/{branch}/checkout")[
|
|
80
|
+
"connection_string"
|
|
81
|
+
]
|
|
82
|
+
|
|
83
|
+
# -- sandboxes ----------------------------------------------------------
|
|
84
|
+
|
|
85
|
+
def create_sandbox(
|
|
86
|
+
self,
|
|
87
|
+
project: str,
|
|
88
|
+
from_branch: str = "main",
|
|
89
|
+
name: Optional[str] = None,
|
|
90
|
+
ttl_minutes: int = 60,
|
|
91
|
+
) -> "Sandbox":
|
|
92
|
+
body = {"from": from_branch, "ttl_minutes": ttl_minutes}
|
|
93
|
+
if name:
|
|
94
|
+
body["name"] = name
|
|
95
|
+
resp = self._call("POST", f"/projects/{project}/sandboxes", body)
|
|
96
|
+
return Sandbox(
|
|
97
|
+
_client=self,
|
|
98
|
+
project=project,
|
|
99
|
+
branch=resp["branch"],
|
|
100
|
+
connection_string=resp["connection_string"],
|
|
101
|
+
expires_at=resp["expires_at"],
|
|
102
|
+
forked_from=resp["forked_from"],
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
# -- pins (reproducible eval datasets) -----------------------------------
|
|
106
|
+
|
|
107
|
+
def create_pin(
|
|
108
|
+
self,
|
|
109
|
+
project: str,
|
|
110
|
+
name: str,
|
|
111
|
+
branch: str = "main",
|
|
112
|
+
lsn: Optional[int] = None,
|
|
113
|
+
note: Optional[str] = None,
|
|
114
|
+
) -> dict:
|
|
115
|
+
"""Pin a branch state under a name: a named, immutable dataset
|
|
116
|
+
reference that survives garbage collection and resets forever.
|
|
117
|
+
Defaults to the branch's current head."""
|
|
118
|
+
body: dict[str, Any] = {"name": name, "branch": branch}
|
|
119
|
+
if lsn is not None:
|
|
120
|
+
body["lsn"] = lsn
|
|
121
|
+
if note:
|
|
122
|
+
body["note"] = note
|
|
123
|
+
return self._call("POST", f"/projects/{project}/pins", body)
|
|
124
|
+
|
|
125
|
+
def list_pins(self, project: str) -> list[dict]:
|
|
126
|
+
return self._call("GET", f"/projects/{project}/pins")["pins"]
|
|
127
|
+
|
|
128
|
+
def delete_pin(self, project: str, name: str) -> None:
|
|
129
|
+
self._call("DELETE", f"/projects/{project}/pins/{name}")
|
|
130
|
+
|
|
131
|
+
def sandbox_from_pin(
|
|
132
|
+
self,
|
|
133
|
+
project: str,
|
|
134
|
+
pin: str,
|
|
135
|
+
name: Optional[str] = None,
|
|
136
|
+
ttl_minutes: int = 60,
|
|
137
|
+
) -> "Sandbox":
|
|
138
|
+
"""Fork a TTL sandbox that starts at exactly the pinned state —
|
|
139
|
+
the reproducible-eval workflow: pin the dataset once, fork a fresh
|
|
140
|
+
sandbox from it for every run."""
|
|
141
|
+
body: dict[str, Any] = {"ttl_minutes": ttl_minutes}
|
|
142
|
+
if name:
|
|
143
|
+
body["name"] = name
|
|
144
|
+
resp = self._call("POST", f"/projects/{project}/pins/{pin}/sandboxes", body)
|
|
145
|
+
return Sandbox(
|
|
146
|
+
_client=self,
|
|
147
|
+
project=project,
|
|
148
|
+
branch=resp["branch"],
|
|
149
|
+
connection_string=resp["connection_string"],
|
|
150
|
+
expires_at=resp["expires_at"],
|
|
151
|
+
forked_from=resp["forked_from"],
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
# -- diff / merge / undo ------------------------------------------------
|
|
155
|
+
|
|
156
|
+
def diff(self, project: str, branch: str) -> dict:
|
|
157
|
+
return self._call("GET", f"/projects/{project}/branches/{branch}/diff")
|
|
158
|
+
|
|
159
|
+
def merge_preview(self, project: str, branch: str) -> dict:
|
|
160
|
+
return self._call("POST", f"/projects/{project}/branches/{branch}/merge-preview")
|
|
161
|
+
|
|
162
|
+
def merge_apply(self, plan_id: str, strategy: Optional[str] = None) -> dict:
|
|
163
|
+
body = {"strategy": strategy} if strategy else {}
|
|
164
|
+
return self._call("POST", f"/merge-plans/{plan_id}/apply", body)
|
|
165
|
+
|
|
166
|
+
def merge(self, project: str, branch: str, strategy: Optional[str] = None) -> dict:
|
|
167
|
+
"""Preview and apply in one step."""
|
|
168
|
+
plan = self.merge_preview(project, branch)
|
|
169
|
+
return self.merge_apply(plan["id"], strategy)
|
|
170
|
+
|
|
171
|
+
def undo(
|
|
172
|
+
self,
|
|
173
|
+
project: str,
|
|
174
|
+
branch: str,
|
|
175
|
+
from_lsn: int,
|
|
176
|
+
to_lsn: Optional[int] = None,
|
|
177
|
+
actor: Optional[str] = None,
|
|
178
|
+
dry_run: bool = False,
|
|
179
|
+
) -> dict:
|
|
180
|
+
body: dict[str, Any] = {"from_lsn": from_lsn, "dry_run": dry_run}
|
|
181
|
+
if to_lsn is not None:
|
|
182
|
+
body["to_lsn"] = to_lsn
|
|
183
|
+
if actor:
|
|
184
|
+
body["actor"] = actor
|
|
185
|
+
return self._call("POST", f"/projects/{project}/branches/{branch}/undo", body)
|
|
186
|
+
|
|
187
|
+
def snapshot(self, project: str, branch: str) -> dict:
|
|
188
|
+
return self._call("POST", f"/projects/{project}/branches/{branch}/snapshots")
|
|
189
|
+
|
|
190
|
+
def time_travel_info(self, project: str, branch: str) -> dict:
|
|
191
|
+
return self._call("GET", f"/projects/{project}/branches/{branch}/time-travel")
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
@dataclass
|
|
195
|
+
class Sandbox:
|
|
196
|
+
"""A disposable, versioned copy of a branch, with a TTL.
|
|
197
|
+
|
|
198
|
+
Point any MongoDB client at ``connection_string``; every write becomes
|
|
199
|
+
versioned history. ``merge()`` brings the work back to the parent,
|
|
200
|
+
``discard()`` throws it away, the TTL reclaims whatever is left.
|
|
201
|
+
"""
|
|
202
|
+
|
|
203
|
+
project: str
|
|
204
|
+
branch: str
|
|
205
|
+
connection_string: str
|
|
206
|
+
expires_at: str
|
|
207
|
+
forked_from: str
|
|
208
|
+
_client: ArgonClient = field(repr=False, default=None)
|
|
209
|
+
|
|
210
|
+
@property
|
|
211
|
+
def database_name(self) -> str:
|
|
212
|
+
"""The physical database name inside the connection string."""
|
|
213
|
+
path = self.connection_string.split("://", 1)[1]
|
|
214
|
+
db = path.split("/", 1)[1] if "/" in path else ""
|
|
215
|
+
return db.split("?", 1)[0]
|
|
216
|
+
|
|
217
|
+
def pymongo_database(self):
|
|
218
|
+
"""A pymongo Database handle for the sandbox (lazy import)."""
|
|
219
|
+
from pymongo import MongoClient
|
|
220
|
+
|
|
221
|
+
return MongoClient(self.connection_string).get_default_database()
|
|
222
|
+
|
|
223
|
+
def diff(self) -> dict:
|
|
224
|
+
return self._client.diff(self.project, self.branch)
|
|
225
|
+
|
|
226
|
+
def merge(self, strategy: Optional[str] = None) -> dict:
|
|
227
|
+
return self._client.merge(self.project, self.branch, strategy)
|
|
228
|
+
|
|
229
|
+
def keep_days_note(self) -> str: # pragma: no cover - convenience only
|
|
230
|
+
return f"expires {self.expires_at}"
|
|
231
|
+
|
|
232
|
+
def discard(self) -> None:
|
|
233
|
+
self._client.delete_branch(self.project, self.branch)
|
|
234
|
+
|
|
235
|
+
@property
|
|
236
|
+
def expires(self) -> datetime.datetime:
|
|
237
|
+
return datetime.datetime.fromisoformat(self.expires_at.replace("Z", "+00:00"))
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"""LangGraph checkpointing on versioned, sandboxed MongoDB.
|
|
2
|
+
|
|
3
|
+
``ArgonCheckpointSaver`` is the official ``langgraph-checkpoint-mongodb``
|
|
4
|
+
saver pointed at an Argon branch, plus the operations MongoDB alone cannot
|
|
5
|
+
give you:
|
|
6
|
+
|
|
7
|
+
- ``from_sandbox``: fork the whole memory state into a disposable,
|
|
8
|
+
TTL-stamped copy and checkpoint an agent against it — production
|
|
9
|
+
checkpoints are never at risk.
|
|
10
|
+
- ``fork``: branch the entire checkpoint history (every thread) at its
|
|
11
|
+
current state, cheaply, and get an independent saver for the copy.
|
|
12
|
+
- ``merge`` / ``discard`` on the underlying sandbox to adopt or reject
|
|
13
|
+
whatever the agent's run produced.
|
|
14
|
+
|
|
15
|
+
LangGraph's own checkpoint ids give you step-level rewind *within* a
|
|
16
|
+
thread; Argon gives you branch-level fork/undo/audit *across* the whole
|
|
17
|
+
store.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
from typing import Optional
|
|
23
|
+
|
|
24
|
+
from langgraph.checkpoint.mongodb import MongoDBSaver
|
|
25
|
+
from pymongo import MongoClient
|
|
26
|
+
|
|
27
|
+
from .client import ArgonClient, Sandbox
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class ArgonCheckpointSaver(MongoDBSaver):
|
|
31
|
+
"""The official MongoDB checkpointer, running on an Argon branch."""
|
|
32
|
+
|
|
33
|
+
def __init__(self, connection_string: str, *, sandbox: Optional[Sandbox] = None, **kwargs):
|
|
34
|
+
client = MongoClient(connection_string)
|
|
35
|
+
db_name = client.get_default_database().name
|
|
36
|
+
super().__init__(client, db_name=db_name, **kwargs)
|
|
37
|
+
self.sandbox = sandbox
|
|
38
|
+
|
|
39
|
+
# -- constructors -------------------------------------------------------
|
|
40
|
+
|
|
41
|
+
@classmethod
|
|
42
|
+
def from_sandbox(
|
|
43
|
+
cls,
|
|
44
|
+
argon: ArgonClient,
|
|
45
|
+
project: str,
|
|
46
|
+
from_branch: str = "main",
|
|
47
|
+
name: Optional[str] = None,
|
|
48
|
+
ttl_minutes: int = 60,
|
|
49
|
+
**kwargs,
|
|
50
|
+
) -> "ArgonCheckpointSaver":
|
|
51
|
+
"""Fork a sandbox and checkpoint against it.
|
|
52
|
+
|
|
53
|
+
The saver's ``sandbox`` attribute exposes ``merge()`` and
|
|
54
|
+
``discard()``; the TTL reclaims the sandbox if neither happens.
|
|
55
|
+
"""
|
|
56
|
+
sandbox = argon.create_sandbox(
|
|
57
|
+
project, from_branch=from_branch, name=name, ttl_minutes=ttl_minutes
|
|
58
|
+
)
|
|
59
|
+
return cls(sandbox.connection_string, sandbox=sandbox, **kwargs)
|
|
60
|
+
|
|
61
|
+
@classmethod
|
|
62
|
+
def for_branch(cls, argon: ArgonClient, project: str, branch: str = "main", **kwargs):
|
|
63
|
+
"""Checkpoint against a (checked-out) long-lived branch."""
|
|
64
|
+
return cls(argon.checkout(project, branch), **kwargs)
|
|
65
|
+
|
|
66
|
+
# -- Argon superpowers ---------------------------------------------------
|
|
67
|
+
|
|
68
|
+
def fork(
|
|
69
|
+
self,
|
|
70
|
+
argon: ArgonClient,
|
|
71
|
+
name: Optional[str] = None,
|
|
72
|
+
ttl_minutes: int = 60,
|
|
73
|
+
) -> "ArgonCheckpointSaver":
|
|
74
|
+
"""Fork the entire checkpoint store (all threads) at its current
|
|
75
|
+
state into a new sandbox and return a saver for the copy."""
|
|
76
|
+
if self.sandbox is None:
|
|
77
|
+
raise ValueError("fork() needs a saver created via from_sandbox()")
|
|
78
|
+
return self.from_sandbox(
|
|
79
|
+
argon,
|
|
80
|
+
self.sandbox.project,
|
|
81
|
+
from_branch=self.sandbox.branch,
|
|
82
|
+
name=name,
|
|
83
|
+
ttl_minutes=ttl_minutes,
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
def merge(self, strategy: Optional[str] = None) -> dict:
|
|
87
|
+
"""Adopt the sandboxed checkpoints into the parent branch."""
|
|
88
|
+
if self.sandbox is None:
|
|
89
|
+
raise ValueError("merge() needs a saver created via from_sandbox()")
|
|
90
|
+
return self.sandbox.merge(strategy)
|
|
91
|
+
|
|
92
|
+
def discard(self) -> None:
|
|
93
|
+
"""Throw the sandboxed run away and reclaim its storage."""
|
|
94
|
+
if self.sandbox is None:
|
|
95
|
+
raise ValueError("discard() needs a saver created via from_sandbox()")
|
|
96
|
+
self.sandbox.discard()
|
argon_agents/mem0.py
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""Sandboxed Mem0 configuration on versioned MongoDB.
|
|
2
|
+
|
|
3
|
+
Mem0 speaks MongoDB natively; what it lacks is a way to experiment on a
|
|
4
|
+
copy of an agent's memory and merge or reject the outcome. This factory
|
|
5
|
+
provisions an Argon sandbox and returns a Mem0 ``config`` dict whose
|
|
6
|
+
MongoDB vector store points at it — plus the sandbox handle for
|
|
7
|
+
``merge()`` / ``discard()`` and TTL-based cleanup.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from typing import Optional, Tuple
|
|
13
|
+
|
|
14
|
+
from .client import ArgonClient, Sandbox
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def sandboxed_mem0_config(
|
|
18
|
+
argon: ArgonClient,
|
|
19
|
+
project: str,
|
|
20
|
+
from_branch: str = "main",
|
|
21
|
+
collection_name: str = "mem0",
|
|
22
|
+
embedding_model_dims: int = 1536,
|
|
23
|
+
ttl_minutes: int = 60,
|
|
24
|
+
name: Optional[str] = None,
|
|
25
|
+
) -> Tuple[dict, Sandbox]:
|
|
26
|
+
"""Provision a sandbox and return (mem0_config, sandbox).
|
|
27
|
+
|
|
28
|
+
Usage::
|
|
29
|
+
|
|
30
|
+
config, sandbox = sandboxed_mem0_config(argon, "my-project")
|
|
31
|
+
memory = Memory.from_config({"vector_store": config, ...})
|
|
32
|
+
... # let the agent read and write memories
|
|
33
|
+
sandbox.merge() # adopt the new memories
|
|
34
|
+
# or sandbox.discard(), or just let the TTL reclaim it
|
|
35
|
+
"""
|
|
36
|
+
sandbox = argon.create_sandbox(
|
|
37
|
+
project, from_branch=from_branch, name=name, ttl_minutes=ttl_minutes
|
|
38
|
+
)
|
|
39
|
+
config = {
|
|
40
|
+
"provider": "mongodb",
|
|
41
|
+
"config": {
|
|
42
|
+
"mongo_uri": sandbox.connection_string,
|
|
43
|
+
"db_name": sandbox.database_name,
|
|
44
|
+
"collection_name": collection_name,
|
|
45
|
+
"embedding_model_dims": embedding_model_dims,
|
|
46
|
+
},
|
|
47
|
+
}
|
|
48
|
+
return config, sandbox
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: argon-agents
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Argon adapters for AI agent frameworks: sandboxed, versioned MongoDB for LangGraph and Mem0
|
|
5
|
+
Project-URL: Homepage, https://github.com/argon-lab/argon-agents
|
|
6
|
+
Project-URL: Engine, https://github.com/argon-lab/argon
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Python: >=3.10
|
|
10
|
+
Requires-Dist: pymongo>=4.6
|
|
11
|
+
Requires-Dist: requests>=2.31
|
|
12
|
+
Provides-Extra: dev
|
|
13
|
+
Requires-Dist: langgraph-checkpoint-mongodb>=0.1; extra == 'dev'
|
|
14
|
+
Requires-Dist: langgraph>=0.2; extra == 'dev'
|
|
15
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
16
|
+
Provides-Extra: langgraph
|
|
17
|
+
Requires-Dist: langgraph-checkpoint-mongodb>=0.1; extra == 'langgraph'
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
|
|
20
|
+
# argon-agents
|
|
21
|
+
|
|
22
|
+
Argon adapters for AI agent frameworks: **sandboxed, versioned MongoDB**
|
|
23
|
+
for LangGraph and Mem0.
|
|
24
|
+
|
|
25
|
+
[Argon](https://github.com/argon-lab/argon) versions MongoDB the way Git
|
|
26
|
+
versions code — branch, time-travel, diff, merge, undo. This package gives
|
|
27
|
+
agent frameworks the two things plain MongoDB can't:
|
|
28
|
+
|
|
29
|
+
1. **A disposable copy of state to work against.** Fork a sandbox with a
|
|
30
|
+
TTL, point the agent at an ordinary connection string, and production
|
|
31
|
+
data is never at risk.
|
|
32
|
+
2. **An adopt-or-reject story for what the agent did.** Diff the sandbox,
|
|
33
|
+
merge it back (with conflict strategies), undo any range, or just let
|
|
34
|
+
the TTL reclaim it.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install argon-agents # client + Mem0 factory
|
|
40
|
+
pip install "argon-agents[langgraph]" # + the LangGraph checkpointer
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Requires a running [Argon API server](https://github.com/argon-lab/argon)
|
|
44
|
+
(`cd api && go run .`) backed by a MongoDB replica set.
|
|
45
|
+
|
|
46
|
+
## The client
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from argon_agents import ArgonClient
|
|
50
|
+
|
|
51
|
+
argon = ArgonClient("http://localhost:8080")
|
|
52
|
+
argon.create_project("support-bot")
|
|
53
|
+
|
|
54
|
+
sandbox = argon.create_sandbox("support-bot", ttl_minutes=60)
|
|
55
|
+
db = sandbox.pymongo_database() # plain pymongo, isolated copy
|
|
56
|
+
db.tickets.insert_one({"_id": "t1", "status": "resolved"})
|
|
57
|
+
|
|
58
|
+
print(sandbox.diff()) # what the agent changed
|
|
59
|
+
sandbox.merge() # adopt it — or sandbox.discard()
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## LangGraph
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from argon_agents import ArgonClient, ArgonCheckpointSaver
|
|
66
|
+
|
|
67
|
+
argon = ArgonClient()
|
|
68
|
+
saver = ArgonCheckpointSaver.from_sandbox(argon, "support-bot", ttl_minutes=60)
|
|
69
|
+
|
|
70
|
+
graph = builder.compile(checkpointer=saver) # any LangGraph graph
|
|
71
|
+
graph.invoke(input, {"configurable": {"thread_id": "user-42"}})
|
|
72
|
+
|
|
73
|
+
saver.merge() # keep the run's checkpoints
|
|
74
|
+
# saver.discard() # or reject them
|
|
75
|
+
# saver.fork(argon) # or branch the entire memory state and try both
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`ArgonCheckpointSaver` *is* the official `langgraph-checkpoint-mongodb`
|
|
79
|
+
saver — same wire format, same semantics — running on an Argon branch.
|
|
80
|
+
LangGraph's checkpoint ids give step-level rewind within a thread; Argon
|
|
81
|
+
adds branch-level fork/merge/undo/audit across the whole store.
|
|
82
|
+
|
|
83
|
+
## Mem0
|
|
84
|
+
|
|
85
|
+
Mem0 speaks MongoDB natively; Argon supplies the versioned sandbox:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from argon_agents import ArgonClient, sandboxed_mem0_config
|
|
89
|
+
from mem0 import Memory
|
|
90
|
+
|
|
91
|
+
argon = ArgonClient()
|
|
92
|
+
config, sandbox = sandboxed_mem0_config(argon, "support-bot")
|
|
93
|
+
memory = Memory.from_config({"vector_store": config})
|
|
94
|
+
|
|
95
|
+
# ... let the agent read/write memories ...
|
|
96
|
+
sandbox.merge() # adopt the new memories, or discard(), or let the TTL run
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Reproducible evals: dataset pins
|
|
100
|
+
|
|
101
|
+
A pin is a named, immutable reference to a branch state that survives
|
|
102
|
+
garbage collection and resets forever. Pin the eval dataset once; fork a
|
|
103
|
+
fresh sandbox from the pin for every run; every run starts identical:
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
argon.create_pin("my-project", "eval-v1", note="golden dataset")
|
|
107
|
+
|
|
108
|
+
run = argon.sandbox_from_pin("my-project", "eval-v1", ttl_minutes=30)
|
|
109
|
+
# ... run the eval against run.connection_string ...
|
|
110
|
+
run.discard() # the pin itself is untouched — fork again anytime
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Tests
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install -e ".[dev]"
|
|
117
|
+
pytest # skips itself unless an Argon stack is reachable
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
CI builds the engine from `argon-lab/argon@master`, starts a replica-set
|
|
121
|
+
MongoDB and the API server, and runs the full suite.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
argon_agents/__init__.py,sha256=KetXtbQTUUxn_5NslJHrvNrC6zuPjGevSNX7vaz01wQ,668
|
|
2
|
+
argon_agents/client.py,sha256=uKxppdTQAJFfPJeWYZy0PzfWiLXk6xcYon0_qTfKvis,8587
|
|
3
|
+
argon_agents/langgraph.py,sha256=Yz_RJPsZfKP_wPO1E3BEmdkSsgePDhsYk21LZ22NXSA,3604
|
|
4
|
+
argon_agents/mem0.py,sha256=uqYrVX4BnGEh_GhXrzpiQTNZ9ya3DkeSCl33G45hrxQ,1587
|
|
5
|
+
argon_agents-0.1.0.dist-info/METADATA,sha256=QCTAJEdFRWmM-e9ue9njxfB8oCfUcTySz0VypOEJUBE,4130
|
|
6
|
+
argon_agents-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
|
|
7
|
+
argon_agents-0.1.0.dist-info/licenses/LICENSE,sha256=9B_nvN3Bp-KSspM_WuE4vZMukdVnRYIXohp53kkHWDA,1075
|
|
8
|
+
argon_agents-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
|
|
3
|
+
MIT License
|
|
4
|
+
|
|
5
|
+
Copyright (c) 2025 Jake Wang
|
|
6
|
+
|
|
7
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
8
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
9
|
+
in the Software without restriction, including without limitation the rights
|
|
10
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
11
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
12
|
+
furnished to do so, subject to the following conditions:
|
|
13
|
+
|
|
14
|
+
The above copyright notice and this permission notice shall be included in all
|
|
15
|
+
copies or substantial portions of the Software.
|
|
16
|
+
|
|
17
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
18
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
19
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
20
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
21
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
22
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
23
|
+
SOFTWARE.
|