upoch 0.1.0__tar.gz

upoch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Upoch
+
+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.

upoch-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: upoch
+Version: 0.1.0
+Summary: Upoch Guard for Python agents: verifiable checkpoints, recovery and rollback on Robinhood Chain, with a one-line LangChain and LangGraph callback.
+License-Expression: MIT
+Project-URL: Homepage, https://upoch.tech
+Project-URL: Documentation, https://upoch.tech/docs
+Keywords: upoch,ai-agents,checkpoint,recovery,rollback,robinhood-chain,langchain,langgraph
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=1.0; extra == "langchain"
+Dynamic: license-file
+
+# upoch: Upoch Guard for Python agents
+
+Give your Python agent a memory and an undo button.
+
+Upoch Guard saves verifiable checkpoints of an agent's work on Robinhood Chain. If the agent crashes, gets a bad
+prompt or makes a bad trade, it restores the last good state, checked against the chain, or rolls back to the
+checkpoint before the mistake and keeps going. It also knows which of its actions already happened.
+
+Website and debugger: https://upoch.tech. Contract (Robinhood Chain, 4663): `0x6179d9123c3c1f9e82f948101a4350cb55aa8c27`
+
+## Setup
+
+Once, in your own terminal. You need Node.js 24 or later, because the `upoch` command holds the keys and does the
+signing:
+
+```sh
+npm install -g @upoch/guard
+upoch setup
+```
+
+`upoch setup` creates your keys in `~/.upoch`, waits while you send the owner address a little ETH on Robinhood
+Chain (0.001 ETH is plenty), and registers your agent. Then:
+
+```sh
+pip install upoch                 # or: pip install "upoch[langchain]"
+```
+
+## LangChain and LangGraph
+
+One line: every consequential tool call (swaps, transfers, bridges, staking, lending, trades, mints, launches and
+approvals) is checkpointed before and after it runs. The pre-tool checkpoint is committed before the tool runs,
+with `invoke` and `ainvoke`.
+
+```python
+from upoch.langchain import UpochCallbackHandler, upoch_tools
+
+upoch = UpochCallbackHandler()
+
+# Automatic checkpoints around consequential tool calls:
+agent.invoke(inputs, config={"callbacks": [upoch]})
+
+# Optional: let the model restore, checkpoint and roll back itself.
+tools = [*your_tools, *upoch_tools(handler=upoch)]
+```
+
+| Tool | |
+|---|---|
+| `upoch_restore` | Latest checkpoint, verified against the chain, and which actions completed |
+| `upoch_checkpoint` | Save the current state |
+| `upoch_rollback` | Go back to an earlier checkpoint and continue. By default, the one right before the last swap or transfer |
+| `upoch_history` | Recent checkpoints |
+| `upoch_complete` | Mark the task finished |
+
+Options:
+
+```python
+UpochCallbackHandler(
+    watch=["swap_tokens", "send_eth"],   # exact tool names, or a compiled regex (default: value-moving names)
+    state=lambda: my_agent_state,        # what each checkpoint holds (default: the log of watched tool calls)
+    strict=True,                         # stop the tool when its pre-tool checkpoint fails (default False)
+)
+```
+
+## Any Python agent
+
+```python
+from upoch import Guard
+
+with Guard() as guard:
+    restored = guard.restore()            # where the last run stopped, verified against the chain
+    state = restored.get("state") or {"step": 0}
+
+    guard.record_action("swap-1", "swap", "planned", input={"sell": "WETH", "qty": 0.1})
+    guard.checkpoint(state, note="before swap", kind="before_action")
+    tx = do_the_swap()
+    guard.record_action("swap-1", "swap", "confirmed", transaction_hash=tx)
+    guard.checkpoint({**state, "step": 1}, note="after swap", kind="after_action")
+
+    # Something went wrong? Go back to the checkpoint before it:
+    guard.rollback(0, reason="the swap was the wrong size")
+```
+
+| Method | What it does | On-chain |
+|---|---|---|
+| `restore(sequence=None)` | Latest (or a given) checkpoint after verifying it: state, note, completed and unresolved actions | read |
+| `checkpoint(state, note, kind)` | Saves the state (`progress`, `before_action`, `after_action`, `manual`) | 1 transaction |
+| `record_action(...)` | Records an external action (planned, submitted, confirmed, failed) with its transaction hash | no (goes into the next checkpoint) |
+| `rollback(sequence, reason)` | Goes back to an earlier checkpoint and continues from it; lists actions since then that were not undone on-chain | 1 transaction |
+| `complete(state, note)` | Saves a final checkpoint and marks the run finished | 1 transaction |
+| `history(limit)` | Recent checkpoints | read |
+| `verify(sequence)` | Verifies one checkpoint without restoring it | read |
+| `status()` | Workflow, executor funds and today's usage | read |
+
+Each method returns the result as a dict. Refusals and errors raise `upoch.UpochError` (with a `code`).
+
+A rollback restores the agent's state. It cannot reverse transactions that already happened on-chain; those are
+listed so the agent can account for them.
+
+## How it works
+
+`Guard` starts the `upoch mcp` command from `@upoch/guard` and talks to it over stdio. That process holds the keys:
+it encrypts each checkpoint on your machine, stores it on IPFS, commits its fingerprint to the Upoch contract, and
+reads it back to verify it. Only someone with your checkpoint key can read it, and anyone can check that it has
+not been changed. Every checkpoint opens in the [Time-Travel Debugger](https://upoch.tech/docs/debugger).
+
+Settings live in `UPOCH_HOME` (default `~/.upoch`); `Guard(home=...)` picks another one. If `upoch` is not on your
+`PATH`, set `UPOCH_COMMAND` (for example `node /path/to/cli.js mcp`) or pass `Guard(command=[...])`.
+
+## Safety
+
+- Each checkpoint is one transaction from the agent's executor key. That key can only submit checkpoints. There is a
+  daily limit (100 by default, `maxCheckpointsPerDay` in `~/.upoch/config.json`).
+- State that looks like private keys, seed phrases or API tokens is refused, because checkpoints are permanent.
+- Keys stay on your machine, in `~/.upoch/secrets.json`, and never pass through Python. Back that file up.
+- The Upoch contracts have not been audited.
+
+## License
+
+MIT

upoch-0.1.0/README.md

@@ -0,0 +1,119 @@
+# upoch: Upoch Guard for Python agents
+
+Give your Python agent a memory and an undo button.
+
+Upoch Guard saves verifiable checkpoints of an agent's work on Robinhood Chain. If the agent crashes, gets a bad
+prompt or makes a bad trade, it restores the last good state, checked against the chain, or rolls back to the
+checkpoint before the mistake and keeps going. It also knows which of its actions already happened.
+
+Website and debugger: https://upoch.tech. Contract (Robinhood Chain, 4663): `0x6179d9123c3c1f9e82f948101a4350cb55aa8c27`
+
+## Setup
+
+Once, in your own terminal. You need Node.js 24 or later, because the `upoch` command holds the keys and does the
+signing:
+
+```sh
+npm install -g @upoch/guard
+upoch setup
+```
+
+`upoch setup` creates your keys in `~/.upoch`, waits while you send the owner address a little ETH on Robinhood
+Chain (0.001 ETH is plenty), and registers your agent. Then:
+
+```sh
+pip install upoch                 # or: pip install "upoch[langchain]"
+```
+
+## LangChain and LangGraph
+
+One line: every consequential tool call (swaps, transfers, bridges, staking, lending, trades, mints, launches and
+approvals) is checkpointed before and after it runs. The pre-tool checkpoint is committed before the tool runs,
+with `invoke` and `ainvoke`.
+
+```python
+from upoch.langchain import UpochCallbackHandler, upoch_tools
+
+upoch = UpochCallbackHandler()
+
+# Automatic checkpoints around consequential tool calls:
+agent.invoke(inputs, config={"callbacks": [upoch]})
+
+# Optional: let the model restore, checkpoint and roll back itself.
+tools = [*your_tools, *upoch_tools(handler=upoch)]
+```
+
+| Tool | |
+|---|---|
+| `upoch_restore` | Latest checkpoint, verified against the chain, and which actions completed |
+| `upoch_checkpoint` | Save the current state |
+| `upoch_rollback` | Go back to an earlier checkpoint and continue. By default, the one right before the last swap or transfer |
+| `upoch_history` | Recent checkpoints |
+| `upoch_complete` | Mark the task finished |
+
+Options:
+
+```python
+UpochCallbackHandler(
+    watch=["swap_tokens", "send_eth"],   # exact tool names, or a compiled regex (default: value-moving names)
+    state=lambda: my_agent_state,        # what each checkpoint holds (default: the log of watched tool calls)
+    strict=True,                         # stop the tool when its pre-tool checkpoint fails (default False)
+)
+```
+
+## Any Python agent
+
+```python
+from upoch import Guard
+
+with Guard() as guard:
+    restored = guard.restore()            # where the last run stopped, verified against the chain
+    state = restored.get("state") or {"step": 0}
+
+    guard.record_action("swap-1", "swap", "planned", input={"sell": "WETH", "qty": 0.1})
+    guard.checkpoint(state, note="before swap", kind="before_action")
+    tx = do_the_swap()
+    guard.record_action("swap-1", "swap", "confirmed", transaction_hash=tx)
+    guard.checkpoint({**state, "step": 1}, note="after swap", kind="after_action")
+
+    # Something went wrong? Go back to the checkpoint before it:
+    guard.rollback(0, reason="the swap was the wrong size")
+```
+
+| Method | What it does | On-chain |
+|---|---|---|
+| `restore(sequence=None)` | Latest (or a given) checkpoint after verifying it: state, note, completed and unresolved actions | read |
+| `checkpoint(state, note, kind)` | Saves the state (`progress`, `before_action`, `after_action`, `manual`) | 1 transaction |
+| `record_action(...)` | Records an external action (planned, submitted, confirmed, failed) with its transaction hash | no (goes into the next checkpoint) |
+| `rollback(sequence, reason)` | Goes back to an earlier checkpoint and continues from it; lists actions since then that were not undone on-chain | 1 transaction |
+| `complete(state, note)` | Saves a final checkpoint and marks the run finished | 1 transaction |
+| `history(limit)` | Recent checkpoints | read |
+| `verify(sequence)` | Verifies one checkpoint without restoring it | read |
+| `status()` | Workflow, executor funds and today's usage | read |
+
+Each method returns the result as a dict. Refusals and errors raise `upoch.UpochError` (with a `code`).
+
+A rollback restores the agent's state. It cannot reverse transactions that already happened on-chain; those are
+listed so the agent can account for them.
+
+## How it works
+
+`Guard` starts the `upoch mcp` command from `@upoch/guard` and talks to it over stdio. That process holds the keys:
+it encrypts each checkpoint on your machine, stores it on IPFS, commits its fingerprint to the Upoch contract, and
+reads it back to verify it. Only someone with your checkpoint key can read it, and anyone can check that it has
+not been changed. Every checkpoint opens in the [Time-Travel Debugger](https://upoch.tech/docs/debugger).
+
+Settings live in `UPOCH_HOME` (default `~/.upoch`); `Guard(home=...)` picks another one. If `upoch` is not on your
+`PATH`, set `UPOCH_COMMAND` (for example `node /path/to/cli.js mcp`) or pass `Guard(command=[...])`.
+
+## Safety
+
+- Each checkpoint is one transaction from the agent's executor key. That key can only submit checkpoints. There is a
+  daily limit (100 by default, `maxCheckpointsPerDay` in `~/.upoch/config.json`).
+- State that looks like private keys, seed phrases or API tokens is refused, because checkpoints are permanent.
+- Keys stay on your machine, in `~/.upoch/secrets.json`, and never pass through Python. Back that file up.
+- The Upoch contracts have not been audited.
+
+## License
+
+MIT

upoch-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "upoch"
+version = "0.1.0"
+description = "Upoch Guard for Python agents: verifiable checkpoints, recovery and rollback on Robinhood Chain, with a one-line LangChain and LangGraph callback."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+keywords = ["upoch", "ai-agents", "checkpoint", "recovery", "rollback", "robinhood-chain", "langchain", "langgraph"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=1.0,<2"]
+
+[project.urls]
+Homepage = "https://upoch.tech"
+Documentation = "https://upoch.tech/docs"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["upoch"]
+
+[tool.setuptools.package-data]
+upoch = ["py.typed"]

upoch-0.1.0/setup.cfg

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

upoch-0.1.0/tests/test_upoch.py

@@ -0,0 +1,195 @@
+"""upoch against a real local chain: anvil with the Upoch contract and a registered setup (guard/test/local-chain-cli.ts),
+the upoch mcp server from guard/dist, and LangChain's own callback manager for the LangChain handler.
+
+Run: python -m unittest discover -s python/tests (needs anvil, the compiled contract, guard built, langchain-core).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from upoch import Guard, UpochError  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[2]
+CLI = ROOT / "guard" / "dist" / "cli.js"
+ANVIL = Path.home() / ".foundry" / "bin" / ("anvil.exe" if os.name == "nt" else "anvil")
+HAVE_CHAIN = ANVIL.exists() and (ROOT / "artifacts" / "contracts" / "Epoch.sol" / "Epoch.json").exists() and CLI.exists()
+TX = "0x" + "be" * 32
+
+try:
+    from langchain_core.tools import tool
+
+    from upoch.langchain import UpochCallbackHandler, upoch_tools
+
+    HAVE_LANGCHAIN = True
+except ImportError:
+    HAVE_LANGCHAIN = False
+
+
+class Chain:
+    def __init__(self, name: str) -> None:
+        self.proc = subprocess.Popen(["node", str(ROOT / "guard" / "test" / "local-chain-cli.ts"), name], cwd=ROOT / "guard", stdin=subprocess.PIPE, stdout=subprocess.PIPE)
+        assert self.proc.stdout is not None
+        line = self.proc.stdout.readline()
+        if not line:
+            raise RuntimeError("local chain setup failed")
+        self.home = json.loads(line)["home"]
+
+    def guard(self) -> Guard:
+        return Guard(self.home, command=["node", str(CLI), "mcp"])
+
+    def stop(self) -> None:
+        assert self.proc.stdin is not None
+        self.proc.stdin.close()
+        self.proc.wait(timeout=30)
+        if self.proc.stdout:
+            self.proc.stdout.close()
+
+
+class NotInstalledTests(unittest.TestCase):
+    def test_missing_command_says_how_to_install(self) -> None:
+        g = Guard(command=["upoch-command-that-does-not-exist", "mcp"])
+        with self.assertRaises(UpochError) as e:
+            g.status()
+        self.assertEqual(e.exception.code, "NOT_INSTALLED")
+        self.assertIn("npm install -g @upoch/guard", str(e.exception))
+
+
+@unittest.skipUnless(HAVE_CHAIN, "needs anvil (Foundry), the compiled Epoch artifact and guard/dist")
+class GuardTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.chain = Chain("Python agent")
+        cls.g = cls.chain.guard()
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.g.close()
+        cls.chain.stop()
+
+    def test_lifecycle(self) -> None:
+        s = self.g.status()
+        self.assertEqual(s["chainId"], 31337)
+        self.assertEqual(s["workflow"]["checkpoints"], "0")
+        self.assertRegex(self.g.server_version or "", r"^0.1.")
+
+        self.g.record_action("swap-1", "swap", "planned", input={"sell": "WETH", "qty": 0.1})
+        c0 = self.g.checkpoint({"step": 1, "plan": "sell 0.1 WETH"}, note="before swap", kind="before_action")
+        self.assertEqual(c0["status"], "VERIFIED_RECOVERY_POINT", c0)
+        self.g.record_action("swap-1", "swap", "confirmed", transaction_hash=TX, result={"got": "301.2 USDC"})
+        c1 = self.g.checkpoint({"step": 2, "usdc": 301.2}, note="after swap", kind="after_action")
+        self.assertEqual(c1["sequence"], "1")
+
+        r = self.g.restore()
+        self.assertEqual(r["status"], "RESTORED")
+        self.assertEqual(r["state"], {"step": 2, "usdc": 301.2})
+        self.assertEqual(self.g.restore(sequence=0)["state"]["step"], 1)
+        self.assertTrue(self.g.verify(1)["ok"])
+        self.assertEqual(self.g.history(limit=5)["total"], "2")
+
+        # A restart of the server (a crash, a new process) recovers the same state from the chain.
+        self.g.close()
+        self.assertEqual(self.chain.guard().restore()["state"]["step"], 2)
+
+        rb = self.g.rollback(0, "the swap was the wrong size")
+        self.assertEqual(rb["status"], "ROLLED_BACK", rb)
+        self.assertEqual(rb["state"]["step"], 1)
+        self.assertEqual([a["operationId"] for a in rb["actionsSince"]], ["swap-1"], "the swap is listed as not undone")
+        self.assertEqual(self.g.restore()["state"]["step"], 1)
+
+        with self.assertRaises(UpochError) as e:
+            self.g.checkpoint({"privateKey": "0x" + "11" * 32})
+        self.assertIn("Refused", str(e.exception))
+
+        done = self.g.complete({"step": 3}, note="finished")
+        self.assertEqual(done["status"], "VERIFIED_RECOVERY_POINT", done)
+
+
+@unittest.skipUnless(HAVE_CHAIN and HAVE_LANGCHAIN, "needs the local chain and langchain-core")
+class LangChainTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.chain = Chain("LangChain Python agent")
+        cls.errors: list[Exception] = []
+        cls.handler = UpochCallbackHandler(cls.chain.guard(), on_error=cls.errors.append)
+        cls.seen: list[int | None] = []
+        handler, seen = cls.handler, cls.seen
+
+        @tool
+        def swap_tokens(qty: float) -> str:
+            """Swap tokens."""
+            seen.append(handler.last_checkpoint)
+            return f"swapped {qty} WETH, tx {TX}"
+
+        @tool
+        def get_price() -> str:
+            """Read a price."""
+            return "3010.5"
+
+        @tool
+        def transfer(to: str) -> str:
+            """Transfer."""
+            raise ValueError("insufficient balance")
+
+        cls.swap, cls.price, cls.transfer = swap_tokens, get_price, transfer
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.handler.guard.close()
+        cls.chain.stop()
+
+    def test_1_checkpoints_around_a_swap(self) -> None:
+        self.price.invoke({}, config={"callbacks": [self.handler]})
+        self.assertIsNone(self.handler.last_checkpoint, "read-only tools are not checkpointed")
+        out = self.swap.invoke({"qty": 0.1}, config={"callbacks": [self.handler]})
+        self.assertIn("swapped 0.1", out)
+        self.assertEqual(self.seen, [0], "checkpoint #0 was committed before the swap body ran")
+        self.assertEqual(self.handler.last_checkpoint, 1)
+        e = self.handler.log[-1]
+        self.assertEqual((e["status"], e["transactionHash"], e["checkpointBefore"]), ("completed", TX, 0))
+        self.assertEqual(self.errors, [])
+
+    def test_2_async_waits_for_the_pre_tool_checkpoint(self) -> None:
+        import asyncio
+
+        asyncio.run(self.swap.ainvoke({"qty": 0.2}, config={"callbacks": [self.handler]}))
+        self.assertEqual(self.seen[-1], 2)
+        self.assertEqual(self.handler.last_checkpoint, 3)
+
+    def test_3_failing_tool_is_recorded_as_failed(self) -> None:
+        with self.assertRaises(ValueError):
+            self.transfer.invoke({"to": "0x1"}, config={"callbacks": [self.handler]})
+        self.assertEqual(self.handler.log[-1]["status"], "failed")
+        self.assertEqual(self.handler.last_checkpoint, 5)
+
+    def test_4_model_tools_restore_and_roll_back(self) -> None:
+        tools = {t.name: t for t in upoch_tools(handler=self.handler)}
+        self.assertEqual(sorted(tools), ["upoch_checkpoint", "upoch_complete", "upoch_history", "upoch_restore", "upoch_rollback"])
+        restored = json.loads(tools["upoch_restore"].invoke({}))
+        self.assertEqual(len(restored["state"]["tools"]), 3)
+        self.assertEqual(json.loads(tools["upoch_history"].invoke({"limit": 10}))["total"], "6")
+        rb = json.loads(tools["upoch_rollback"].invoke({"reason": "the transfer failed; go back"}))
+        self.assertEqual((rb["status"], rb["rolledBackTo"]), ("ROLLED_BACK", "4"), rb)
+        saved = json.loads(tools["upoch_checkpoint"].invoke({"state": {"plan": "retry with less"}, "note": "after rollback"}))
+        self.assertEqual(saved["status"], "VERIFIED_RECOVERY_POINT")
+        self.assertTrue(tools["upoch_checkpoint"].invoke({"state": {"privateKey": "0x" + "11" * 32}}).startswith("Error:"))
+
+    def test_5_strict_stops_the_tool_when_its_checkpoint_fails(self) -> None:
+        errors: list[Exception] = []
+        strict = UpochCallbackHandler(self.handler.guard, state=lambda: {"privateKey": "0x" + "11" * 32}, strict=True, on_error=errors.append)
+        before = len(self.seen)
+        with self.assertRaises(UpochError):
+            self.swap.invoke({"qty": 9}, config={"callbacks": [strict]})
+        self.assertEqual(len(self.seen), before, "the swap did not run")
+        self.assertEqual(len(errors), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

upoch-0.1.0/upoch/__init__.py

@@ -0,0 +1,16 @@
+"""Upoch Guard for Python agents: verifiable checkpoints, recovery and rollback on Robinhood Chain.
+
+    from upoch import Guard
+
+    guard = Guard()
+    restored = guard.restore()
+    guard.checkpoint({"step": 3, "positions": [...]}, note="rebalanced")
+
+LangChain and LangGraph: ``from upoch.langchain import UpochCallbackHandler`` (``pip install "upoch[langchain]"``).
+"""
+
+__version__ = "0.1.0"
+
+from .guard import ActionStatus, CheckpointKind, Guard, UpochError
+
+__all__ = ["Guard", "UpochError", "CheckpointKind", "ActionStatus", "__version__"]

upoch-0.1.0/upoch/guard.py

@@ -0,0 +1,235 @@
+"""Guard: Upoch Guard from Python, through the ``upoch mcp`` server of @upoch/guard.
+
+The server holds the keys and does the signing, encryption and verification; this module only starts it and
+calls its tools over stdio (newline-delimited JSON-RPC, the MCP stdio transport). Standard library only.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import threading
+from collections import deque
+from typing import Any, Literal
+
+__all__ = ["Guard", "UpochError", "CheckpointKind", "ActionStatus"]
+
+CheckpointKind = Literal["progress", "before_action", "after_action", "manual"]
+ActionStatus = Literal["planned", "submitted", "confirmed", "failed"]
+
+PROTOCOL_VERSION = "2025-06-18"
+INSTALL_HINT = "Install it with: npm install -g @upoch/guard, then run: upoch setup (in your own terminal)."
+
+
+class UpochError(Exception):
+    """A tool or server error. ``code`` is the Guard error code (e.g. NOT_SET_UP, REFUSED) when there is one."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+
+
+def _default_command() -> list[str]:
+    env = os.environ.get("UPOCH_COMMAND")
+    if env:
+        return shlex.split(env, posix=os.name != "nt")
+    found = shutil.which("upoch")
+    if not found:
+        raise UpochError("NOT_INSTALLED", f"The upoch command was not found. {INSTALL_HINT}")
+    return [found, "mcp"]
+
+
+class _StdioClient:
+    """A minimal MCP client over a child process's stdin/stdout. Thread-safe."""
+
+    def __init__(self, command: list[str], env: dict[str, str], timeout: float) -> None:
+        self.timeout = timeout
+        try:
+            self.proc = subprocess.Popen(command, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=env)
+        except OSError as e:
+            raise UpochError("NOT_INSTALLED", f"Could not start {command[0]}: {e}. {INSTALL_HINT}") from e
+        self._lock = threading.Lock()
+        self._next_id = 0
+        self._pending: dict[int, dict[str, Any]] = {}
+        self._cond = threading.Condition()
+        self._closed: str | None = None
+        self._stderr: deque[str] = deque(maxlen=20)
+        threading.Thread(target=self._read_stdout, daemon=True).start()
+        threading.Thread(target=self._read_stderr, daemon=True).start()
+        init = self.request("initialize", {"protocolVersion": PROTOCOL_VERSION, "capabilities": {}, "clientInfo": {"name": "upoch-python", "version": _version()}})
+        self.server_info: dict[str, Any] = init.get("serverInfo", {})
+        self.instructions: str = init.get("instructions", "")
+        self._send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+
+    def _send(self, msg: dict[str, Any]) -> None:
+        data = (json.dumps(msg, separators=(",", ":")) + "\n").encode("utf-8")
+        with self._lock:
+            if self._closed:
+                raise UpochError("SERVER_EXITED", self._closed)
+            assert self.proc.stdin is not None
+            self.proc.stdin.write(data)
+            self.proc.stdin.flush()
+
+    def _read_stdout(self) -> None:
+        assert self.proc.stdout is not None
+        for raw in self.proc.stdout:
+            try:
+                msg = json.loads(raw)
+            except ValueError:
+                continue
+            if "id" in msg and "method" in msg:
+                # A request from the server (e.g. ping): answer ping, decline anything else.
+                reply = {"jsonrpc": "2.0", "id": msg["id"], "result": {}} if msg["method"] == "ping" else {"jsonrpc": "2.0", "id": msg["id"], "error": {"code": -32601, "message": "Method not found"}}
+                try:
+                    self._send(reply)
+                except UpochError:
+                    pass
+            elif "id" in msg:
+                with self._cond:
+                    self._pending[msg["id"]] = msg
+                    self._cond.notify_all()
+        with self._cond:
+            tail = " | ".join(self._stderr) or f"exit code {self.proc.poll()}"
+            self._closed = f"The upoch server stopped: {tail}"
+            self._cond.notify_all()
+
+    def _read_stderr(self) -> None:
+        assert self.proc.stderr is not None
+        for raw in self.proc.stderr:
+            line = raw.decode("utf-8", "replace").strip()
+            if line:
+                self._stderr.append(line)
+
+    def request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        with self._cond:
+            self._next_id += 1
+            rid = self._next_id
+        self._send({"jsonrpc": "2.0", "id": rid, "method": method, "params": params})
+        with self._cond:
+            if not self._cond.wait_for(lambda: rid in self._pending or self._closed is not None, timeout=self.timeout):
+                raise UpochError("TIMEOUT", f"No answer to {method} after {self.timeout:.0f}s.")
+            if rid not in self._pending:
+                raise UpochError("SERVER_EXITED", self._closed or "The upoch server stopped.")
+            msg = self._pending.pop(rid)
+        if "error" in msg:
+            raise UpochError("PROTOCOL", str(msg["error"].get("message", msg["error"])))
+        return msg.get("result", {})
+
+    def close(self) -> None:
+        with self._lock:
+            self._closed = self._closed or "closed"
+            try:
+                if self.proc.stdin:
+                    self.proc.stdin.close()
+            except OSError:
+                pass
+        try:
+            self.proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self.proc.kill()
+            self.proc.wait()
+        for pipe in (self.proc.stdout, self.proc.stderr):
+            if pipe:
+                pipe.close()
+
+
+def _version() -> str:
+    from . import __version__
+
+    return __version__
+
+
+class Guard:
+    """Verifiable checkpoints, recovery and rollback for a Python agent, on Robinhood Chain.
+
+    Keys and settings come from ``upoch setup`` (in ``home``, default ``UPOCH_HOME`` or ``~/.upoch``). The
+    ``upoch`` command (``npm install -g @upoch/guard``) is started on first use and stopped by :meth:`close`.
+
+    Each method returns the server's JSON result as a dict. A refused or failed call raises :class:`UpochError`;
+    :meth:`checkpoint` instead returns a result whose ``status`` says what happened (``VERIFIED_RECOVERY_POINT``
+    when the checkpoint was committed and verified).
+    """
+
+    def __init__(self, home: str | os.PathLike[str] | None = None, *, command: list[str] | None = None, env: dict[str, str] | None = None, timeout: float = 300.0) -> None:
+        self._command = command
+        self._env = {**os.environ, **(env or {})}
+        if home is not None:
+            self._env["UPOCH_HOME"] = os.fspath(home)
+        self._timeout = timeout
+        self._client: _StdioClient | None = None
+        self._start_lock = threading.Lock()
+
+    def _call(self, tool: str, args: dict[str, Any]) -> dict[str, Any]:
+        with self._start_lock:
+            if self._client is None:
+                self._client = _StdioClient(self._command or _default_command(), self._env, self._timeout)
+        r = self._client.request("tools/call", {"name": tool, "arguments": {k: v for k, v in args.items() if v is not None}})
+        text = "".join(c.get("text", "") for c in r.get("content", []) if c.get("type") == "text")
+        if r.get("isError"):
+            code, sep, message = text.partition(": ")
+            if sep and code.replace("_", "").isupper():
+                raise UpochError(code, message)
+            raise UpochError("ERROR", text)
+        return json.loads(text) if text else {}
+
+    def status(self) -> dict[str, Any]:
+        """The workflow (checkpoints, head), executor funds, the open run and today's usage."""
+        return self._call("upoch_status", {})
+
+    def checkpoint(self, state: Any, note: str | None = None, kind: CheckpointKind = "progress") -> dict[str, Any]:
+        """Saves ``state`` (JSON) as an encrypted checkpoint, committed on-chain and verified. One transaction."""
+        return self._call("upoch_checkpoint", {"state": state, "note": note, "kind": kind})
+
+    def record_action(self, operation_id: str, type: str, status: ActionStatus, *, transaction_hash: str | None = None, input: Any = None, result: Any = None) -> dict[str, Any]:
+        """Records an external action (planned, then confirmed or failed); it goes into the next checkpoint."""
+        return self._call("upoch_record_action", {"operationId": operation_id, "type": type, "status": status, "transactionHash": transaction_hash, "input": input, "result": result})
+
+    def restore(self, sequence: int | None = None) -> dict[str, Any]:
+        """The latest checkpoint (or ``sequence``), verified: its state, note and which actions completed."""
+        return self._call("upoch_restore", {"sequence": sequence})
+
+    def rollback(self, sequence: int, reason: str) -> dict[str, Any]:
+        """Goes back to checkpoint ``sequence`` and continues from it. One transaction.
+
+        Restores state only: on-chain transactions since then are not undone; they are listed in ``actionsSince``.
+        """
+        return self._call("upoch_rollback", {"sequence": sequence, "reason": reason})
+
+    def history(self, limit: int | None = None) -> dict[str, Any]:
+        """The most recent checkpoints, newest first."""
+        return self._call("upoch_history", {"limit": limit})
+
+    def verify(self, sequence: int) -> dict[str, Any]:
+        """Verifies one checkpoint without restoring it."""
+        return self._call("upoch_verify", {"sequence": sequence})
+
+    def complete(self, state: Any, note: str | None = None) -> dict[str, Any]:
+        """Saves a final checkpoint marking the task finished. One transaction."""
+        return self._call("upoch_complete", {"state": state, "note": note})
+
+    @property
+    def server_version(self) -> str | None:
+        return self._client.server_info.get("version") if self._client else None
+
+    def close(self) -> None:
+        """Stops the upoch server (it starts again on the next call)."""
+        with self._start_lock:
+            if self._client is not None:
+                self._client.close()
+                self._client = None
+
+    def __enter__(self) -> Guard:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass

upoch-0.1.0/upoch/langchain.py

@@ -0,0 +1,216 @@
+"""Upoch Guard for LangChain and LangGraph (Python). Two ways in, usable together:
+
+    UpochCallbackHandler()  pass it in ``callbacks``: every consequential tool call (swap, transfer...) is
+                            checkpointed on Robinhood Chain before and after it runs, with no code changes
+    upoch_tools()           tools the model can call itself: restore, checkpoint, rollback, history, complete
+
+Needs ``pip install "upoch[langchain]"`` and the one-time ``upoch setup`` in your terminal.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+from collections.abc import Callable, Iterable
+from datetime import datetime, timezone
+from typing import Any
+from uuid import UUID
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+    from langchain_core.tools import BaseTool, StructuredTool
+    from pydantic import BaseModel, Field
+except ImportError as e:  # pragma: no cover
+    raise ImportError('upoch.langchain needs LangChain: pip install "upoch[langchain]"') from e
+
+from .guard import Guard, UpochError
+
+__all__ = ["DEFAULT_WATCH", "UpochCallbackHandler", "upoch_tools"]
+
+#: Tool names that move value or change something outside the agent.
+DEFAULT_WATCH = re.compile(r"(swap|transfer|send|bridge|deploy|stake|unstake|lend|borrow|repay|withdraw|deposit|buy|sell|trade|mint|launch|approve)", re.I)
+_TX = re.compile(r"0x[0-9a-fA-F]{64}")
+_OK = ("VERIFIED_RECOVERY_POINT", "COMMITTED")
+
+
+def _text(v: Any) -> str:
+    v = getattr(v, "content", v)  # ToolMessage
+    if not isinstance(v, str):
+        try:
+            v = json.dumps(v, default=str)
+        except (TypeError, ValueError):
+            v = str(v)
+    return v[:500]
+
+
+class UpochCallbackHandler(BaseCallbackHandler):
+    """Checkpoints around consequential tool calls.
+
+    The pre-tool checkpoint is committed before the tool runs (LangChain waits for callback handlers, also
+    under ``ainvoke``). Failures are logged and the tool runs anyway, unless ``strict=True``.
+
+    Args:
+        guard: a :class:`~upoch.Guard` to use; default: one for ``UPOCH_HOME`` (``~/.upoch``).
+        watch: which tool names to checkpoint around: a regex or a list of exact names.
+        state: what each automatic checkpoint holds (default: the log of watched tool calls).
+        strict: raise, and so stop the tool, when its pre-tool checkpoint fails.
+        on_error: called with each error (default: a warning on stderr).
+    """
+
+    def __init__(self, guard: Guard | None = None, *, watch: re.Pattern[str] | Iterable[str] | None = None, state: Callable[[], Any] | None = None, strict: bool = False, on_error: Callable[[Exception], None] | None = None) -> None:
+        super().__init__()
+        self.guard = guard or Guard()
+        if watch is None or isinstance(watch, re.Pattern):
+            pattern = watch or DEFAULT_WATCH
+            self._watch: Callable[[str], bool] = lambda n: bool(pattern.search(n))
+        else:
+            names = set(watch)
+            self._watch = lambda n: n in names
+        self._state = state
+        self.raise_error = strict
+        self._on_error = on_error or (lambda e: print(f"[upoch] {e}", file=__import__("sys").stderr))
+        self.log: list[dict[str, Any]] = []
+        self.last_checkpoint: int | None = None
+        self._runs: dict[UUID, dict[str, Any]] = {}
+        self._serial = threading.Lock()
+
+    def _save(self, note: str, kind: str) -> int | None:
+        state = self._state() if self._state else {"tools": self.log[-25:]}
+        r = self.guard.checkpoint(state, note=note, kind=kind)  # type: ignore[arg-type]
+        if r.get("status") not in _OK:
+            raise UpochError(str(r.get("status")), (r.get("error") or {}).get("message", "checkpoint failed"))
+        if r.get("sequence") is not None:
+            self.last_checkpoint = int(r["sequence"])
+        return self.last_checkpoint
+
+    def _guarded(self, f: Callable[[], None], rethrow: bool) -> None:
+        with self._serial:
+            try:
+                f()
+            except Exception as e:
+                self._on_error(e)
+                if rethrow:
+                    raise
+
+    def on_tool_start(self, serialized: dict[str, Any] | None, input_str: str, *, run_id: UUID, **kwargs: Any) -> None:
+        name = (serialized or {}).get("name") or kwargs.get("name") or "tool"
+        if not self._watch(name):
+            return
+        op = re.sub(r"[^A-Za-z0-9._:-]", "_", f"{name}-{run_id}")[:128]
+        entry: dict[str, Any] = {"operationId": op, "tool": name, "status": "started", "input": _text(input_str), "at": datetime.now(timezone.utc).isoformat()}
+        self._runs[run_id] = entry
+
+        def before() -> None:
+            self.guard.record_action(op, name, "planned")
+            self.log.append(entry)
+            entry["checkpointBefore"] = self._save(f"Before {name}", "before_action")
+
+        self._guarded(before, self.raise_error)
+
+    def _finish(self, run_id: UUID, ok: bool, output: Any) -> None:
+        entry = self._runs.pop(run_id, None)
+        if entry is None:
+            return
+        out = _text(output)
+        m = _TX.search(out)
+        tx = m.group(0) if m else None
+
+        def after() -> None:
+            self.guard.record_action(entry["operationId"], entry["tool"], "confirmed" if ok else "failed", transaction_hash=tx, result={"success": ok, "output": out[:300]})
+            entry.update({"status": "completed" if ok else "failed", "output": out[:300]})
+            if tx:
+                entry["transactionHash"] = tx
+            if entry not in self.log:
+                self.log.append(entry)
+            self._save(f"{'After' if ok else 'Failed'}: {entry['tool']}" + (f" ({tx[:10]}...)" if tx else ""), "after_action")
+
+        # After the tool ran, a failed checkpoint must never turn its result into an error.
+        try:
+            self._guarded(after, False)
+        except Exception:
+            pass
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        self._finish(run_id, True, output)
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._finish(run_id, False, str(error))
+
+    @property
+    def last_pre_tool_checkpoint(self) -> int | None:
+        """The checkpoint taken right before the most recent watched tool call."""
+        for e in reversed(self.log):
+            if e.get("checkpointBefore") is not None:
+                return int(e["checkpointBefore"])
+        return None
+
+
+def _safe(f: Callable[[], Any]) -> str:
+    try:
+        return json.dumps(f(), indent=2)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+class _Empty(BaseModel):
+    pass
+
+
+class _Checkpoint(BaseModel):
+    state: dict[str, Any] = Field(description="Everything needed to continue from here, as JSON.")
+    note: str | None = Field(default=None, max_length=500)
+
+
+class _Rollback(BaseModel):
+    sequence: int | None = Field(default=None, ge=0, description="The checkpoint to go back to (default: the one right before the last swap/transfer).")
+    reason: str = Field(min_length=1, max_length=300)
+
+
+class _History(BaseModel):
+    limit: int | None = Field(default=None, ge=1, le=50)
+
+
+def upoch_tools(guard: Guard | None = None, handler: UpochCallbackHandler | None = None) -> list[BaseTool]:
+    """Upoch tools for a LangChain or LangGraph agent. Pass the handler too, so rollback can default to "before
+    the last tool call"."""
+    g = guard or (handler.guard if handler else Guard())
+
+    def rollback(reason: str, sequence: int | None = None) -> str:
+        target = sequence if sequence is not None else (handler.last_pre_tool_checkpoint if handler else None)
+        if target is None:
+            return "Error: give a checkpoint number (see upoch_history)."
+        return _safe(lambda: g.rollback(target, reason))
+
+    return [
+        StructuredTool.from_function(
+            func=lambda: _safe(g.restore),
+            name="upoch_restore",
+            description="Restore the agent's latest Upoch checkpoint, verified against Robinhood Chain: its state, note, and which recorded actions completed. Call at the start of a task; do not repeat completed actions.",
+            args_schema=_Empty,
+        ),
+        StructuredTool.from_function(
+            func=lambda state, note=None: _safe(lambda: g.checkpoint(state, note=note)),
+            name="upoch_checkpoint",
+            description="Save the current state as a verifiable checkpoint on Robinhood Chain (one transaction). Use after meaningful progress. Never include keys, seed phrases or tokens.",
+            args_schema=_Checkpoint,
+        ),
+        StructuredTool.from_function(
+            func=rollback,
+            name="upoch_rollback",
+            description="Roll back to an earlier checkpoint and continue from it, e.g. after a bad trade. Default: the checkpoint right before the last swap/transfer tool call. Restores state only; on-chain transactions since then are not undone and are listed.",
+            args_schema=_Rollback,
+        ),
+        StructuredTool.from_function(
+            func=lambda limit=None: _safe(lambda: g.history(limit)),
+            name="upoch_history",
+            description="List the most recent Upoch checkpoints, newest first.",
+            args_schema=_History,
+        ),
+        StructuredTool.from_function(
+            func=lambda state, note=None: _safe(lambda: g.complete(state, note=note)),
+            name="upoch_complete",
+            description="Save a final checkpoint marking the task finished (one transaction).",
+            args_schema=_Checkpoint,
+        ),
+    ]

upoch-0.1.0/upoch.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: upoch
+Version: 0.1.0
+Summary: Upoch Guard for Python agents: verifiable checkpoints, recovery and rollback on Robinhood Chain, with a one-line LangChain and LangGraph callback.
+License-Expression: MIT
+Project-URL: Homepage, https://upoch.tech
+Project-URL: Documentation, https://upoch.tech/docs
+Keywords: upoch,ai-agents,checkpoint,recovery,rollback,robinhood-chain,langchain,langgraph
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=1.0; extra == "langchain"
+Dynamic: license-file
+
+# upoch: Upoch Guard for Python agents
+
+Give your Python agent a memory and an undo button.
+
+Upoch Guard saves verifiable checkpoints of an agent's work on Robinhood Chain. If the agent crashes, gets a bad
+prompt or makes a bad trade, it restores the last good state, checked against the chain, or rolls back to the
+checkpoint before the mistake and keeps going. It also knows which of its actions already happened.
+
+Website and debugger: https://upoch.tech. Contract (Robinhood Chain, 4663): `0x6179d9123c3c1f9e82f948101a4350cb55aa8c27`
+
+## Setup
+
+Once, in your own terminal. You need Node.js 24 or later, because the `upoch` command holds the keys and does the
+signing:
+
+```sh
+npm install -g @upoch/guard
+upoch setup
+```
+
+`upoch setup` creates your keys in `~/.upoch`, waits while you send the owner address a little ETH on Robinhood
+Chain (0.001 ETH is plenty), and registers your agent. Then:
+
+```sh
+pip install upoch                 # or: pip install "upoch[langchain]"
+```
+
+## LangChain and LangGraph
+
+One line: every consequential tool call (swaps, transfers, bridges, staking, lending, trades, mints, launches and
+approvals) is checkpointed before and after it runs. The pre-tool checkpoint is committed before the tool runs,
+with `invoke` and `ainvoke`.
+
+```python
+from upoch.langchain import UpochCallbackHandler, upoch_tools
+
+upoch = UpochCallbackHandler()
+
+# Automatic checkpoints around consequential tool calls:
+agent.invoke(inputs, config={"callbacks": [upoch]})
+
+# Optional: let the model restore, checkpoint and roll back itself.
+tools = [*your_tools, *upoch_tools(handler=upoch)]
+```
+
+| Tool | |
+|---|---|
+| `upoch_restore` | Latest checkpoint, verified against the chain, and which actions completed |
+| `upoch_checkpoint` | Save the current state |
+| `upoch_rollback` | Go back to an earlier checkpoint and continue. By default, the one right before the last swap or transfer |
+| `upoch_history` | Recent checkpoints |
+| `upoch_complete` | Mark the task finished |
+
+Options:
+
+```python
+UpochCallbackHandler(
+    watch=["swap_tokens", "send_eth"],   # exact tool names, or a compiled regex (default: value-moving names)
+    state=lambda: my_agent_state,        # what each checkpoint holds (default: the log of watched tool calls)
+    strict=True,                         # stop the tool when its pre-tool checkpoint fails (default False)
+)
+```
+
+## Any Python agent
+
+```python
+from upoch import Guard
+
+with Guard() as guard:
+    restored = guard.restore()            # where the last run stopped, verified against the chain
+    state = restored.get("state") or {"step": 0}
+
+    guard.record_action("swap-1", "swap", "planned", input={"sell": "WETH", "qty": 0.1})
+    guard.checkpoint(state, note="before swap", kind="before_action")
+    tx = do_the_swap()
+    guard.record_action("swap-1", "swap", "confirmed", transaction_hash=tx)
+    guard.checkpoint({**state, "step": 1}, note="after swap", kind="after_action")
+
+    # Something went wrong? Go back to the checkpoint before it:
+    guard.rollback(0, reason="the swap was the wrong size")
+```
+
+| Method | What it does | On-chain |
+|---|---|---|
+| `restore(sequence=None)` | Latest (or a given) checkpoint after verifying it: state, note, completed and unresolved actions | read |
+| `checkpoint(state, note, kind)` | Saves the state (`progress`, `before_action`, `after_action`, `manual`) | 1 transaction |
+| `record_action(...)` | Records an external action (planned, submitted, confirmed, failed) with its transaction hash | no (goes into the next checkpoint) |
+| `rollback(sequence, reason)` | Goes back to an earlier checkpoint and continues from it; lists actions since then that were not undone on-chain | 1 transaction |
+| `complete(state, note)` | Saves a final checkpoint and marks the run finished | 1 transaction |
+| `history(limit)` | Recent checkpoints | read |
+| `verify(sequence)` | Verifies one checkpoint without restoring it | read |
+| `status()` | Workflow, executor funds and today's usage | read |
+
+Each method returns the result as a dict. Refusals and errors raise `upoch.UpochError` (with a `code`).
+
+A rollback restores the agent's state. It cannot reverse transactions that already happened on-chain; those are
+listed so the agent can account for them.
+
+## How it works
+
+`Guard` starts the `upoch mcp` command from `@upoch/guard` and talks to it over stdio. That process holds the keys:
+it encrypts each checkpoint on your machine, stores it on IPFS, commits its fingerprint to the Upoch contract, and
+reads it back to verify it. Only someone with your checkpoint key can read it, and anyone can check that it has
+not been changed. Every checkpoint opens in the [Time-Travel Debugger](https://upoch.tech/docs/debugger).
+
+Settings live in `UPOCH_HOME` (default `~/.upoch`); `Guard(home=...)` picks another one. If `upoch` is not on your
+`PATH`, set `UPOCH_COMMAND` (for example `node /path/to/cli.js mcp`) or pass `Guard(command=[...])`.
+
+## Safety
+
+- Each checkpoint is one transaction from the agent's executor key. That key can only submit checkpoints. There is a
+  daily limit (100 by default, `maxCheckpointsPerDay` in `~/.upoch/config.json`).
+- State that looks like private keys, seed phrases or API tokens is refused, because checkpoints are permanent.
+- Keys stay on your machine, in `~/.upoch/secrets.json`, and never pass through Python. Back that file up.
+- The Upoch contracts have not been audited.
+
+## License
+
+MIT

upoch-0.1.0/upoch.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_upoch.py
+upoch/__init__.py
+upoch/guard.py
+upoch/langchain.py
+upoch/py.typed
+upoch.egg-info/PKG-INFO
+upoch.egg-info/SOURCES.txt
+upoch.egg-info/dependency_links.txt
+upoch.egg-info/requires.txt
+upoch.egg-info/top_level.txt

upoch-0.1.0/upoch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

upoch-0.1.0/upoch.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[langchain]
+langchain-core<2,>=1.0

upoch-0.1.0/upoch.egg-info/top_level.txt

@@ -0,0 +1 @@
+upoch