chore: import upstream snapshot with attribution

examples/python/mongodb/mongodb.py

@@ -0,0 +1,143 @@
+# ========= 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 dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.mongodb import MongoDBConfig, MongoDBResource
+
+load_dotenv(".env.development")
+
+DB = "mirage_test"
+COLL_HET = "heterogeneous"
+COLL_EMB = "embeddings"
+COLL_TXT = "text_indexed"
+VIEW = "high_rated_films"
+
+config = MongoDBConfig(
+    uri=os.environ["MONGODB_URI"],
+    databases=[DB],
+    elide_fields={f"{DB}.{COLL_EMB}": ["vector"]},
+)
+resource = MongoDBResource(config=config)
+
+
+async def _run(ws, cmd):
+    print(f"\n>>> {cmd}")
+    r = await ws.execute(cmd)
+    out = (await r.stdout_str()).strip()
+    err = await r.stderr_str()
+    if out:
+        for line in out.splitlines()[:8]:
+            print(f"  {line[:160]}")
+        total = len(out.splitlines())
+        if total > 8:
+            print(f"  ... ({total} lines total)")
+    if err:
+        print(f"  [stderr] {err.strip()[:160]}")
+    if not out and not err:
+        print(f"  (empty, exit={r.exit_code})")
+    return r
+
+
+async def main():
+    ws = Workspace({"/mongodb": resource}, mode=MountMode.READ)
+
+    coll_doc = f"/mongodb/{DB}/collections/{COLL_HET}/documents.jsonl"
+    coll_schema = f"/mongodb/{DB}/collections/{COLL_HET}/schema.json"
+    emb_doc = f"/mongodb/{DB}/collections/{COLL_EMB}/documents.jsonl"
+    text_doc = f"/mongodb/{DB}/collections/{COLL_TXT}/documents.jsonl"
+    view_doc = f"/mongodb/{DB}/views/{VIEW}/documents.jsonl"
+    view_schema = f"/mongodb/{DB}/views/{VIEW}/schema.json"
+    db_json = f"/mongodb/{DB}/database.json"
+
+    print("=" * 60)
+    print("DIRECTORY LISTING")
+    print("=" * 60)
+    await _run(ws, "ls /mongodb/")
+    await _run(ws, f"ls /mongodb/{DB}/")
+    await _run(ws, f"ls /mongodb/{DB}/collections/")
+    await _run(ws, f"ls /mongodb/{DB}/views/")
+    await _run(ws, f"ls /mongodb/{DB}/collections/{COLL_HET}/")
+    await _run(ws, f"tree -L 3 /mongodb/{DB}/")
+
+    print("\n" + "=" * 60)
+    print("CAT (database.json, schema.json, documents.jsonl)")
+    print("=" * 60)
+    await _run(ws, f'cat "{db_json}"')
+    await _run(ws, f'cat "{coll_schema}"')
+    await _run(ws, f'cat "{view_schema}"')
+    await _run(ws, f'cat -n "{coll_schema}"')
+    await _run(ws, f'cat -n "{coll_doc}"')
+
+    print("\n" + "=" * 60)
+    print("HEAD / TAIL / WC / STAT")
+    print("=" * 60)
+    await _run(ws, f'head -n 3 "{coll_doc}"')
+    await _run(ws, f'tail -n 3 "{coll_doc}"')
+    await _run(ws, f'wc -l "{coll_doc}"')
+    await _run(ws, f'stat "{coll_doc}"')
+    await _run(ws, f'head -n 2 "{view_doc}"')
+
+    print("\n" + "=" * 60)
+    print("ELIDE_FIELDS in action (embedding dropped from output)")
+    print("=" * 60)
+    await _run(ws, f'head -n 1 "{emb_doc}"')
+
+    print("\n" + "=" * 60)
+    print("GREP at every scope")
+    print("=" * 60)
+    await _run(ws, f'grep -c title "{coll_doc}"')
+    await _run(ws, f'grep -m 3 title "{coll_doc}"')
+    await _run(ws, f'grep mongodb "/mongodb/{DB}/collections/{COLL_TXT}/"')
+    await _run(ws, f'grep mongodb "/mongodb/{DB}/"')
+    await _run(ws, 'grep mongodb "/mongodb/"')
+
+    print("\n" + "=" * 60)
+    print("RG at db / root scope")
+    print("=" * 60)
+    await _run(ws, f'rg database "/mongodb/{DB}/"')
+    await _run(ws, 'rg database "/mongodb/"')
+
+    print("\n" + "=" * 60)
+    print("JQ on documents.jsonl")
+    print("=" * 60)
+    await _run(ws, f'jq -r ".[] | .title" "{coll_doc}" | head -n 5')
+    await _run(ws, f'jq -r \'.[] | ._id["$oid"]\' "{coll_doc}" | head -n 5')
+    await _run(
+        ws, f'jq -r ".[] | select(.year >= 2024) | .title" "{coll_doc}"'
+        " | head -n 5")
+    await _run(ws, f'jq -r ".[] | .body" "{text_doc}" | head -n 3')
+
+    print("\n" + "=" * 60)
+    print("FIND")
+    print("=" * 60)
+    await _run(ws, f'find "/mongodb/{DB}/" -name "schema.json"')
+    await _run(ws, f'find "/mongodb/{DB}/" -name "documents.jsonl"')
+    await _run(ws, f'find "/mongodb/{DB}/" -maxdepth 2')
+
+    print("\n" + "=" * 60)
+    print("CD + pwd + ls + relative path read")
+    print("=" * 60)
+    await ws.execute(f'cd "/mongodb/{DB}/collections/{COLL_HET}"')
+    await _run(ws, "pwd")
+    await _run(ws, "ls")
+    await _run(ws, 'head -n 1 documents.jsonl')
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/mongodb/mongodb_fuse.py

@@ -0,0 +1,105 @@
+# ========= 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 json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import Mount, MountMode, Workspace
+from mirage.resource.mongodb import MongoDBConfig, MongoDBResource
+
+load_dotenv(".env.development")
+
+DB = "mirage_test"
+COLL = "heterogeneous"
+VIEW = "high_rated_films"
+
+config = MongoDBConfig(uri=os.environ["MONGODB_URI"], databases=[DB])
+resource = MongoDBResource(config=config)
+
+with Workspace({"/mongodb/": Mount(resource, mode=MountMode.READ,
+                                   fuse=True)}) as ws:
+    mp = ws.fuse_mountpoint
+
+    print(f"=== FUSE MODE: mounted at {mp} ===\n")
+
+    print("--- listdir() root (databases) ---")
+    for db in os.listdir(mp):
+        print(f"  {db}")
+
+    print(f"\n--- listdir() /mongodb/{DB} (entities) ---")
+    for entry in os.listdir(f"{mp}/{DB}"):
+        print(f"  {entry}")
+
+    print(f"\n--- listdir() /mongodb/{DB}/collections ---")
+    for col in os.listdir(f"{mp}/{DB}/collections"):
+        print(f"  {col}")
+
+    print(f"\n--- listdir() /mongodb/{DB}/views ---")
+    for v in os.listdir(f"{mp}/{DB}/views"):
+        print(f"  {v}")
+
+    print(f"\n--- listdir() /mongodb/{DB}/collections/{COLL} (entity) ---")
+    for entry in os.listdir(f"{mp}/{DB}/collections/{COLL}"):
+        print(f"  {entry}")
+
+    print("\n--- open() database.json ---")
+    with open(f"{mp}/{DB}/database.json") as f:
+        db_meta = json.loads(f.read())
+    print(f"  collections: {len(db_meta.get('collections', []))}")
+    print(f"  views: {len(db_meta.get('views', []))}")
+
+    print(f"\n--- open() schema.json for {COLL} ---")
+    with open(f"{mp}/{DB}/collections/{COLL}/schema.json") as f:
+        schema = json.loads(f.read())
+    print(f"  kind: {schema.get('kind')}")
+    print(f"  fields: {len(schema.get('fields', []))}")
+    print(f"  indexes: {len(schema.get('indexes', []))}")
+
+    print(f"\n--- open() + read documents.jsonl for {COLL} ---")
+    path = f"{mp}/{DB}/collections/{COLL}/documents.jsonl"
+    with open(path) as f:
+        text = f.read().strip()
+    lines = [ln for ln in text.splitlines() if ln.strip()]
+    print(f"  documents: {len(lines)}")
+    for line in lines[:3]:
+        doc = json.loads(line)
+        print(f"  {doc.get('title', '?')}")
+
+    print(f"\n--- open() + read view documents for {VIEW} ---")
+    view_path = f"{mp}/{DB}/views/{VIEW}/documents.jsonl"
+    with open(view_path) as f:
+        view_text = f.read().strip()
+    view_lines = [ln for ln in view_text.splitlines() if ln.strip()]
+    print(f"  documents: {len(view_lines)}")
+    for line in view_lines[:3]:
+        doc = json.loads(line)
+        print(f"  {doc.get('title', '?')} (rating={doc.get('rating', '?')})")
+
+    print(f"\n>>> FUSE mounted at: {mp}")
+    print(">>> Open another terminal and try:")
+    print(f">>>   ls {mp}/{DB}/collections/")
+    print(f">>>   head -n 3 {mp}/{DB}/collections/{COLL}/documents.jsonl")
+    if sys.stdin.isatty():
+        print(">>> Press Enter to unmount and exit...")
+        input()
+    else:
+        print(">>> (non-interactive: unmounting now)")
+
+    records = ws.ops.records
+    total = sum(r.bytes for r in records)
+    print(f"\nStats: {len(records)} ops, "
+          f"{total} bytes transferred")

examples/python/mongodb/mongodb_vfs.py

@@ -0,0 +1,112 @@
+# ========= 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 json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.mongodb import MongoDBConfig, MongoDBResource
+
+load_dotenv(".env.development")
+
+DB = "mirage_test"
+COLL = "heterogeneous"
+VIEW = "high_rated_films"
+
+config = MongoDBConfig(uri=os.environ["MONGODB_URI"], databases=[DB])
+resource = MongoDBResource(config=config)
+
+
+async def main():
+    with Workspace({"/mongodb/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print("=== VFS MODE: open() reads from MongoDB ===\n")
+
+        print("--- listdir() root (databases) ---")
+        for db in vos.listdir("/mongodb"):
+            print(f"  {db}")
+
+        print(f"\n--- listdir() /mongodb/{DB} (entities) ---")
+        for entry in vos.listdir(f"/mongodb/{DB}"):
+            print(f"  {entry}")
+
+        print(f"\n--- listdir() /mongodb/{DB}/collections ---")
+        collections = vos.listdir(f"/mongodb/{DB}/collections")
+        for col in collections:
+            print(f"  {col}")
+
+        print(f"\n--- listdir() /mongodb/{DB}/views ---")
+        views = vos.listdir(f"/mongodb/{DB}/views")
+        for v in views:
+            print(f"  {v}")
+
+        print(f"\n--- listdir() /mongodb/{DB}/collections/{COLL} (entity) ---")
+        for entry in vos.listdir(f"/mongodb/{DB}/collections/{COLL}"):
+            print(f"  {entry}")
+
+        print("\n--- open() database.json ---")
+        with open(f"/mongodb/{DB}/database.json") as f:
+            db_meta = json.loads(f.read())
+        print(f"  collections: {len(db_meta.get('collections', []))}")
+        print(f"  views: {len(db_meta.get('views', []))}")
+
+        print(f"\n--- open() schema.json for {COLL} ---")
+        with open(f"/mongodb/{DB}/collections/{COLL}/schema.json") as f:
+            schema = json.loads(f.read())
+        print(f"  kind: {schema.get('kind')}")
+        print(f"  fields: {len(schema.get('fields', []))}")
+        print(f"  indexes: {len(schema.get('indexes', []))}")
+
+        print(f"\n--- open() + read documents.jsonl for {COLL} ---")
+        path = f"/mongodb/{DB}/collections/{COLL}/documents.jsonl"
+        with open(path) as f:
+            content = f.read()
+        lines = [ln for ln in content.strip().split("\n") if ln.strip()]
+        print(f"  documents: {len(lines)}")
+        for line in lines[:3]:
+            doc = json.loads(line)
+            print(f"  [{doc['_id']['$oid']}] {doc.get('title', '?')}")
+
+        print(f"\n--- open() + read view documents for {VIEW} ---")
+        view_path = f"/mongodb/{DB}/views/{VIEW}/documents.jsonl"
+        with open(view_path) as f:
+            view_content = f.read()
+        view_lines = [
+            ln for ln in view_content.strip().split("\n") if ln.strip()
+        ]
+        print(f"  documents: {len(view_lines)}")
+        for line in view_lines[:3]:
+            doc = json.loads(line)
+            title = doc.get("title", "?")
+            rating = doc.get("rating", "?")
+            print(f"  {title} (rating={rating})")
+
+        print("\n--- bash history ---")
+        with open("/.bash_history") as f:
+            for i, line in enumerate(f):
+                if i >= 6:
+                    break
+                print(f"  {line.rstrip()[:120]}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, "
+              f"{total} bytes transferred")
+
+
+asyncio.run(main())