yoro-cache 0.1.1__tar.gz

yoro_cache-0.1.1/LICENSE

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

yoro_cache-0.1.1/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: yoro-cache
+Version: 0.1.1
+Summary: YORO — You Only Reason Once. A drop-in LLM caching proxy that invalidates on change and replays cached reasoning instead of serving stale answers.
+Author: Chaitanya Pinapaka
+License: MIT
+Project-URL: Homepage, https://yorocache.com
+Project-URL: Repository, https://github.com/ChaitanyaPinapaka/yoro-cache
+Keywords: llm,cache,semantic-cache,agents,inference,proxy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: requests>=2.30
+Provides-Extra: embed
+Requires-Dist: sentence-transformers>=3.0; extra == "embed"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# YORO — You Only Reason Once
+
+![tests](https://github.com/ChaitanyaPinapaka/yoro-cache/actions/workflows/tests.yml/badge.svg)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+YORO is an OpenAI-compatible caching proxy for LLM applications. Unlike a plain
+semantic cache, it tracks what each cached answer depends on and invalidates
+entries when those dependencies change, so it never serves an answer whose
+premises moved. The engine can also re-apply the cached reasoning to new inputs
+(*replay*) instead of re-deriving from scratch — available in the library today,
+wired into the proxy in the next release.
+
+Website: [yorocache.com](https://yorocache.com)
+
+## Why
+
+Semantic caches (GPTCache and similar) serve a cached answer whenever a new request
+is embedding-similar to a previous one. This saves tokens, but it has a failure mode
+that standard cache metrics do not surface: when the world changes, the cache keeps
+serving the old answer. In our measurements, a drift rate of just 5% (5% of recurring
+tasks whose true answer has changed) already makes over half of a naive cache's hits
+wrong, because popular items drift too and every later hit serves the dead answer.
+
+Adding invalidation alone is not sufficient. In agent workloads, the *method* behind
+an answer often lives in earlier interactions rather than in the current request. An
+invalidating cache correctly drops the stale entry, then re-derives without the
+method, caches the wrong result, and serves it — a failure mode we call
+*re-poisoning*. YORO addresses both failure modes: dependency fingerprints handle
+detection, and replay of the stored reasoning handles re-derivation.
+
+## Install
+
+```bash
+pip install "yoro-cache[embed]"
+# before the first PyPI release:
+pip install "yoro-cache[embed] @ git+https://github.com/ChaitanyaPinapaka/yoro-cache"
+```
+
+Requires Python 3.10+. The `[embed]` extra installs `sentence-transformers` for
+semantic matching; without it the library still works with the hash embedder or an
+external embedding endpoint.
+
+## Usage
+
+Run the proxy in front of any OpenAI-compatible endpoint (vLLM, llama.cpp server,
+OpenRouter, ...), then point your client at it. The worked example below is the
+setup this README was tested on — a local 35B reasoning model on an M-series Mac:
+
+```bash
+# 1. serve a local model via llama.cpp        (brew install llama.cpp)
+llama-server -hf deepreinforce-ai/Ornith-1.0-35B-GGUF --port 8000
+
+# 2. put YORO in front of it
+YORO_UPSTREAM=http://127.0.0.1:8000/v1 yoro serve    # listens on :8400
+
+# 3. point any OpenAI-compatible client at the proxy
+export OPENAI_BASE_URL=http://127.0.0.1:8400/v1
+```
+
+On this setup, a repeated ask serves from cache in ~12 ms against ~3.3 s upstream,
+with the cached reasoning trace preserved in the response.
+
+To use YORO under [OpenCode](https://opencode.ai), register the proxy as a custom
+provider in `opencode.json`:
+
+```json
+{ "provider": { "yoro": {
+    "npm": "@ai-sdk/openai-compatible",
+    "options": { "baseURL": "http://127.0.0.1:8400/v1" },
+    "models": { "ornith-35b": {} } } } }
+```
+
+The safe policy caches OpenCode's plain question turns and passes its tool-bearing
+(agentic) turns through untouched.
+
+To scope a cache entry to workspace state, pass dependency fingerprints. An entry
+only serves while its fingerprints match what was stored; when they change, the
+entry stops serving and the request is re-reasoned upstream:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://127.0.0.1:8400/v1", api_key="unused-locally")
+r = client.chat.completions.create(
+    model="your-model",
+    messages=[{"role": "user", "content": "Recompute the rollup for March"}],
+    extra_headers={"X-YORO-Deps": "rollup.csv:9f3ab2"},
+)
+```
+
+Every response reports the cache decision, and `yoro stats` (or
+`GET /yoro/stats`) shows running totals.
+
+| Header | Direction | Meaning |
+|---|---|---|
+| `X-YORO-Deps` | request | `name:fingerprint,...` — entry serves only while these match |
+| `X-YORO-Cache: 0` / `1` | request | force caching off / on for this call |
+| `X-YORO-Cache` | response | `HIT`, `MISS`, or `SKIP:<reason>` |
+| `X-YORO-Sim` | response | similarity of the matched entry (on hits) |
+
+### Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `YORO_UPSTREAM` | `http://127.0.0.1:8000/v1` | upstream OpenAI-compatible endpoint |
+| `YORO_PORT` | `8400` | proxy listen port |
+| `YORO_POLICY` | `safe` | `safe` refuses to cache tool-bearing or sampled turns; `aggressive` caches them |
+| `YORO_TAU_HIT` / `YORO_TAU_MISS` | `0.95` / `0.6` | reuse-acceptance / novelty thresholds |
+| `YORO_EMBED` | `all-MiniLM-L6-v2` | sentence-transformers model for matching |
+| `YORO_CACHE_PATH` | `~/.yoro/proxy_cache.json` | persistent cache location |
+
+The default policy is deliberately conservative: requests that carry tools, contain
+tool history, or use `temperature > 0.2` pass through uncached, because a stale hit
+in an agentic flow can corrupt real work. Caching such turns is an explicit opt-in.
+
+## How it works
+
+Each request is embedded and matched against the case store, then routed to the
+cheapest tier that is safe:
+
+1. **Serve** — the matched entry is fresh and similarity is high: return the cached
+   answer with no model call.
+2. **Replay** — same entry, but its dependencies changed: inject the stored
+   reasoning trace and apply it to the new inputs. Short output; no re-exploration.
+   (Library + benchmark today; proxy integration lands in the next release.)
+3. **Reason** — novel or borderline request: full reasoning upstream; the trace,
+   answer, and dependency fingerprints are cached.
+
+A novelty gate escalates look-alike-but-different requests to re-reasoning instead
+of force-fitting them into a near-match — trading some hit rate for correctness.
+
+## Evaluation
+
+The claims above are measured, on gpt-oss-120B (H100, vLLM) and reproduced on
+Qwen2.5-32B-Instruct-AWQ (4-bit, one consumer RTX 5090), across controlled sweeps of
+drift rate, near-miss rate, and invalidation-signal fidelity — 25 sweep levels,
+1,027 runs, 616,200 scored queries, 72.7M tokens in total. Selected results at
+drift 0.4 on the method-in-history workload:
+
+| | GPTCache-style | YORO serve-only | YORO replay | YORO replay (low effort) | no cache |
+|---|---|---|---|---|---|
+| Accuracy | 0.16 | 0.16 | **0.96** | 0.92 | 0.07 |
+| Output tokens vs no-cache | 4% | 42% | 21% | 10% | 100% |
+
+- On self-contained workloads, a no-invalidation cache reaches staleness 0.90
+  (share of hits serving a wrong answer) as drift rises; YORO holds ~0.00 at the
+  same matched thresholds, with accuracy 1.00.
+- Wrong serves split into two mechanistically different failure modes: *outdated*
+  (served an answer that was once correct) and *re-poisoned* (served an answer that
+  was never correct). The no-invalidation cache fails mostly outdated; an
+  invalidating cache without replay fails ~99% re-poisoned; replay reduces both to
+  near zero. Accuracy alone cannot distinguish these; the taxonomy metrics
+  (`outdated_rate`, `repoisoned_rate`) can.
+- Weakening the invalidation signal degrades YORO gracefully — staleness tracks the
+  share of missed signals and converges to naive-cache behavior at zero signal.
+
+The full benchmark harness (sweep driver, workload generators, taxonomy metrics,
+and the result curves behind these numbers) lands in this repository in an upcoming
+release.
+
+## Scope and limitations
+
+- The replay result is measured in the *method-in-history* regime, where re-asks
+  reference a procedure established earlier — the normal case for long-running
+  agents. If every request restates its full context, a plain cache with
+  invalidation performs equally well on correctness.
+- Replay is validated on multi-step arithmetic procedures; non-numeric procedures
+  (extraction rules, rubrics, tool plans) have not yet been evaluated.
+- Replay quality depends on the invalidation signal. Without dependency
+  fingerprints, YORO falls back to conservative matching and behaves like a
+  gated semantic cache.
+- Related work: Buffer of Thoughts, Metacognitive Reuse, and Analogical Prompting
+  reuse reasoning templates. YORO's contribution is making reuse safe and
+  accounted for: invalidation, the failure-mode taxonomy, and separate input/output
+  token accounting.
+
+## Repository layout
+
+```
+yoro/    library and proxy: cache, matcher, invalidation, replay, CLI
+bench/   the benchmark harness: rungs, sweeps, taxonomy metrics, result curves, runbook
+tests/   library, proxy, and benchmark tests; no GPU required
+site/    yorocache.com (static)
+```
+
+## License
+
+MIT. Built and measured by [Chaitanya Pinapaka](https://github.com/ChaitanyaPinapaka).

yoro_cache-0.1.1/README.md

@@ -0,0 +1,188 @@
+# YORO — You Only Reason Once
+
+![tests](https://github.com/ChaitanyaPinapaka/yoro-cache/actions/workflows/tests.yml/badge.svg)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+YORO is an OpenAI-compatible caching proxy for LLM applications. Unlike a plain
+semantic cache, it tracks what each cached answer depends on and invalidates
+entries when those dependencies change, so it never serves an answer whose
+premises moved. The engine can also re-apply the cached reasoning to new inputs
+(*replay*) instead of re-deriving from scratch — available in the library today,
+wired into the proxy in the next release.
+
+Website: [yorocache.com](https://yorocache.com)
+
+## Why
+
+Semantic caches (GPTCache and similar) serve a cached answer whenever a new request
+is embedding-similar to a previous one. This saves tokens, but it has a failure mode
+that standard cache metrics do not surface: when the world changes, the cache keeps
+serving the old answer. In our measurements, a drift rate of just 5% (5% of recurring
+tasks whose true answer has changed) already makes over half of a naive cache's hits
+wrong, because popular items drift too and every later hit serves the dead answer.
+
+Adding invalidation alone is not sufficient. In agent workloads, the *method* behind
+an answer often lives in earlier interactions rather than in the current request. An
+invalidating cache correctly drops the stale entry, then re-derives without the
+method, caches the wrong result, and serves it — a failure mode we call
+*re-poisoning*. YORO addresses both failure modes: dependency fingerprints handle
+detection, and replay of the stored reasoning handles re-derivation.
+
+## Install
+
+```bash
+pip install "yoro-cache[embed]"
+# before the first PyPI release:
+pip install "yoro-cache[embed] @ git+https://github.com/ChaitanyaPinapaka/yoro-cache"
+```
+
+Requires Python 3.10+. The `[embed]` extra installs `sentence-transformers` for
+semantic matching; without it the library still works with the hash embedder or an
+external embedding endpoint.
+
+## Usage
+
+Run the proxy in front of any OpenAI-compatible endpoint (vLLM, llama.cpp server,
+OpenRouter, ...), then point your client at it. The worked example below is the
+setup this README was tested on — a local 35B reasoning model on an M-series Mac:
+
+```bash
+# 1. serve a local model via llama.cpp        (brew install llama.cpp)
+llama-server -hf deepreinforce-ai/Ornith-1.0-35B-GGUF --port 8000
+
+# 2. put YORO in front of it
+YORO_UPSTREAM=http://127.0.0.1:8000/v1 yoro serve    # listens on :8400
+
+# 3. point any OpenAI-compatible client at the proxy
+export OPENAI_BASE_URL=http://127.0.0.1:8400/v1
+```
+
+On this setup, a repeated ask serves from cache in ~12 ms against ~3.3 s upstream,
+with the cached reasoning trace preserved in the response.
+
+To use YORO under [OpenCode](https://opencode.ai), register the proxy as a custom
+provider in `opencode.json`:
+
+```json
+{ "provider": { "yoro": {
+    "npm": "@ai-sdk/openai-compatible",
+    "options": { "baseURL": "http://127.0.0.1:8400/v1" },
+    "models": { "ornith-35b": {} } } } }
+```
+
+The safe policy caches OpenCode's plain question turns and passes its tool-bearing
+(agentic) turns through untouched.
+
+To scope a cache entry to workspace state, pass dependency fingerprints. An entry
+only serves while its fingerprints match what was stored; when they change, the
+entry stops serving and the request is re-reasoned upstream:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://127.0.0.1:8400/v1", api_key="unused-locally")
+r = client.chat.completions.create(
+    model="your-model",
+    messages=[{"role": "user", "content": "Recompute the rollup for March"}],
+    extra_headers={"X-YORO-Deps": "rollup.csv:9f3ab2"},
+)
+```
+
+Every response reports the cache decision, and `yoro stats` (or
+`GET /yoro/stats`) shows running totals.
+
+| Header | Direction | Meaning |
+|---|---|---|
+| `X-YORO-Deps` | request | `name:fingerprint,...` — entry serves only while these match |
+| `X-YORO-Cache: 0` / `1` | request | force caching off / on for this call |
+| `X-YORO-Cache` | response | `HIT`, `MISS`, or `SKIP:<reason>` |
+| `X-YORO-Sim` | response | similarity of the matched entry (on hits) |
+
+### Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `YORO_UPSTREAM` | `http://127.0.0.1:8000/v1` | upstream OpenAI-compatible endpoint |
+| `YORO_PORT` | `8400` | proxy listen port |
+| `YORO_POLICY` | `safe` | `safe` refuses to cache tool-bearing or sampled turns; `aggressive` caches them |
+| `YORO_TAU_HIT` / `YORO_TAU_MISS` | `0.95` / `0.6` | reuse-acceptance / novelty thresholds |
+| `YORO_EMBED` | `all-MiniLM-L6-v2` | sentence-transformers model for matching |
+| `YORO_CACHE_PATH` | `~/.yoro/proxy_cache.json` | persistent cache location |
+
+The default policy is deliberately conservative: requests that carry tools, contain
+tool history, or use `temperature > 0.2` pass through uncached, because a stale hit
+in an agentic flow can corrupt real work. Caching such turns is an explicit opt-in.
+
+## How it works
+
+Each request is embedded and matched against the case store, then routed to the
+cheapest tier that is safe:
+
+1. **Serve** — the matched entry is fresh and similarity is high: return the cached
+   answer with no model call.
+2. **Replay** — same entry, but its dependencies changed: inject the stored
+   reasoning trace and apply it to the new inputs. Short output; no re-exploration.
+   (Library + benchmark today; proxy integration lands in the next release.)
+3. **Reason** — novel or borderline request: full reasoning upstream; the trace,
+   answer, and dependency fingerprints are cached.
+
+A novelty gate escalates look-alike-but-different requests to re-reasoning instead
+of force-fitting them into a near-match — trading some hit rate for correctness.
+
+## Evaluation
+
+The claims above are measured, on gpt-oss-120B (H100, vLLM) and reproduced on
+Qwen2.5-32B-Instruct-AWQ (4-bit, one consumer RTX 5090), across controlled sweeps of
+drift rate, near-miss rate, and invalidation-signal fidelity — 25 sweep levels,
+1,027 runs, 616,200 scored queries, 72.7M tokens in total. Selected results at
+drift 0.4 on the method-in-history workload:
+
+| | GPTCache-style | YORO serve-only | YORO replay | YORO replay (low effort) | no cache |
+|---|---|---|---|---|---|
+| Accuracy | 0.16 | 0.16 | **0.96** | 0.92 | 0.07 |
+| Output tokens vs no-cache | 4% | 42% | 21% | 10% | 100% |
+
+- On self-contained workloads, a no-invalidation cache reaches staleness 0.90
+  (share of hits serving a wrong answer) as drift rises; YORO holds ~0.00 at the
+  same matched thresholds, with accuracy 1.00.
+- Wrong serves split into two mechanistically different failure modes: *outdated*
+  (served an answer that was once correct) and *re-poisoned* (served an answer that
+  was never correct). The no-invalidation cache fails mostly outdated; an
+  invalidating cache without replay fails ~99% re-poisoned; replay reduces both to
+  near zero. Accuracy alone cannot distinguish these; the taxonomy metrics
+  (`outdated_rate`, `repoisoned_rate`) can.
+- Weakening the invalidation signal degrades YORO gracefully — staleness tracks the
+  share of missed signals and converges to naive-cache behavior at zero signal.
+
+The full benchmark harness (sweep driver, workload generators, taxonomy metrics,
+and the result curves behind these numbers) lands in this repository in an upcoming
+release.
+
+## Scope and limitations
+
+- The replay result is measured in the *method-in-history* regime, where re-asks
+  reference a procedure established earlier — the normal case for long-running
+  agents. If every request restates its full context, a plain cache with
+  invalidation performs equally well on correctness.
+- Replay is validated on multi-step arithmetic procedures; non-numeric procedures
+  (extraction rules, rubrics, tool plans) have not yet been evaluated.
+- Replay quality depends on the invalidation signal. Without dependency
+  fingerprints, YORO falls back to conservative matching and behaves like a
+  gated semantic cache.
+- Related work: Buffer of Thoughts, Metacognitive Reuse, and Analogical Prompting
+  reuse reasoning templates. YORO's contribution is making reuse safe and
+  accounted for: invalidation, the failure-mode taxonomy, and separate input/output
+  token accounting.
+
+## Repository layout
+
+```
+yoro/    library and proxy: cache, matcher, invalidation, replay, CLI
+bench/   the benchmark harness: rungs, sweeps, taxonomy metrics, result curves, runbook
+tests/   library, proxy, and benchmark tests; no GPU required
+site/    yorocache.com (static)
+```
+
+## License
+
+MIT. Built and measured by [Chaitanya Pinapaka](https://github.com/ChaitanyaPinapaka).

yoro_cache-0.1.1/bench/__init__.py

@@ -0,0 +1,33 @@
+"""YORO benchmark harness.
+
+A baseline ladder over labelled prompt streams, runnable locally with a mock model
+(`--smoke`, no GPU) or against any OpenAI-compatible endpoint, with per-level
+checkpoint/resume, optional cloud sinks (S3 / CloudWatch / W&B), and a hard
+auto-shutdown budget cap for rented GPUs.
+
+Modules:
+  budget   - BudgetGuard: spend tracking + auto-shutdown before the ceiling.
+  metrics  - per-prompt Outcome, run summary, cross-seed aggregation + significance.
+  ladder   - the five rungs (no-cache / exact / gptcache-semantic / behaviors / YORO).
+  wandb_log- thin W&B logger shim (falls back to stdout if wandb is absent).
+"""
+from .budget import BudgetGuard
+from .metrics import Outcome, summarize, aggregate_seeds, paired_t
+from .ladder import (Strategy, NoCache, ExactCache, SemanticCache, BehaviorsOnly,
+                     YOROStrategy, build_ladder)
+from .wandb_log import WandbLogger
+from .eventlog import EventLog, S3FileSink, CloudWatchSink
+from .checkpoint import Checkpoint
+from .convergence import Convergence, ci_halfwidth
+from .vast import VastCredit, stop_self
+
+__all__ = [
+    "BudgetGuard",
+    "Outcome", "summarize", "aggregate_seeds", "paired_t",
+    "Strategy", "NoCache", "ExactCache", "SemanticCache", "BehaviorsOnly", "YOROStrategy", "build_ladder",
+    "WandbLogger",
+    "EventLog", "S3FileSink", "CloudWatchSink",
+    "Checkpoint",
+    "Convergence", "ci_halfwidth",
+    "VastCredit", "stop_self",
+]

yoro_cache-0.1.1/bench/budget.py

@@ -0,0 +1,81 @@
+"""BudgetGuard — the safety feature that makes a multi-day, unattended, $500 rented-GPU
+run safe to leave alone.
+
+It tracks spend = instance $/hr x elapsed + any per-token API cost, and once spend
+crosses a soft fraction of the hard ceiling it fires a provider-specific shutdown hook
+(e.g. `vastai destroy instance <id>`) exactly once. Pair it with frequent checkpointing
+so the auto-shutdown (or a spot preemption) never loses results.
+
+The clock is injectable so the logic is unit-testable without waiting hours.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+
+@dataclass
+class BudgetGuard:
+    ceiling_usd: float                                  # HARD cap (e.g. 500)
+    hourly_usd: float                                   # instance price, e.g. Vast.ai spot $/hr
+    shutdown_frac: float = 0.9                          # auto-shutdown at 90% of the ceiling
+    clock: Callable[[], float] = time.time             # injectable for tests
+    on_shutdown: Optional[Callable[[], None]] = None    # provider terminate hook (fired once)
+    token_cost_usd: float = 0.0                         # accrued per-token cost (0 when self-hosting)
+    started_at: Optional[float] = None
+    _stopped: bool = field(default=False, repr=False)
+
+    def __post_init__(self):
+        if self.started_at is None:
+            self.started_at = self.clock()
+
+    def add_token_cost(self, usd: float) -> None:
+        self.token_cost_usd += max(0.0, usd)
+
+    def spent(self) -> float:
+        hours = max(0.0, (self.clock() - self.started_at) / 3600.0)
+        return hours * self.hourly_usd + self.token_cost_usd
+
+    def remaining(self) -> float:
+        return max(0.0, self.ceiling_usd - self.spent())
+
+    def soft_cap(self) -> float:
+        return self.ceiling_usd * self.shutdown_frac
+
+    def should_stop(self) -> bool:
+        return self.spent() >= self.soft_cap()
+
+    def check(self) -> bool:
+        """Call this periodically (e.g. every checkpoint). Returns True once spend crosses
+        the soft cap, firing the shutdown hook exactly once. Idempotent thereafter."""
+        if self._stopped:
+            return True
+        if self.should_stop():
+            self._stopped = True
+            if self.on_shutdown is not None:
+                try:
+                    self.on_shutdown()
+                except Exception:
+                    pass
+            return True
+        return False
+
+    def stop(self) -> None:
+        """Force-stop from an EXTERNAL signal (e.g. low real Vast credit), so a sweep that
+        shares this guard also halts — not just the current level."""
+        self._stopped = True
+
+    @property
+    def stopped(self) -> bool:
+        return self._stopped
+
+    def status(self) -> dict:
+        return {
+            "spent_usd": round(self.spent(), 2),
+            "remaining_usd": round(self.remaining(), 2),
+            "ceiling_usd": self.ceiling_usd,
+            "soft_cap_usd": round(self.soft_cap(), 2),
+            "hourly_usd": self.hourly_usd,
+            "stopped": self._stopped,
+        }

yoro_cache-0.1.1/bench/checkpoint.py

@@ -0,0 +1,67 @@
+"""Checkpoint + resume — so a Vast.ai spot preemption or the budget auto-shutdown never
+loses work. A checkpoint is a JSON snapshot of run state (cursor into the prompt stream,
+per-rung outcomes so far, cache contents, accumulated spend). It's written ATOMICALLY
+(temp file + os.replace, so a kill mid-write can't corrupt it) and mirrored to S3, so a
+fresh instance can pull the latest and continue from the cursor.
+
+Usage:
+    ck = Checkpoint("runs/phase0/ckpt.json", s3=("my-bucket", "yoro/phase0/ckpt.json"))
+    state = ck.load() or {"cursor": 0, "outcomes": {}}
+    ...                      # run from state["cursor"], periodically:
+    ck.save(state)
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from typing import Optional, Tuple
+
+
+def _s3():
+    try:
+        import boto3
+        return boto3.client("s3")
+    except Exception:
+        return None
+
+
+class Checkpoint:
+    def __init__(self, path: str, s3: Optional[Tuple[str, str]] = None):
+        self.path = path
+        self.s3 = s3                                     # (bucket, key) or None
+        self._c = _s3() if s3 else None
+
+    def save(self, state: dict) -> None:
+        d = os.path.dirname(os.path.abspath(self.path)) or "."
+        os.makedirs(d, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=d, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w") as f:
+                json.dump(state, f, default=str)
+            os.replace(tmp, self.path)                   # atomic on POSIX
+        finally:
+            if os.path.exists(tmp):
+                os.remove(tmp)
+        if self._c:
+            try:
+                self._c.upload_file(self.path, self.s3[0], self.s3[1])
+            except Exception as e:
+                print(f"[ckpt s3 err {str(e)[:70]}]")
+
+    def load(self) -> Optional[dict]:
+        if os.path.exists(self.path):
+            try:
+                with open(self.path) as f:
+                    return json.load(f)
+            except Exception:
+                pass                                     # fall through to S3
+        if self._c:
+            try:
+                os.makedirs(os.path.dirname(os.path.abspath(self.path)) or ".", exist_ok=True)
+                self._c.download_file(self.s3[0], self.s3[1], self.path)   # boto3 won't mkdir the target dir
+                with open(self.path) as f:
+                    return json.load(f)
+            except Exception:
+                return None
+        return None