runvouch 0.3.3__tar.gz

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.
runvouch-0.3.3/LICENSE ADDED
@@ -0,0 +1,9 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 RunVouch
4
+
5
+ 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:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ 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.
@@ -0,0 +1,41 @@
1
+ Metadata-Version: 2.4
2
+ Name: runvouch
3
+ Version: 0.3.3
4
+ Summary: The watchdog for unattended AI agents: dead man's switch, cost cap and outcome check for cron'd LLM scripts, Claude Code routines, OpenClaw and n8n.
5
+ Author-email: RunVouch <hello@runvouch.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://runvouch.com
8
+ Project-URL: Documentation, https://runvouch.com/docs
9
+ Project-URL: Source, https://github.com/runvouch/runvouch
10
+ Keywords: ai-agents,monitoring,watchdog,cron,llm,claude-code,openclaw,observability
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: System :: Monitoring
16
+ Requires-Python: >=3.8
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ # runvouch
22
+
23
+ The watchdog for unattended AI agents. Alerts within minutes when a scheduled agent is
24
+ MISSED, FAILED, reported success without evidence, stuck in a retry storm, over budget,
25
+ drifting or stalled. Telegram, Slack, e-mail or webhook. Free for 3 agents.
26
+
27
+ ```bash
28
+ pip install runvouch
29
+ export RUNVOUCH_KEY=rv_... # free key at https://runvouch.com/app
30
+
31
+ # wrap any cron job / agent command
32
+ rv run nightly-report --evidence-file out/report.html -- python report.py
33
+ ```
34
+
35
+ ```python
36
+ import os, runvouch
37
+ with runvouch.vouch("nightly-report", evidence=lambda: {"report": os.path.exists("out.html")}) as run:
38
+ run.tool("openai.chat", {"model": "gpt-5"}, cost=0.01)
39
+ ```
40
+
41
+ Zero dependencies, fails open (monitoring can never break your job). Docs: https://runvouch.com/docs
@@ -0,0 +1,21 @@
1
+ # runvouch
2
+
3
+ The watchdog for unattended AI agents. Alerts within minutes when a scheduled agent is
4
+ MISSED, FAILED, reported success without evidence, stuck in a retry storm, over budget,
5
+ drifting or stalled. Telegram, Slack, e-mail or webhook. Free for 3 agents.
6
+
7
+ ```bash
8
+ pip install runvouch
9
+ export RUNVOUCH_KEY=rv_... # free key at https://runvouch.com/app
10
+
11
+ # wrap any cron job / agent command
12
+ rv run nightly-report --evidence-file out/report.html -- python report.py
13
+ ```
14
+
15
+ ```python
16
+ import os, runvouch
17
+ with runvouch.vouch("nightly-report", evidence=lambda: {"report": os.path.exists("out.html")}) as run:
18
+ run.tool("openai.chat", {"model": "gpt-5"}, cost=0.01)
19
+ ```
20
+
21
+ Zero dependencies, fails open (monitoring can never break your job). Docs: https://runvouch.com/docs
@@ -0,0 +1,33 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "runvouch"
7
+ version = "0.3.3"
8
+ description = "The watchdog for unattended AI agents: dead man's switch, cost cap and outcome check for cron'd LLM scripts, Claude Code routines, OpenClaw and n8n."
9
+ readme = "README.md"
10
+ license = {text = "MIT"}
11
+ requires-python = ">=3.8"
12
+ authors = [{name = "RunVouch", email = "hello@runvouch.com"}]
13
+ keywords = ["ai-agents", "monitoring", "watchdog", "cron", "llm", "claude-code", "openclaw", "observability"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Programming Language :: Python :: 3",
19
+ "Topic :: System :: Monitoring",
20
+ ]
21
+ dependencies = []
22
+
23
+ [project.urls]
24
+ Homepage = "https://runvouch.com"
25
+ Documentation = "https://runvouch.com/docs"
26
+ Source = "https://github.com/runvouch/runvouch"
27
+
28
+ [project.scripts]
29
+ rv = "runvouch.cli:main"
30
+ runvouch = "runvouch.cli:main"
31
+
32
+ [tool.setuptools]
33
+ packages = ["runvouch"]
@@ -0,0 +1,37 @@
1
+ """runvouch.py — zero-dependency Python client. Fails open: report calls never raise.
2
+ import runvouch
3
+ with runvouch.vouch("nightly-report", evidence=lambda: {"report": os.path.exists("out.html")}) as run:
4
+ run.tool("openai.chat", {"model": "gpt-5", "h": "…"}, cost=0.01)
5
+ ...
6
+ """
7
+ import json, os, sys, urllib.request, contextlib
8
+ URL = os.getenv("RUNVOUCH_URL", "https://api.runvouch.com").rstrip("/"); KEY = os.getenv("RUNVOUCH_KEY", "")
9
+
10
+ def _api(path, body=None, method="POST"):
11
+ try:
12
+ req = urllib.request.Request(URL + path, json.dumps(body).encode() if body is not None else None,
13
+ {"X-API-Key": KEY, "Content-Type": "application/json", "User-Agent": "runvouch-python/0.3"}, method=method)
14
+ with urllib.request.urlopen(req, timeout=10) as r:
15
+ return json.loads(r.read() or b"{}")
16
+ except Exception as e:
17
+ sys.stderr.write(f"runvouch: {e} (running unmonitored)\n"); return None
18
+
19
+ def agent(name, **opts): return _api("/v1/agents", {"name": name, **opts})
20
+
21
+ class Run:
22
+ def __init__(self, agent, source="python", meta=None):
23
+ r = _api("/v1/runs/start", {"agent": agent, "source": source, "meta": meta or {}}); self.run_id = r and r.get("run_id")
24
+ def tool(self, tool, input=None, ok=True, cost=0, tokens=0):
25
+ return self.run_id and _api("/v1/runs/tool", {"run_id": self.run_id, "tool": tool, "input": input, "ok": ok, "cost": cost, "tokens": tokens})
26
+ def heartbeat(self): return self.run_id and _api(f"/v1/runs/heartbeat?run_id={self.run_id}")
27
+ def end(self, status="ok", cost=0, tokens=0, evidence=None, output_bytes=None, meta=None):
28
+ return self.run_id and _api("/v1/runs/end", {"run_id": self.run_id, "status": status, "cost": cost, "tokens": tokens, "evidence": evidence or {}, "output_bytes": output_bytes, "meta": meta or {}})
29
+
30
+ @contextlib.contextmanager
31
+ def vouch(agent, source="python", evidence=None, cost=None):
32
+ run = Run(agent, source)
33
+ try:
34
+ yield run
35
+ except Exception as e:
36
+ run.end(status="fail", meta={"error": str(e)[-500:]}); raise
37
+ run.end(status="ok", evidence=(evidence() if callable(evidence) else evidence) or {}, cost=(cost() if callable(cost) else cost) or 0)
@@ -0,0 +1,124 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ rv — RunVouch client CLI. Zero dependencies (stdlib only) so it runs in any cron/agent environment.
4
+
5
+ rv agent NAME [--cadence 24h] [--cap-run-cost 2] [--cap-day-cost 10] [--evidence]
6
+ rv run NAME [--evidence-file PATH] [--evidence-url URL] [--source cron] -- CMD ARGS...
7
+ rv start NAME -> prints run_id
8
+ rv tool RUN_ID TOOL [--input JSON] [--cost X] [--tokens N] [--fail]
9
+ rv end RUN_ID [--status ok|fail] [--cost X] [--tokens N] [--evidence JSON]
10
+ rv status -> table of agents
11
+ rv alerts [--ack ID]
12
+
13
+ Env: RUNVOUCH_URL (default http://localhost:8787), RUNVOUCH_KEY
14
+ """
15
+ import argparse, json, os, subprocess, sys, time, urllib.request
16
+
17
+ URL = os.getenv("RUNVOUCH_URL", "https://api.runvouch.com").rstrip("/")
18
+ KEY = os.getenv("RUNVOUCH_KEY", "")
19
+
20
+
21
+ def api(method, path, body=None, params=None, soft=False, _retries=3):
22
+ """soft=True: never raise/exit (used by `rv run` so monitoring can't break the job)."""
23
+ if not KEY:
24
+ if soft:
25
+ sys.stderr.write("runvouch: RUNVOUCH_KEY not set, running unmonitored\n"); return None
26
+ sys.exit("RUNVOUCH_KEY not set")
27
+ url = URL + path
28
+ if params:
29
+ url += "?" + "&".join(f"{k}={v}" for k, v in params.items())
30
+ data = json.dumps(body).encode() if body is not None else None
31
+ req = urllib.request.Request(url, data, {"X-API-Key": KEY, "Content-Type": "application/json", "User-Agent": "runvouch-cli/0.2"}, method=method)
32
+ try:
33
+ with urllib.request.urlopen(req, timeout=15) as r:
34
+ return json.loads(r.read() or b"{}")
35
+ except Exception as e:
36
+ msg = f"RunVouch {getattr(e, 'code', '')}: {getattr(e, 'reason', e)}"
37
+ if soft and _retries > 0 and getattr(e, 'code', 0) in (0, 502, 503, 504):
38
+ time.sleep(3); return api(method, path, body, params, soft, _retries - 1)
39
+ if soft:
40
+ sys.stderr.write("runvouch: " + msg + " (running unmonitored)\n"); return None
41
+ sys.exit(msg)
42
+
43
+
44
+ def dur(s):
45
+ units = {"s": 1, "m": 60, "h": 3600, "d": 86400}
46
+ return int(float(s[:-1]) * units[s[-1]]) if s and s[-1] in units else int(s)
47
+
48
+
49
+ def main(argv=None):
50
+ p = argparse.ArgumentParser(prog="rv")
51
+ sub = p.add_subparsers(dest="cmd", required=True)
52
+ a = sub.add_parser("agent"); a.add_argument("name"); a.add_argument("--cadence"); a.add_argument("--grace", default="15m")
53
+ a.add_argument("--max-runtime", default="1h"); a.add_argument("--cap-run-cost", type=float); a.add_argument("--cap-day-cost", type=float)
54
+ a.add_argument("--cap-run-tokens", type=int); a.add_argument("--evidence", action="store_true")
55
+ r = sub.add_parser("run"); r.add_argument("name"); r.add_argument("--evidence-file", action="append", default=[])
56
+ r.add_argument("--evidence-url", action="append", default=[]); r.add_argument("--source", default="cron")
57
+ r.add_argument("--log", help="append the command's stdout+stderr to this file (rv writes it, so it can double as evidence)")
58
+ s = sub.add_parser("start"); s.add_argument("name"); s.add_argument("--source", default="custom")
59
+ t = sub.add_parser("tool"); t.add_argument("run_id"); t.add_argument("tool"); t.add_argument("--input"); t.add_argument("--cost", type=float, default=0)
60
+ t.add_argument("--tokens", type=int, default=0); t.add_argument("--fail", action="store_true")
61
+ e = sub.add_parser("end"); e.add_argument("run_id"); e.add_argument("--status", default="ok"); e.add_argument("--cost", type=float, default=0)
62
+ e.add_argument("--tokens", type=int, default=0); e.add_argument("--evidence"); e.add_argument("--output-bytes", type=int)
63
+ sub.add_parser("status")
64
+ al = sub.add_parser("alerts"); al.add_argument("--ack", type=int)
65
+ argv = list(sys.argv[1:] if argv is None else argv)
66
+ tail = []
67
+ if argv and argv[0] == "run" and "--" in argv:
68
+ i = argv.index("--"); tail = argv[i + 1:]; argv = argv[:i]
69
+ args = p.parse_args(argv)
70
+
71
+ if args.cmd == "agent":
72
+ print(api("POST", "/v1/agents", {"name": args.name, "cadence_s": dur(args.cadence) if args.cadence else None,
73
+ "grace_s": dur(args.grace), "max_runtime_s": dur(args.max_runtime),
74
+ "cap_run_cost": args.cap_run_cost, "cap_day_cost": args.cap_day_cost,
75
+ "cap_run_tokens": args.cap_run_tokens, "evidence_required": args.evidence}))
76
+ elif args.cmd == "start":
77
+ print(api("POST", "/v1/runs/start", {"agent": args.name, "source": args.source})["run_id"])
78
+ elif args.cmd == "tool":
79
+ inp = json.loads(args.input) if args.input else None
80
+ api("POST", "/v1/runs/tool", {"run_id": args.run_id, "tool": args.tool, "input": inp, "cost": args.cost, "tokens": args.tokens, "ok": not args.fail})
81
+ elif args.cmd == "end":
82
+ ev = json.loads(args.evidence) if args.evidence else {}
83
+ print(api("POST", "/v1/runs/end", {"run_id": args.run_id, "status": args.status, "cost": args.cost, "tokens": args.tokens,
84
+ "evidence": ev, "output_bytes": args.output_bytes}))
85
+ elif args.cmd == "run":
86
+ cmd = tail
87
+ if not cmd:
88
+ sys.exit("rv run NAME -- CMD ...")
89
+ args.evidence_file = [os.path.abspath(f) for f in args.evidence_file]
90
+ r0 = api("POST", "/v1/runs/start", {"agent": args.name, "source": args.source, "meta": {"cmd": " ".join(cmd)}}, soft=True)
91
+ rid = r0.get("run_id") if r0 else None
92
+ t0 = time.time()
93
+ proc = subprocess.run(cmd, capture_output=True, text=True)
94
+ out = (proc.stdout or "") + (proc.stderr or "")
95
+ if args.log:
96
+ with open(args.log, "a") as lf:
97
+ lf.write(out)
98
+ else:
99
+ sys.stdout.write(proc.stdout or ""); sys.stderr.write(proc.stderr or "")
100
+ evidence = {}
101
+ for f in args.evidence_file: # evidence = file exists AND was modified during the run AND non-empty
102
+ ok = os.path.exists(f) and os.path.getsize(f) > 0 and os.path.getmtime(f) >= t0 - 1
103
+ evidence[f"file:{os.path.basename(f)}"] = bool(ok)
104
+ for u in args.evidence_url:
105
+ evidence[f"url:{u}"] = {"type": "url", "url": u, "expect": 200}
106
+ res = rid and api("POST", "/v1/runs/end", {"run_id": rid, "status": "ok" if proc.returncode == 0 else "fail",
107
+ "output_bytes": len(out.encode()), "evidence": evidence,
108
+ "meta": {"exit": proc.returncode, "error": (proc.stderr or "")[-500:] if proc.returncode else ""}}, soft=True)
109
+ sys.exit(proc.returncode)
110
+ elif args.cmd == "status":
111
+ for ag in api("GET", "/v1/agents"):
112
+ l = ag["last_run"]
113
+ print(f"{ag['name']:24s} {ag['state']:9s} last={time.strftime('%m-%d %H:%M', time.localtime(l['started'])) if l else '—':12s} "
114
+ f"cost24h={ag['cost_24h']:<8} alerts={ag['open_alerts']}")
115
+ elif args.cmd == "alerts":
116
+ if args.ack:
117
+ api("POST", f"/v1/alerts/{args.ack}/ack"); print("acked")
118
+ else:
119
+ for x in api("GET", "/v1/alerts"):
120
+ print(f"#{x['id']} {time.strftime('%m-%d %H:%M', time.localtime(x['ts']))} {x['agent']} [{x['kind']}] {x['message']}")
121
+
122
+
123
+ if __name__ == "__main__":
124
+ main()
@@ -0,0 +1,41 @@
1
+ Metadata-Version: 2.4
2
+ Name: runvouch
3
+ Version: 0.3.3
4
+ Summary: The watchdog for unattended AI agents: dead man's switch, cost cap and outcome check for cron'd LLM scripts, Claude Code routines, OpenClaw and n8n.
5
+ Author-email: RunVouch <hello@runvouch.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://runvouch.com
8
+ Project-URL: Documentation, https://runvouch.com/docs
9
+ Project-URL: Source, https://github.com/runvouch/runvouch
10
+ Keywords: ai-agents,monitoring,watchdog,cron,llm,claude-code,openclaw,observability
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: System :: Monitoring
16
+ Requires-Python: >=3.8
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ # runvouch
22
+
23
+ The watchdog for unattended AI agents. Alerts within minutes when a scheduled agent is
24
+ MISSED, FAILED, reported success without evidence, stuck in a retry storm, over budget,
25
+ drifting or stalled. Telegram, Slack, e-mail or webhook. Free for 3 agents.
26
+
27
+ ```bash
28
+ pip install runvouch
29
+ export RUNVOUCH_KEY=rv_... # free key at https://runvouch.com/app
30
+
31
+ # wrap any cron job / agent command
32
+ rv run nightly-report --evidence-file out/report.html -- python report.py
33
+ ```
34
+
35
+ ```python
36
+ import os, runvouch
37
+ with runvouch.vouch("nightly-report", evidence=lambda: {"report": os.path.exists("out.html")}) as run:
38
+ run.tool("openai.chat", {"model": "gpt-5"}, cost=0.01)
39
+ ```
40
+
41
+ Zero dependencies, fails open (monitoring can never break your job). Docs: https://runvouch.com/docs
@@ -0,0 +1,10 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ runvouch/__init__.py
5
+ runvouch/cli.py
6
+ runvouch.egg-info/PKG-INFO
7
+ runvouch.egg-info/SOURCES.txt
8
+ runvouch.egg-info/dependency_links.txt
9
+ runvouch.egg-info/entry_points.txt
10
+ runvouch.egg-info/top_level.txt
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ runvouch = runvouch.cli:main
3
+ rv = runvouch.cli:main
@@ -0,0 +1 @@
1
+ runvouch
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+