chore: import upstream snapshot with attribution

examples/python/redis_resource/example_redis.py

@@ -0,0 +1,259 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import copy as _copy
+import os
+import tempfile
+import uuid
+
+from mirage import MountMode, Workspace
+from mirage.commands.builtin.redis._provision import (file_read_provision,
+                                                      head_tail_provision,
+                                                      metadata_provision)
+from mirage.resource.redis import RedisResource
+from mirage.types import PathSpec
+
+REDIS_URL = "redis://localhost:6379/0"
+resource = RedisResource(url=REDIS_URL)
+
+
+async def main() -> None:
+    ws = Workspace({"/data": resource}, mode=MountMode.WRITE)
+
+    print("=== tee (create files) ===")
+    await ws.execute('echo "hello world" | tee /data/hello.txt')
+    await ws.execute(
+        'echo \'{"name": "alice", "age": 30}\' | tee /data/user.json')
+    await ws.execute("mkdir /data/reports")
+    await ws.execute(
+        'echo "revenue,100\\nexpense,80" | tee /data/reports/q1.csv')
+
+    print("=== ls /data/ ===")
+    result = await ws.execute("ls /data/")
+    print(await result.stdout_str())
+
+    print("=== cat /data/hello.txt ===")
+    result = await ws.execute("cat /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== head -n 1 /data/reports/q1.csv ===")
+    result = await ws.execute("head -n 1 /data/reports/q1.csv")
+    print(await result.stdout_str())
+
+    print("=== tail -n 1 /data/reports/q1.csv ===")
+    result = await ws.execute("tail -n 1 /data/reports/q1.csv")
+    print(await result.stdout_str())
+
+    print("=== wc /data/hello.txt ===")
+    result = await ws.execute("wc /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== stat /data/hello.txt ===")
+    result = await ws.execute("stat /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== jq .name /data/user.json ===")
+    result = await ws.execute('jq ".name" /data/user.json')
+    print(await result.stdout_str())
+
+    print("=== not-found errors show the full virtual path ===")
+    for cmd in ("cat /data/missing.txt", "head /data/missing.txt",
+                "stat /data/missing.txt"):
+        result = await ws.execute(cmd)
+        print(f"$ {cmd}")
+        print(f"  exit={result.exit_code}  "
+              f"{(await result.stderr_str()).strip()}")
+
+    print("=== nl /data/reports/q1.csv ===")
+    result = await ws.execute("nl /data/reports/q1.csv")
+    print(await result.stdout_str())
+
+    print("=== tree /data/ ===")
+    result = await ws.execute("tree /data/")
+    print(await result.stdout_str())
+
+    print("=== find /data/ -name '*.txt' ===")
+    result = await ws.execute("find /data/ -name '*.txt'")
+    print(await result.stdout_str())
+
+    print("=== grep hello /data/hello.txt ===")
+    result = await ws.execute("grep hello /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== rg hello /data/hello.txt ===")
+    result = await ws.execute("rg hello /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== basename /data/hello.txt ===")
+    result = await ws.execute("basename /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== dirname /data/hello.txt ===")
+    result = await ws.execute("dirname /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== realpath /data/hello.txt ===")
+    result = await ws.execute("realpath /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== sort /data/reports/q1.csv ===")
+    result = await ws.execute("sort /data/reports/q1.csv")
+    print(await result.stdout_str())
+
+    print("=== tr a-z A-Z < /data/hello.txt ===")
+    result = await ws.execute("cat /data/hello.txt | tr a-z A-Z")
+    print(await result.stdout_str())
+
+    print("=== cp /data/hello.txt /data/hello_copy.txt ===")
+    await ws.execute("cp /data/hello.txt /data/hello_copy.txt")
+    result = await ws.execute("cat /data/hello_copy.txt")
+    print(await result.stdout_str())
+
+    print("=== mv /data/hello_copy.txt /data/renamed.txt ===")
+    await ws.execute("mv /data/hello_copy.txt /data/renamed.txt")
+    result = await ws.execute("ls /data/")
+    print(await result.stdout_str())
+
+    print("=== rm /data/renamed.txt ===")
+    await ws.execute("rm /data/renamed.txt")
+    result = await ws.execute("ls /data/")
+    print(await result.stdout_str())
+
+    print("=== du /data/ ===")
+    result = await ws.execute("du /data/")
+    print(await result.stdout_str())
+
+    print("=== sed ===")
+    result = await ws.execute("cat /data/hello.txt | sed s/hello/goodbye/")
+    print(await result.stdout_str())
+
+    print("=== awk ===")
+    result = await ws.execute("cat /data/reports/q1.csv | awk -F, '{print $1}'"
+                              )
+    print(await result.stdout_str())
+
+    print("=== uniq ===")
+    await ws.execute('echo "a\\na\\nb\\nb\\nc" | tee /data/dup.txt')
+    result = await ws.execute("sort /data/dup.txt | uniq")
+    print(await result.stdout_str())
+
+    print("=== rev ===")
+    result = await ws.execute("cat /data/hello.txt | rev")
+    print(await result.stdout_str())
+
+    print("=== md5 /data/hello.txt ===")
+    result = await ws.execute("md5 /data/hello.txt")
+    print(await result.stdout_str())
+
+    print("=== base64 /data/hello.txt ===")
+    result = await ws.execute("base64 /data/hello.txt")
+    print(await result.stdout_str())
+
+    # ── provision: cost estimates before execution ─────────────────
+    print("\n=== PROVISION (cost estimates before execution) ===\n")
+    print(
+        "  Redis ops have no ranged GET — every read fetches the full value.")
+    print("  Provision lets the agent budget IO / compute before running.\n")
+
+    # 1. ws.execute(cmd, provision=True) returns a ProvisionResult
+    ws_prov = await ws.execute("cat /data/hello.txt", provision=True)
+    print("  ws.execute('cat /data/hello.txt', provision=True):")
+    print(f"    command        = {ws_prov.command!r}")
+    print(f"    network_read   = {ws_prov.network_read}")
+    print(f"    read_ops       = {ws_prov.read_ops}")
+    print(f"    precision      = {ws_prov.precision}")
+    print()
+
+    # 2. Redis-specific helpers — exact Redis cost, callable standalone
+    paths = [
+        PathSpec(virtual="/data/hello.txt",
+                 directory="/data",
+                 resource_path="hello.txt"),
+        PathSpec(virtual="/data/user.json",
+                 directory="/data",
+                 resource_path="user.json"),
+    ]
+    accessor = resource.accessor
+
+    read_cost = await file_read_provision(accessor, paths, command="cat")
+    print("  file_read_provision(accessor, [hello.txt, user.json]):")
+    print(f"    network_read   = {read_cost.network_read} bytes "
+          f"({read_cost.read_ops} reads)")
+    print(f"    precision      = {read_cost.precision}")
+
+    head_cost = await head_tail_provision(accessor, paths, command="head -n 1")
+    print("  head_tail_provision(...) — Redis fetches full value regardless:")
+    print(f"    network_read   = {head_cost.network_read} bytes")
+
+    meta_cost = await metadata_provision(accessor, paths, command="stat")
+    print("  metadata_provision(...) — stat/ls/find cost zero network bytes:")
+    print(f"    network_read   = {meta_cost.network_read} bytes")
+    print(f"    read_ops       = {meta_cost.read_ops}")
+
+    # ── persistence: save / load / copy / deepcopy ──────────────────
+    # Redis has redacted connection config: saved state contains the full
+    # key+value dump, but caller must supply a fresh RedisResource (often
+    # pointed at a different
+    # Redis instance / different key prefix) at load time.
+    print("\n=== PERSISTENCE ===\n")
+    with tempfile.NamedTemporaryFile(suffix=".tar", delete=False) as f:
+        snap = f.name
+    dst_prefix = f"mirage:loaded:{uuid.uuid4().hex[:8]}:"
+    try:
+        await ws.snapshot(snap)
+        print(f"  saved → {snap} ({os.path.getsize(snap)} bytes)")
+
+        try:
+            await Workspace.load(snap)
+            print("  ✗ load() should have raised without resources=")
+        except ValueError as e:
+            print(f"  ✓ load() w/o resources raises: "
+                  f"{str(e).splitlines()[0][:70]}…")
+
+        # Load into a fresh Redis prefix (same instance, isolated namespace)
+        loaded = await Workspace.load(snap,
+                                      resources={
+                                          "/data":
+                                          RedisResource(url=REDIS_URL,
+                                                        key_prefix=dst_prefix)
+                                      })
+        r = await loaded.execute("ls /data/")
+        print(f"  loaded ws ls /data: "
+              f"{(await r.stdout_str()).strip()[:60]}…")
+
+        # copy(): in-process, reuses same RedisResource, both copies
+        # see the same Redis state
+        cp = await ws.copy()
+        print(f"  copy() mounts: {[m.prefix for m in cp.mounts()]}")
+
+        for op_name, op in (("deepcopy", _copy.deepcopy), ("shallow copy",
+                                                           _copy.copy)):
+            try:
+                op(ws)
+                print(f"  ✗ {op_name} should have raised")
+            except NotImplementedError as e:
+                print(f"  ✓ {op_name} raises: {str(e)[:60]}…")
+    finally:
+        os.unlink(snap)
+        # Cleanup loaded keys
+        import redis as sync_redis
+        sc = sync_redis.Redis.from_url(REDIS_URL)
+        for key in sc.scan_iter(f"{dst_prefix}*"):
+            sc.delete(key)
+        sc.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/redis_resource/example_redis_cache.py

@@ -0,0 +1,44 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from mirage.cache.file.redis import RedisFileCacheStore
+
+REDIS_URL = os.environ.get("REDIS_URL", "redis://localhost:6379/0")
+
+
+async def main() -> None:
+    # A Redis-backed file cache: file content is stored in Redis, so two
+    # Mirage processes sharing a key_prefix share one content cache.
+    key_prefix = "mirage:example:cache:"
+    cache = RedisFileCacheStore(url=REDIS_URL, key_prefix=key_prefix)
+
+    print("=== RedisFileCacheStore: FileCache backed by Redis ===")
+    await cache.set("/data/hello.txt", b"hello from redis cache")
+    got = await cache.get("/data/hello.txt")
+    print(f"cache.get: {got.decode() if got else '(none)'}")
+
+    # Another store with the same key_prefix sees the same data.
+    cache2 = RedisFileCacheStore(url=REDIS_URL, key_prefix=key_prefix)
+    got2 = await cache2.get("/data/hello.txt")
+    print(f"cache2.get: {got2.decode() if got2 else '(none)'}")
+
+    await cache.clear()
+    print("wiped cache keys from Redis")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/redis_resource/example_redis_fuse.py

@@ -0,0 +1,67 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from mirage import Mount, MountMode, Workspace
+from mirage.resource.redis import RedisResource
+
+REDIS_URL = "redis://localhost:6379/0"
+KEY_PREFIX = "mirage:fs:"
+
+
+async def _seed():
+    resource = RedisResource(url=REDIS_URL, key_prefix=KEY_PREFIX)
+    ws = Workspace({"/data/": resource}, mode=MountMode.WRITE)
+    await ws.execute('echo "hello world" | tee /data/hello.txt')
+    await ws.execute("mkdir /data/sub")
+    await ws.execute('echo "nested content" | tee /data/sub/nested.txt')
+    await ws.execute('echo \'{"key": "value"}\' | tee /data/example.json')
+
+
+asyncio.run(_seed())
+print("Seeded Redis with sample files")
+
+resource = RedisResource(url=REDIS_URL, key_prefix=KEY_PREFIX)
+
+with Workspace({"/data/": Mount(resource, mode=MountMode.WRITE,
+                                fuse=True)}) as ws:
+    mp = ws.fuse_mountpoint
+
+    print(f"\n=== FUSE MODE: mounted at {mp} ===\n")
+
+    data_path = mp
+
+    print("--- os.listdir() ---")
+    entries = os.listdir(data_path)
+    for e in entries:
+        full = f"{data_path}/{e}"
+        if os.path.isfile(full):
+            size = os.path.getsize(full)
+            print(f"  {e:30s} {size:>10,} bytes")
+        else:
+            print(f"  {e:30s} <dir>")
+
+    print(f"\n>>> FUSE mounted at: {mp}")
+    print(">>> Open another terminal and try:")
+    print(f">>>   ls -la {mp}/")
+    print(f">>>   cat {mp}/hello.txt")
+    print(f">>>   cat {mp}/example.json | jq .")
+    print(">>> Press Enter to unmount and exit...")
+    input()
+
+    records = ws.ops.records
+    total = sum(r.bytes for r in records)
+    print(f"\nStats: {len(records)} ops, {total} bytes transferred")

examples/python/redis_resource/example_redis_index.py

@@ -0,0 +1,71 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+import time
+
+from mirage import Workspace
+from mirage.cache.index import (IndexEntry, RedisIndexCacheStore,
+                                RedisIndexConfig)
+from mirage.resource.ram import RAMResource
+
+REDIS_URL = os.environ.get("REDIS_URL", "redis://localhost:6379/0")
+
+
+def _file(name: str) -> IndexEntry:
+    return IndexEntry(id=name, name=name, resource_type="file")
+
+
+async def main() -> None:
+    # A workspace-level ``index`` config points every mounted resource's
+    # index cache at the same Redis instance. Two separate Mirage processes
+    # that share a key_prefix then share one index -- the building block for
+    # running the same mounts locally and in a remote sandbox.
+    key_prefix = f"mirage:example:idx:{int(time.time() * 1000)}:"
+    index_config = RedisIndexConfig(url=REDIS_URL, key_prefix=key_prefix)
+
+    # Workspace A: a RAM mount whose INDEX is backed by Redis (not RAM).
+    ram_a = RAMResource()
+    Workspace({"/data": ram_a}, index=index_config)
+    print("index store A is redis-backed: "
+          f"{isinstance(ram_a.index, RedisIndexCacheStore)}")
+
+    # Populate the shared Redis index through workspace A.
+    await ram_a.index.put("/data/hello.txt", _file("hello.txt"))
+    await ram_a.index.set_dir(
+        "/data",
+        [("hello.txt", _file("hello.txt")), ("notes.md", _file("notes.md"))],
+    )
+
+    # Workspace B: a separate resource pointed at the same Redis index
+    # (same key_prefix). It sees what A cached without re-listing anything.
+    ram_b = RAMResource()
+    Workspace({"/data": ram_b}, index=index_config)
+
+    entry = await ram_b.index.get("/data/hello.txt")
+    name = entry.entry.name if entry.entry else "(none)"
+    print(f"shared index entry: {name}")
+
+    listing = await ram_b.index.list_dir("/data")
+    print(f"shared index listing: {', '.join(listing.entries or [])}")
+
+    await ram_a.index.clear()
+    await ram_a.index.close()
+    await ram_b.index.close()
+    print("wiped test keys from Redis")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/redis_resource/example_redis_vfs.py

@@ -0,0 +1,63 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import sys
+
+from mirage import MountMode, Workspace
+from mirage.resource.redis import RedisResource
+
+REDIS_URL = "redis://localhost:6379/0"
+
+
+async def _seed():
+    resource = RedisResource(url=REDIS_URL)
+    ws = Workspace({"/data": resource}, mode=MountMode.WRITE)
+    await ws.execute('echo "hello world" | tee /data/hello.txt')
+    await ws.execute("mkdir /data/sub")
+    await ws.execute('echo "nested" | tee /data/sub/nested.txt')
+
+
+asyncio.run(_seed())
+
+resource = RedisResource(url=REDIS_URL)
+ws = Workspace({"/data": resource}, mode=MountMode.WRITE)
+
+with ws:
+    vos = sys.modules["os"]
+    print("=== VFS MODE ===\n")
+
+    print("--- os.listdir() ---")
+    entries = vos.listdir("/data")
+    for e in entries:
+        print(f"  {e}")
+
+    print("\n--- open() + read ---")
+    with open("/data/hello.txt") as f:
+        print(f"  {f.read().strip()}")
+
+    print("\n--- os.path.exists() ---")
+    print(f"  hello.txt: {vos.path.exists('/data/hello.txt')}")
+    print(f"  nope.txt: {vos.path.exists('/data/nope.txt')}")
+
+    print("\n--- os.path.isdir() ---")
+    print(f"  /data/sub: {vos.path.isdir('/data/sub')}")
+
+    print("\n--- os.listdir() sub ---")
+    for e in vos.listdir("/data/sub"):
+        print(f"  {e}")
+
+    records = ws.ops.records
+    total = sum(r.bytes for r in records)
+    print(f"\nStats: {len(records)} ops, {total} bytes transferred")