agentcache-core 0.9.9__py3-none-any.whl

agentcache/storage/__init__.py

@@ -0,0 +1,29 @@
+"""
+src/storage/ — Storage utilities package for agentmemory-python (A2.3).
+
+Sub-modules:
+  scopes  — KV scope registry (class KV with all scope definitions)
+  paths   — Path/ID utility functions (normalize_folder_path, validate_agent_id,
+             generate_id, fingerprint_id)
+  images  — Image-on-disk helpers (save_image_to_disk, delete_image, touch_image,
+             is_managed_image_path)
+
+These are compatibility copies — the originals in functions.py are kept intact
+for backward compatibility.
+"""
+
+from .images import delete_image, is_managed_image_path, save_image_to_disk, touch_image
+from .paths import fingerprint_id, generate_id, normalize_folder_path, validate_agent_id
+from .scopes import KV
+
+__all__ = [
+    "KV",
+    "normalize_folder_path",
+    "validate_agent_id",
+    "generate_id",
+    "fingerprint_id",
+    "save_image_to_disk",
+    "delete_image",
+    "touch_image",
+    "is_managed_image_path",
+]

agentcache/storage/images.py

@@ -0,0 +1,102 @@
+"""
+src/storage/images.py — Image-on-disk storage helpers (A2.3).
+
+Copied from src/functions.py — do NOT delete the originals (backward compat).
+"""
+
+import hashlib
+import os
+from typing import Optional, Tuple
+
+IMAGES_DIR = os.path.join(os.path.expanduser("~"), ".agentmemory", "images")
+
+
+def get_max_bytes() -> int:
+    """Return the configured image-store byte limit (default 500 MB)."""
+    return int(os.getenv("AGENTMEMORY_IMAGE_STORE_MAX_BYTES", 500 * 1024 * 1024))
+
+
+def is_managed_image_path(file_path: str) -> bool:
+    """Return True iff *file_path* lives inside the managed images directory."""
+    if not file_path:
+        return False
+    resolved = os.path.abspath(file_path)
+    normalized_images_dir = os.path.abspath(IMAGES_DIR)
+    return (
+        resolved.startswith(normalized_images_dir + os.sep)
+        or resolved == normalized_images_dir
+    )
+
+
+def save_image_to_disk(base64_data: str) -> Tuple[str, int]:
+    """Decode *base64_data* and write to the managed images directory.
+
+    Returns:
+        (file_path, bytes_written) — bytes_written is 0 if the file already
+        existed (content-addressable dedup via SHA-256).
+    """
+    if not base64_data:
+        return "", 0
+
+    if not os.path.exists(IMAGES_DIR):
+        os.makedirs(IMAGES_DIR, exist_ok=True)
+
+    clean_base64 = base64_data
+    ext = "png"
+
+    if base64_data.startswith("data:image/"):
+        comma_idx = base64_data.find(",")
+        if comma_idx != -1:
+            meta = base64_data[:comma_idx]
+            if "jpeg" in meta or "jpg" in meta:
+                ext = "jpg"
+            elif "webp" in meta:
+                ext = "webp"
+            elif "gif" in meta:
+                ext = "gif"
+            clean_base64 = base64_data[comma_idx + 1 :]
+    elif base64_data.startswith("/9j/"):
+        ext = "jpg"
+
+    h = hashlib.sha256(clean_base64.encode("utf-8")).hexdigest()
+    file_path = os.path.join(IMAGES_DIR, f"{h}.{ext}")
+
+    if os.path.exists(file_path):
+        return file_path, 0
+
+    import base64
+
+    buffer = base64.b64decode(clean_base64)
+    with open(file_path, "wb") as f:
+        f.write(buffer)
+
+    size = os.path.getsize(file_path)
+    return file_path, size
+
+
+def delete_image(file_path: Optional[str]) -> int:
+    """Delete a managed image file and return the number of bytes freed.
+
+    Returns 0 if the path is not managed or does not exist.
+    """
+    if not file_path or not is_managed_image_path(file_path):
+        return 0
+    try:
+        if os.path.exists(file_path):
+            size = os.path.getsize(file_path)
+            os.remove(file_path)
+            return size
+    except Exception as e:
+        print(f"[agentmemory] Failed to delete image context: {e}")
+    return 0
+
+
+def touch_image(file_path: str) -> None:
+    """Update the mtime of a managed image (keeps it alive past LRU eviction)."""
+    if not file_path or not is_managed_image_path(file_path):
+        return
+    try:
+        if os.path.exists(file_path):
+            os.utime(file_path, None)
+    except Exception:
+        pass

agentcache/storage/paths.py

@@ -0,0 +1,116 @@
+"""
+src/storage/paths.py — Path normalisation and ID utilities (A2.3).
+
+Copied from src/functions.py — do NOT delete the originals (backward compat).
+"""
+
+import hashlib
+import os
+import time
+import uuid
+
+# Maximum allowed length for folder paths and agent IDs.
+_MAX_PATH_LEN = 512
+
+
+def generate_id(prefix: str) -> str:
+    """Generate a time-sortable unique ID with a human-readable prefix.
+
+    Format: ``{prefix}_{base36_timestamp}_{12_hex_chars}``
+    """
+    t = int(time.time() * 1000)
+    chars = "0123456789abcdefghijklmnopqrstuvwxyz"
+    ts_str = ""
+    while t > 0:
+        ts_str = chars[t % 36] + ts_str
+        t //= 36
+    if not ts_str:
+        ts_str = "0"
+    rand = uuid.uuid4().hex[:12]
+    return f"{prefix}_{ts_str}_{rand}"
+
+
+def fingerprint_id(prefix: str, content: str) -> str:
+    """Generate a deterministic ID by SHA-256 fingerprinting *content*.
+
+    Format: ``{prefix}_{first_16_hex_chars_of_sha256}``
+    """
+    h = hashlib.sha256(content.strip().lower().encode("utf-8")).hexdigest()
+    return f"{prefix}_{h[:16]}"
+
+
+def normalize_folder_path(path: str) -> str:
+    """Normalize a folder path for safe use in KV scope keys.
+
+    Steps applied in order:
+    1. Cap the raw input at 512 characters (REQ-066).
+    2. Apply ``os.path.normpath`` to collapse redundant separators and
+       resolve any ``..`` components at the OS level.
+    3. Convert all OS-native separators to forward slashes.
+    4. Strip any remaining leading or trailing slashes.
+
+    Raises:
+        ValueError: if *path* is empty (before or after normalization), or
+                    if the normalized result still contains a ``..`` segment,
+                    which would indicate an attempt at path traversal
+                    (REQ-064).
+
+    Returns:
+        A non-empty, forward-slash-separated string with no leading/trailing
+        slashes and no ``..`` segments — safe for use as a KV scope fragment.
+
+    Property (REQ-074): idempotent — applying this function twice yields
+    the same result as applying it once.
+    """
+    if not path:
+        raise ValueError("folder_path must not be empty")
+
+    # 1. Length cap before any processing.
+    path = path[:_MAX_PATH_LEN]
+
+    # Pre-normalisation traversal check: reject any path that contains a ".."
+    # component in the raw input before normpath has a chance to resolve it.
+    raw_parts = path.replace("\\", "/").split("/")
+    if any(part == ".." for part in raw_parts):
+        raise ValueError(f"folder_path contains path traversal segment '..': {path!r}")
+
+    # 2. OS-level normalisation (resolves duplicate separators, etc.)
+    normalized = os.path.normpath(path)
+
+    # 3. Unify separators to forward slash.
+    normalized = normalized.replace("\\", "/")
+
+    # 4. Strip leading / trailing slashes.
+    normalized = normalized.strip("/")
+
+    # Guard: also reject any ".." that somehow survives normalisation.
+    parts = normalized.split("/")
+    if any(part == ".." for part in parts):
+        raise ValueError(f"folder_path contains path traversal segment '..': {path!r}")
+
+    if not normalized:
+        raise ValueError("folder_path is empty after normalization")
+
+    return normalized
+
+
+def validate_agent_id(agent_id: str) -> str:
+    """Validate and sanitize an agent_id before use in KV scope keys.
+
+    Strips surrounding whitespace and caps at 512 characters (REQ-066).
+
+    Raises:
+        ValueError: if *agent_id* is empty after stripping.
+
+    Returns:
+        Sanitized agent_id string.
+    """
+    if not agent_id:
+        raise ValueError("agent_id must not be empty")
+
+    sanitized = agent_id.strip()[:_MAX_PATH_LEN]
+
+    if not sanitized:
+        raise ValueError("agent_id is empty after stripping whitespace")
+
+    return sanitized

agentcache/storage/scopes.py

@@ -0,0 +1,9 @@
+"""
+src/storage/scopes.py — KV scope registry (A2.3).
+
+Re-exports KV from core.kv_scopes for backward compatibility.
+"""
+
+from ..core.kv_scopes import KV
+
+__all__ = ["KV"]

agentcache/viewer/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="10" fill="#111111"/><text x="32" y="41" text-anchor="middle" font-family="Arial,sans-serif" font-size="24" font-weight="700" fill="#2D6A4F">AM</text></svg>