cartograph-cli 0.7.2__tar.gz → 0.7.4__tar.gz

{cartograph_cli-0.7.2 → cartograph_cli-0.7.4}/CLAUDE.md

@@ -107,38 +107,6 @@ current directory (or the directory specified by `--target`).
     rules reset --language <lang> [--global]
       Restore a rules file to its default template.
 
-**Architect (project-level planning)**
-
-    architect init [--path X] [--force]
-      Scaffold a starter architect.py at the project root. Architect is
-      a project-local Python file describing components and relationships
-      (cross-domain: software, modeling, rtl, physical). The agent reads
-      it for app-level planning context before reaching for widgets.
-
-    architect validate [--path X]
-      Structural checks only: unique component ids, edge/parent ref
-      integrity, parent cycles, schema_version, known domains. The
-      vibes layer (kind/description/what) is intentionally not checked.
-
-    architect render [--path X] [--output X | --stdout] [--direction TD|TB|LR|BT|RL] [--force]
-      Render architect.py as a Mermaid flowchart. Defaults to writing
-      architect.mmd next to the source so it commits cleanly and renders
-      in GitHub. Refuses to render an invalid architecture unless --force.
-
-    architect link <component_id> <widget_dir> [--path X]
-      Link an installed widget to a Component slot. Multiple widgets
-      may compose one slot (router + validator + logger as one
-      service). Refuses if the widget is not installed under cg/, or
-      if it is already linked.
-
-    architect link <component_id> <widget_dir> --clear [--path X]
-      Unlink a specific widget from a Component slot.
-
-    architect link <component_id> --clear [--path X]
-      Unlink ALL widgets from a Component slot. Edits architect.py via
-      AST surgery; comments outside the target Component block are
-      preserved.
-
 **Configuration**
 
     config [key] [value]

{cartograph_cli-0.7.2 → cartograph_cli-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartograph-cli
-Version: 0.7.2
+Version: 0.7.4
 Summary: Widget library manager for AI agents — CLI
 License-Expression: MIT
 License-File: LICENSE

cartograph_cli-0.7.4/cg/cg_universal_graph_cycles_python/.validation_stamp.json

@@ -0,0 +1 @@
+{"fingerprint": "b5dd0d134e637c9c93f85aababe75e58bdfcb7e0ad2457490f677fcfe3f2071c", "stamped_at": "2026-06-04T21:40:30.314561+00:00", "language": "python", "engine_version": 1, "runtime": "python 3.14.5", "test_results": {}, "validated_at": "2026-06-04T21:40:30.314237+00:00"}

{cartograph_cli-0.7.2 → cartograph_cli-0.7.4}/cg/cg_universal_graph_cycles_python/widget.json

@@ -2,7 +2,7 @@
   "meta": {
     "id": "universal-graph-cycles-python",
     "name": "Graph Cycles",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "domain": "universal",
     "tags": [
       "graph",
@@ -25,7 +25,7 @@
   },
   "validation": {
     "engine_version": 1,
-    "validated_at": "2026-05-02T04:23:51.124498+00:00",
-    "runtime": "python 3.13.13"
+    "validated_at": "2026-06-04T21:40:31.582833+00:00",
+    "runtime": "python 3.14.5"
   }
 }

cartograph_cli-0.7.4/cg/infra_agent_cli_python/.cartograph_source

@@ -0,0 +1 @@
+{"owner": "benteigland11", "registry_url": "https://api.cartograph.tools"}

{cartograph_cli-0.7.2 → cartograph_cli-0.7.4}/cg/infra_agent_cli_python/widget.json

@@ -2,7 +2,7 @@
   "meta": {
     "id": "infra-agent-cli-python",
     "name": "Agent CLI",
-    "version": "1.2.1",
+    "version": "1.2.2",
     "domain": "infra",
     "tags": [
       "cli",
@@ -12,19 +12,19 @@
       "llm-tools"
     ]
   },
-  "description": "Declarative CLI framework for LLM/agent-driven tools. JSON output, no interactive prompts, grouped help, nested subcommands. Define commands as dicts, get argparse wiring for free.",
+  "description": "Declarative CLI framework that provides machine-first argparse wiring for LLM/agent-driven tools. Features JSON-first output, non-interactive execution, and grouped help.",
   "tech_stack": {
     "language": "python",
     "dependencies": []
   },
   "library_notes": {
     "general": "Single responsibility - one widget does one thing. No global state. No project-specific code, hardcoded paths, credentials, or environment-specific values. Expose variation points as constructor parameters or function arguments - no hardcoded thresholds, colors, sizes, or behavior flags. URLs and endpoints belong in examples as demonstration data, not in src/ - if a widget needs a URL to operate, it must be a parameter the caller provides. All dependencies must be declared in widget.json tech_stack.dependencies. Widgets cannot depend on other widgets - they must be fully self-contained. If you need logic from another widget, copy it into src/ directly. Examples must run and exit cleanly with no user input, no network calls, and no external services or API keys - use fake/hardcoded data. The widget's own declared dependencies are fine and will be installed by the validator before the example runs. Do not modify library_notes - it is managed by Cartograph and will be restored on checkin.",
-    "language": "No project-specific names, identifiers, or terminology anywhere in src/, tests/, or examples/ - use generic names like 'user', 'item', 'value', 'example_org'. A test that references your project's real entity names is contaminated. Use pytest for all tests - no unittest. Type hints required on all public functions. No __init__.py in tests/. No if __name__ == '__main__' blocks in src/ files. Imports ordered: stdlib, third-party, local. ML domain: framework-free (numpy, scikit-learn, plain Python) and API-based inference (HTTP calls to OpenAI, Anthropic, HuggingFace Inference API) work everywhere. Heavy frameworks (torch, tensorflow, jax, and similar) are allowed but must be pre-installed - Cartograph will not auto-install them. Declare them in widget.json dependencies normally; consumers must also have them installed to validate.",
+    "language": "No project-specific names, identifiers, or terminology anywhere in src/, tests/, or examples/ - use generic names like 'user', 'item', 'value', 'example_org'. A test that references your project's real entity names is contaminated. Use pytest for all tests - no unittest. Type hints required on all public functions. No __init__.py in tests/. No if __name__ == '__main__' blocks in src/ files. Imports ordered: stdlib, third-party, local. ML domain: framework-free (numpy, scikit-learn, plain Python) and API-based inference (HTTP calls to OpenAI, Anthropic, HuggingFace Inference API) work everywhere. Heavy optional frameworks must be pre-installed - Cartograph will not auto-install them. Declare dependencies in widget.json normally; consumers must also have them installed to validate.",
     "domain": "Accept all paths and hostnames as parameters - never construct paths from hardcoded roots. Config keys, log formats, and health check endpoints must be configurable. Return structured status objects rather than printing; let the caller handle output. Side effects (file writes, process spawns) must be opt-in, not automatic."
   },
   "validation": {
     "engine_version": 1,
-    "validated_at": "2026-04-12T20:49:05.866788+00:00",
-    "runtime": "python 3.14.3"
+    "validated_at": "2026-05-02T04:28:33.143608+00:00",
+    "runtime": "python 3.13.13"
   }
 }

cartograph_cli-0.7.4/cg/infra_archive_manifest_consistency_python/examples/example_usage.py

@@ -0,0 +1,53 @@
+"""Example: verify a tarball matches a declared manifest.
+
+Builds an in-memory archive that includes an unintended __pycache__ file
+and shows the consistency check catching both an extra entry and a
+forbidden entry against caller-supplied declarations.
+"""
+
+import io
+import os
+import sys
+import tarfile
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from src.archive_manifest_consistency import check_consistency
+
+
+def _build(members):
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w") as tf:
+        for name, data in members:
+            info = tarfile.TarInfo(name=name)
+            info.size = len(data)
+            info.mode = 0o644
+            tf.addfile(info, io.BytesIO(data))
+    return buf.getvalue()
+
+
+def main() -> None:
+    archive = _build([
+        ("manifest.json", b'{"id": "example"}'),
+        ("src/a.py", b"x = 1\n"),
+        ("src/b.py", b"y = 2\n"),
+        ("__pycache__/a.cpython-312.pyc", b"compiled"),
+    ])
+
+    report = check_consistency(
+        archive,
+        expected={"manifest.json", "src/a.py", "src/b.py"},
+        required={"manifest.json"},
+        forbidden={"__pycache__/a.cpython-312.pyc"},
+    )
+
+    print(f"ok:                {report.ok}")
+    print(f"all_files:         {list(report.all_files)}")
+    print(f"missing:           {list(report.missing)}")
+    print(f"extra:             {list(report.extra)}")
+    print(f"required_missing:  {list(report.required_missing)}")
+    print(f"forbidden_present: {list(report.forbidden_present)}")
+
+
+if __name__ == "__main__":
+    main()

cartograph_cli-0.7.4/cg/infra_archive_manifest_consistency_python/src/archive_manifest_consistency.py

@@ -0,0 +1,107 @@
+"""Verify a tarball's contents match a declared file manifest.
+
+Given a tarball and three optional declarations, returns a structured
+report:
+
+  * `expected`  - the full enumerated set of paths the archive should
+                  contain. Anything in the archive not in this set is
+                  reported as `extra`; anything in this set not in the
+                  archive is reported as `missing`. When `expected` is
+                  omitted, neither `extra` nor `missing` is reported.
+  * `required`  - a subset that MUST be present, even when the full
+                  expected list is unknown. Useful for sanity checks
+                  ("manifest.json must be in the archive") without
+                  enumerating every file.
+  * `forbidden` - paths that must NOT be present. Useful for catching
+                  build artifacts or vendor dirs that should have been
+                  excluded at pack time.
+
+Pure stdlib (tarfile). Sets are returned sorted for stable diffs.
+"""
+
+import io
+import os
+import tarfile
+from dataclasses import dataclass
+
+
+class ConsistencyError(Exception):
+    """Base class for consistency errors."""
+
+
+@dataclass(frozen=True)
+class ConsistencyReport:
+    """Structured comparison result.
+
+    `ok` is True iff missing/extra/forbidden_present are all empty
+    relative to whatever declarations the caller provided. `all_files`
+    is the full sorted file list found in the archive (regular files
+    only - directories and links are excluded).
+    """
+
+    ok: bool
+    all_files: tuple[str, ...]
+    missing: tuple[str, ...]
+    extra: tuple[str, ...]
+    forbidden_present: tuple[str, ...]
+    required_missing: tuple[str, ...]
+
+
+def _list_archive_files(archive: bytes | str) -> set[str]:
+    """Return the set of regular-file paths inside the archive."""
+    if isinstance(archive, (bytes, bytearray)):
+        opener = tarfile.open(fileobj=io.BytesIO(archive), mode="r:*")
+    elif isinstance(archive, str):
+        if not os.path.isfile(archive):
+            raise ConsistencyError(f"archive not found: {archive!r}")
+        opener = tarfile.open(name=archive, mode="r:*")
+    else:
+        raise ConsistencyError(
+            f"archive must be bytes or path string, got {type(archive).__name__}"
+        )
+    with opener as tf:
+        return {m.name for m in tf.getmembers() if m.isreg()}
+
+
+def check_consistency(
+    archive: bytes | str,
+    *,
+    expected: set[str] | None = None,
+    required: set[str] | None = None,
+    forbidden: set[str] | None = None,
+) -> ConsistencyReport:
+    """Compare the archive's file list to the caller's declarations.
+
+    All declarations are optional - omitted ones contribute nothing to
+    the report's `ok` verdict. Path strings are compared literally; the
+    caller is responsible for normalizing separators or arcname prefixes
+    before calling.
+    """
+    found = _list_archive_files(archive)
+
+    missing: tuple[str, ...] = ()
+    extra: tuple[str, ...] = ()
+    if expected is not None:
+        missing = tuple(sorted(expected - found))
+        extra = tuple(sorted(found - expected))
+
+    required_missing: tuple[str, ...] = ()
+    if required is not None:
+        required_missing = tuple(sorted(required - found))
+
+    forbidden_present: tuple[str, ...] = ()
+    if forbidden is not None:
+        forbidden_present = tuple(sorted(forbidden & found))
+
+    ok = (
+        not missing and not extra
+        and not required_missing and not forbidden_present
+    )
+    return ConsistencyReport(
+        ok=ok,
+        all_files=tuple(sorted(found)),
+        missing=missing,
+        extra=extra,
+        forbidden_present=forbidden_present,
+        required_missing=required_missing,
+    )

cartograph_cli-0.7.4/cg/infra_archive_manifest_consistency_python/tests/test_archive_manifest_consistency.py

@@ -0,0 +1,148 @@
+import io
+import tarfile
+
+import pytest
+
+from src.archive_manifest_consistency import (
+    ConsistencyError,
+    check_consistency,
+)
+
+
+def _build_tar(members: list[tuple[str, bytes]]) -> bytes:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w") as tf:
+        for name, data in members:
+            info = tarfile.TarInfo(name=name)
+            info.size = len(data)
+            info.mode = 0o644
+            tf.addfile(info, io.BytesIO(data))
+    return buf.getvalue()
+
+
+def test_no_declarations_means_ok_with_full_listing():
+    data = _build_tar([("a.txt", b"x"), ("b.txt", b"y")])
+    r = check_consistency(data)
+    assert r.ok is True
+    assert r.all_files == ("a.txt", "b.txt")
+
+
+def test_expected_matches_archive_exactly():
+    data = _build_tar([("a.txt", b"x"), ("b.txt", b"y")])
+    r = check_consistency(data, expected={"a.txt", "b.txt"})
+    assert r.ok is True
+    assert r.missing == ()
+    assert r.extra == ()
+
+
+def test_extra_files_in_archive_reported():
+    data = _build_tar([("a.txt", b"x"), ("b.txt", b"y"), ("c.txt", b"z")])
+    r = check_consistency(data, expected={"a.txt", "b.txt"})
+    assert r.ok is False
+    assert r.extra == ("c.txt",)
+
+
+def test_missing_files_reported():
+    data = _build_tar([("a.txt", b"x")])
+    r = check_consistency(data, expected={"a.txt", "b.txt"})
+    assert r.ok is False
+    assert r.missing == ("b.txt",)
+
+
+def test_required_present_passes():
+    data = _build_tar([("manifest.json", b"{}"), ("a.txt", b"x")])
+    r = check_consistency(data, required={"manifest.json"})
+    assert r.ok is True
+    assert r.required_missing == ()
+
+
+def test_required_missing_reported():
+    data = _build_tar([("a.txt", b"x")])
+    r = check_consistency(data, required={"manifest.json"})
+    assert r.ok is False
+    assert r.required_missing == ("manifest.json",)
+
+
+def test_forbidden_absent_passes():
+    data = _build_tar([("src/a.py", b"x")])
+    r = check_consistency(data, forbidden={"__pycache__/junk.pyc"})
+    assert r.ok is True
+    assert r.forbidden_present == ()
+
+
+def test_forbidden_present_reported():
+    data = _build_tar([("src/a.py", b"x"), ("__pycache__/junk.pyc", b"y")])
+    r = check_consistency(data, forbidden={"__pycache__/junk.pyc"})
+    assert r.ok is False
+    assert r.forbidden_present == ("__pycache__/junk.pyc",)
+
+
+def test_combined_declarations_all_evaluated():
+    data = _build_tar([
+        ("manifest.json", b"{}"),
+        ("a.txt", b"x"),
+        ("__pycache__/junk.pyc", b"y"),
+    ])
+    r = check_consistency(
+        data,
+        expected={"manifest.json", "a.txt"},
+        required={"manifest.json"},
+        forbidden={"__pycache__/junk.pyc"},
+    )
+    assert r.ok is False
+    assert r.extra == ("__pycache__/junk.pyc",)
+    assert r.forbidden_present == ("__pycache__/junk.pyc",)
+    assert r.required_missing == ()
+
+
+def test_directories_excluded_from_file_list():
+    """Directory entries should not appear in all_files."""
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w") as tf:
+        dir_info = tarfile.TarInfo(name="pkg")
+        dir_info.type = tarfile.DIRTYPE
+        tf.addfile(dir_info)
+        file_info = tarfile.TarInfo(name="pkg/a.py")
+        file_info.size = 1
+        tf.addfile(file_info, io.BytesIO(b"x"))
+    r = check_consistency(buf.getvalue())
+    assert r.all_files == ("pkg/a.py",)
+
+
+def test_extracts_from_file_path(tmp_path):
+    data = _build_tar([("a.txt", b"hello")])
+    p = tmp_path / "in.tar"
+    p.write_bytes(data)
+    r = check_consistency(str(p), expected={"a.txt"})
+    assert r.ok is True
+
+
+def test_missing_archive_path_raises(tmp_path):
+    with pytest.raises(ConsistencyError):
+        check_consistency(str(tmp_path / "nope.tar"))
+
+
+def test_archive_must_be_bytes_or_str():
+    with pytest.raises(ConsistencyError):
+        check_consistency(123)  # type: ignore[arg-type]
+
+
+def test_all_files_sorted():
+    data = _build_tar([("z.txt", b"z"), ("a.txt", b"a"), ("m.txt", b"m")])
+    r = check_consistency(data)
+    assert r.all_files == ("a.txt", "m.txt", "z.txt")
+
+
+def test_empty_expected_set_means_archive_must_be_empty():
+    """Passing an empty set as `expected` (vs None) is a real declaration."""
+    data = _build_tar([("a.txt", b"x")])
+    r = check_consistency(data, expected=set())
+    assert r.ok is False
+    assert r.extra == ("a.txt",)
+
+
+def test_empty_archive():
+    data = _build_tar([])
+    r = check_consistency(data, expected=set())
+    assert r.ok is True
+    assert r.all_files == ()

cartograph_cli-0.7.4/cg/infra_archive_manifest_consistency_python/widget.json

@@ -0,0 +1,31 @@
+{
+  "meta": {
+    "id": "infra-archive-manifest-consistency-python",
+    "name": "Archive Manifest Consistency",
+    "version": "1.0.0",
+    "domain": "infra",
+    "tags": [
+      "archive",
+      "manifest",
+      "consistency",
+      "supply-chain",
+      "verification"
+    ]
+  },
+  "description": "Verify a tarball's contents match a declared file manifest. Given a tarball and any combination of expected (full enumerated set), required (must-be-present subset), and forbidden (must-not-be-present) path declarations, returns a structured report listing missing files, extra files, required-but-missing, and forbidden-present. Path strings are compared literally so callers control normalization. Pure stdlib (tarfile).",
+  "tech_stack": {
+    "language": "python",
+    "dependencies": []
+  },
+  "custom_notes": "",
+  "library_notes": {
+    "general": "Single responsibility - one widget does one thing. No global state. No project-specific code, hardcoded paths, credentials, or environment-specific values. Expose variation points as constructor parameters or function arguments - no hardcoded thresholds, colors, sizes, or behavior flags. URLs and endpoints belong in examples as demonstration data, not in src/ - if a widget needs a URL to operate, it must be a parameter the caller provides. All dependencies must be declared in widget.json tech_stack.dependencies. Widgets cannot depend on other widgets - they must be fully self-contained. If you need logic from another widget, copy it into src/ directly. Examples must run and exit cleanly with no user input, no network calls, and no external services or API keys - use fake/hardcoded data. The widget's own declared dependencies are fine and will be installed by the validator before the example runs. Do not modify library_notes - it is managed by Cartograph and will be restored on checkin.",
+    "language": "No project-specific names, identifiers, or terminology anywhere in src/, tests/, or examples/ - use generic names like 'user', 'item', 'value', 'example_org'. A test that references your project's real entity names is contaminated. Use pytest for all tests - no unittest. Type hints required on all public functions. No __init__.py in tests/. No if __name__ == '__main__' blocks in src/ files. Imports ordered: stdlib, third-party, local. ML domain: framework-free (numpy, scikit-learn, plain Python) and API-based inference (HTTP calls to OpenAI, Anthropic, HuggingFace Inference API) work everywhere. Heavy optional frameworks must be pre-installed - Cartograph will not auto-install them. Declare dependencies in widget.json normally; consumers must also have them installed to validate.",
+    "domain": "Accept all paths and hostnames as parameters - never construct paths from hardcoded roots. Config keys, log formats, and health check endpoints must be configurable. Return structured status objects rather than printing; let the caller handle output. Side effects (file writes, process spawns) must be opt-in, not automatic."
+  },
+  "validation": {
+    "engine_version": 1,
+    "validated_at": "2026-05-07T02:23:11.212189+00:00",
+    "runtime": "python 3.14.4"
+  }
+}

cartograph_cli-0.7.4/cg/infra_file_stamp_python/.validation_stamp.json

@@ -0,0 +1 @@
+{"fingerprint": "bdbee4a0c3d45c3e71441189f39cd8b9abee33ae3612ec2b9fe728e39b4c8691", "stamped_at": "2026-06-04T21:33:30.432552+00:00", "language": "python", "engine_version": 1, "runtime": "python 3.14.5", "test_results": {}, "validated_at": "2026-06-04T21:33:30.432184+00:00"}

cartograph_cli-0.7.4/cg/infra_file_stamp_python/widget.json

@@ -0,0 +1,30 @@
+{
+  "meta": {
+    "id": "infra-file-stamp-python",
+    "name": "File Stamp",
+    "version": "1.0.2",
+    "domain": "infra",
+    "tags": [
+      "fingerprint",
+      "cache-invalidation",
+      "file-hash",
+      "change-detection",
+      "build-tools"
+    ]
+  },
+  "description": "Fingerprint-based change detection for file sets. Computes SHA-256 over watched files, writes a JSON stamp, and checks validity on subsequent runs. Useful for build cache invalidation, validation short-circuiting, and incremental processing pipelines.",
+  "tech_stack": {
+    "language": "python",
+    "dependencies": []
+  },
+  "library_notes": {
+    "general": "Single responsibility - one widget does one thing. No global state. No project-specific code, hardcoded paths, credentials, or environment-specific values. Expose variation points as constructor parameters or function arguments - no hardcoded thresholds, colors, sizes, or behavior flags. URLs and endpoints belong in examples as demonstration data, not in src/ - if a widget needs a URL to operate, it must be a parameter the caller provides. All dependencies must be declared in widget.json tech_stack.dependencies. Widgets cannot depend on other widgets - they must be fully self-contained. If you need logic from another widget, copy it into src/ directly. Examples must run and exit cleanly with no user input, no network calls, and no external services or API keys - use fake/hardcoded data. The widget's own declared dependencies are fine and will be installed by the validator before the example runs. Do not modify library_notes - it is managed by Cartograph and will be restored on checkin.",
+    "language": "No project-specific names, identifiers, or terminology anywhere in src/, tests/, or examples/ - use generic names like 'user', 'item', 'value', 'example_org'. A test that references your project's real entity names is contaminated. Use pytest for all tests - no unittest. Type hints required on all public functions. No __init__.py in tests/. No if __name__ == '__main__' blocks in src/ files. Imports ordered: stdlib, third-party, local. ML domain: framework-free (numpy, scikit-learn, plain Python) and API-based inference (HTTP calls to OpenAI, Anthropic, HuggingFace Inference API) work everywhere. Heavy optional frameworks must be pre-installed - Cartograph will not auto-install them. Declare dependencies in widget.json normally; consumers must also have them installed to validate.",
+    "domain": "Accept all paths and hostnames as parameters - never construct paths from hardcoded roots. Config keys, log formats, and health check endpoints must be configurable. Return structured status objects rather than printing; let the caller handle output. Side effects (file writes, process spawns) must be opt-in, not automatic."
+  },
+  "validation": {
+    "engine_version": 1,
+    "validated_at": "2026-06-04T21:33:38.758184+00:00",
+    "runtime": "python 3.14.5"
+  }
+}

cartograph_cli-0.7.4/cg/universal_block_walker_python/src/__init__.py

@@ -0,0 +1 @@
+# Package marker - add explicit exports here once the public API is stable.

cartograph_cli-0.7.4/cg/universal_ttl_disk_cache_python/.validation_stamp.json

@@ -0,0 +1 @@
+{"fingerprint": "66f9d8e1bf9b8bc1949f0423451beab19a8238e13c4c710f40a6d3ce14dbb55b", "stamped_at": "2026-06-04T21:18:41.001785+00:00", "language": "python", "engine_version": 1, "runtime": "python 3.14.5", "test_results": {}, "validated_at": "2026-06-04T21:18:41.001510+00:00"}

cartograph_cli-0.7.4/cg/universal_ttl_disk_cache_python/examples/example_usage.py

@@ -0,0 +1,54 @@
+"""Demonstrate the cache-around-a-callable pattern.
+
+A short-lived CLI wants to avoid paying for an expensive lookup on every
+invocation. Wrap the call in a get-then-set helper backed by ttl-disk-cache:
+first call computes and stores; subsequent calls within the TTL window
+short-circuit on the disk read.
+
+Runs offline with a faked-out 'expensive lookup'. Tear-down at the end
+keeps the example directory clean for re-runs.
+"""
+import os
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+from src.ttl_disk_cache import get, set, clear
+
+
+def expensive_lookup(user_id: str) -> dict:
+    """Stand-in for a slow network call. In real use this would be an
+    HTTP request, a database read, or anything else worth caching."""
+    return {"user_id": user_id, "tier": "gold", "lookups": 1}
+
+
+def cached_lookup(cache_root: str, user_id: str, ttl_seconds: float) -> dict:
+    hit = get(cache_root, user_id)
+    if hit is not None:
+        return hit
+    value = expensive_lookup(user_id)
+    set(cache_root, user_id, value, ttl_seconds)
+    return value
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory() as cache_root:
+        first = cached_lookup(cache_root, "ada", ttl_seconds=60)
+        print(f"first call (miss, computed): {first}")
+
+        second = cached_lookup(cache_root, "ada", ttl_seconds=60)
+        print(f"second call (hit, from disk): {second}")
+        assert first == second, "cache should return the stored value"
+
+        # Inspect what's on disk.
+        files = sorted(os.listdir(cache_root))
+        print(f"cache files on disk: {files}")
+
+        # Targeted invalidation — useful when underlying data changes.
+        clear(cache_root, "ada")
+        assert get(cache_root, "ada") is None
+        print("after clear: cache miss as expected")
+
+
+if __name__ == "__main__":
+    main()

cartograph_cli-0.7.4/cg/universal_ttl_disk_cache_python/src/__init__.py

@@ -0,0 +1 @@
+# Package marker - add explicit exports here once the public API is stable.