agentcache-core 0.9.9__py3-none-any.whl

agentcache/core/__init__.py

@@ -0,0 +1,19 @@
+"""
+agentcache.core — deep, injectable modules for the agentcache system.
+
+Modules:
+  kv_scopes      — KV scope key registry (shared by all stores and routes)
+  search_service — SearchService (BM25 + vector indexing and querying)
+"""
+
+from .kv_scopes import KV
+from .observation_store import ObservationEvents, ObservationStore
+from .search_service import IndexPersistence, SearchService
+
+__all__ = [
+    "KV",
+    "SearchService",
+    "IndexPersistence",
+    "ObservationStore",
+    "ObservationEvents",
+]

agentcache/core/audit_log.py

@@ -0,0 +1,104 @@
+"""Audit log — record, query, and safe-fire audit entries."""
+
+import datetime
+from typing import Any, Dict, List, Optional
+
+from ..db import StateKV
+from ..storage.paths import generate_id
+from .kv_scopes import KV
+
+
+def record_audit(
+    kv: StateKV,
+    operation: str,
+    function_id: str,
+    target_ids: List[str],
+    details: Dict[str, Any] = {},
+    quality_score: Optional[float] = None,
+    user_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    entry = {
+        "id": generate_id("aud"),
+        "timestamp": datetime.datetime.now(datetime.timezone.utc)
+        .isoformat()
+        .replace("+00:00", "Z"),
+        "operation": operation,
+        "userId": user_id,
+        "functionId": function_id,
+        "targetIds": target_ids,
+        "details": details,
+        "qualityScore": quality_score,
+    }
+    kv.set(KV.audit, entry["id"], entry)
+    return entry
+
+
+def safe_audit(
+    kv: StateKV,
+    operation: str,
+    function_id: str,
+    target_ids: List[str],
+    details: Dict[str, Any] = {},
+    quality_score: Optional[float] = None,
+    user_id: Optional[str] = None,
+) -> None:
+    try:
+        record_audit(
+            kv, operation, function_id, target_ids, details, quality_score, user_id
+        )
+    except Exception as e:
+        print(f"[audit] Failed to write audit: {e}")
+
+
+def query_audit(
+    kv: StateKV, filter_opts: Optional[Dict[str, Any]] = None
+) -> List[Dict[str, Any]]:
+    all_entries = kv.list(KV.audit)
+    entries = sorted(all_entries, key=lambda x: x.get("timestamp", ""), reverse=True)
+    if not filter_opts:
+        return entries[:100]
+
+    op = filter_opts.get("operation")
+    if op:
+        entries = [e for e in entries if e.get("operation") == op]
+
+    import dateutil.parser
+
+    date_from = filter_opts.get("dateFrom")
+    if date_from:
+        try:
+            dt_from = dateutil.parser.parse(date_from).replace(tzinfo=None)
+            filtered_entries = []
+            for e in entries:
+                ts = e.get("timestamp")
+                if ts:
+                    try:
+                        dt_ts = dateutil.parser.parse(ts).replace(tzinfo=None)
+                        if dt_ts >= dt_from:
+                            filtered_entries.append(e)
+                    except Exception:
+                        pass
+            entries = filtered_entries
+        except Exception:
+            pass
+
+    date_to = filter_opts.get("dateTo")
+    if date_to:
+        try:
+            dt_to = dateutil.parser.parse(date_to).replace(tzinfo=None)
+            filtered_entries = []
+            for e in entries:
+                ts = e.get("timestamp")
+                if ts:
+                    try:
+                        dt_ts = dateutil.parser.parse(ts).replace(tzinfo=None)
+                        if dt_ts <= dt_to:
+                            filtered_entries.append(e)
+                    except Exception:
+                        pass
+            entries = filtered_entries
+        except Exception:
+            pass
+
+    limit = filter_opts.get("limit", 100)
+    return entries[:limit]

agentcache/core/config.py

@@ -0,0 +1,51 @@
+"""Agent configuration helpers — env-var readers and Dolt commit helper."""
+
+import os
+from typing import Optional
+
+from ..db import StateKV
+
+
+def get_agent_id() -> Optional[str]:
+    return os.getenv("AGENT_ID") or None
+
+
+def commit_if_enabled(
+    kv: StateKV, message: str, agent_id: Optional[str]
+) -> Optional[str]:
+    return kv.commit_version(message, agent_id or "unknown-agent")
+
+
+def is_agent_scope_isolated() -> bool:
+    return (
+        os.getenv("AGENTCACHE_AGENT_SCOPE") or os.getenv("AGENTMEMORY_AGENT_SCOPE")
+    ) == "isolated"
+
+
+def is_auto_compress_enabled() -> bool:
+    return (
+        os.getenv("AGENTCACHE_AUTO_COMPRESS") or os.getenv("AGENTMEMORY_AUTO_COMPRESS")
+    ) == "true"
+
+
+def is_slots_enabled() -> bool:
+    return (os.getenv("AGENTCACHE_SLOTS") or os.getenv("AGENTMEMORY_SLOTS")) == "true"
+
+
+def is_reflect_enabled() -> bool:
+    return (
+        os.getenv("AGENTCACHE_REFLECT") or os.getenv("AGENTMEMORY_REFLECT")
+    ) == "true"
+
+
+def is_graph_extraction_enabled() -> bool:
+    return os.getenv("GRAPH_EXTRACTION_ENABLED") == "true"
+
+
+def is_consolidation_enabled() -> bool:
+    val = os.getenv("CONSOLIDATION_ENABLED")
+    if val in ("false", "0"):
+        return False
+    if val in ("true", "1"):
+        return True
+    return bool(os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY"))

agentcache/core/context_builder.py

@@ -0,0 +1,209 @@
+"""Prompt context compilation — assembles memory blocks into XML context string."""
+
+import os
+import re
+import time
+from typing import Any, Dict, List, Optional
+
+from ..db import StateKV
+from .kv_scopes import KV
+from .slots import list_pinned_slots, render_pinned_context
+
+
+def estimate_tokens(text: str) -> int:
+    return int(len(text) / 3)
+
+
+def escape_xml_attr(s: str) -> str:
+    return (
+        s.replace("&", "&")
+        .replace('"', """)
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+    )
+
+
+def strip_xml_wrappers(raw: str) -> str:
+    if not raw:
+        return ""
+    cleaned = raw.strip()
+    cleaned = re.sub(r"```xml\s*\n?", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"```", "", cleaned)
+    cleaned = cleaned.strip()
+    root_match = re.search(
+        r"(<[a-zA-Z_][a-zA-Z0-9_-]*>[\s\S]*<\/[a-zA-Z_][a-zA-Z0-9_-]*>)", cleaned
+    )
+    if root_match:
+        return root_match.group(1).strip()
+    return cleaned
+
+
+def get_xml_tag(text: str, tag: str) -> Optional[str]:
+    cleaned = strip_xml_wrappers(text)
+    pattern = rf"<{tag}>(.*?)</{tag}>"
+    match = re.search(pattern, cleaned, re.DOTALL)
+    return match.group(1).strip() if match else None
+
+
+def get_xml_children(text: str, parent_tag: str, child_tag: str) -> List[str]:
+    parent_content = get_xml_tag(text, parent_tag)
+    if not parent_content:
+        return []
+    pattern = rf"<{child_tag}>(.*?)</{child_tag}>"
+    return [m.strip() for m in re.findall(pattern, parent_content, re.DOTALL)]
+
+
+def context(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
+    session_id = data.get("sessionId")
+    project = data.get("project")
+    budget = data.get("budget") or int(os.getenv("TOKEN_BUDGET", "2000"))
+
+    if not session_id or not project:
+        raise ValueError("sessionId and project are required")
+
+    blocks = []
+
+    # 1. Pinned Slots
+    pinned_slots = list_pinned_slots(kv, project)
+    slot_content = render_pinned_context(pinned_slots)
+    if slot_content:
+        blocks.append(
+            {
+                "type": "memory",
+                "content": slot_content,
+                "tokens": estimate_tokens(slot_content),
+                "recency": int(time.time() * 1000),
+            }
+        )
+
+    # 2. Profile
+    profile = kv.get(KV.profiles, project)
+    if profile:
+        profile_parts = []
+        if profile.get("topConcepts"):
+            profile_parts.append(
+                "Concepts: "
+                + ", ".join([c["concept"] for c in profile["topConcepts"][:8]])
+            )
+        if profile.get("topFiles"):
+            profile_parts.append(
+                "Key files: " + ", ".join([f["file"] for f in profile["topFiles"][:5]])
+            )
+        if profile.get("conventions"):
+            profile_parts.append("Conventions: " + "; ".join(profile["conventions"]))
+        if profile.get("commonErrors"):
+            profile_parts.append(
+                "Common errors: " + "; ".join(profile["commonErrors"][:3])
+            )
+
+        if profile_parts:
+            profile_content = "## Project Profile\n" + "\n".join(profile_parts)
+            blocks.append(
+                {
+                    "type": "memory",
+                    "content": profile_content,
+                    "tokens": estimate_tokens(profile_content),
+                    "recency": int(time.time() * 1000),
+                }
+            )
+
+    # 3. Lessons
+    lessons = kv.list(KV.lessons)
+    relevant_lessons = [
+        les
+        for les in lessons
+        if not les.get("deleted")
+        and (not les.get("project") or les["project"] == project)
+    ]
+
+    def lesson_score(les):
+        factor = 1.5 if les.get("project") == project else 1.0
+        return factor * les.get("confidence", 0.5)
+
+    relevant_lessons.sort(key=lesson_score, reverse=True)
+    relevant_lessons = relevant_lessons[:10]
+
+    if relevant_lessons:
+        items = []
+        for les in relevant_lessons:
+            desc = f"- ({les['confidence']:.2f}) {les['content']}"
+            if les.get("context"):
+                desc += f" — {les['context']}"
+            items.append(desc)
+        lessons_content = "## Lessons Learned\n" + "\n".join(items)
+        blocks.append(
+            {
+                "type": "memory",
+                "content": lessons_content,
+                "tokens": estimate_tokens(lessons_content),
+                "recency": int(time.time() * 1000),
+            }
+        )
+
+    # 4. Sessions & Summaries
+    all_sessions = kv.list(KV.sessions)
+    sessions = [
+        s for s in all_sessions if s.get("project") == project and s["id"] != session_id
+    ]
+    sessions.sort(key=lambda s: s.get("startedAt", ""), reverse=True)
+    sessions = sessions[:10]
+
+    for s in sessions:
+        summary = kv.get(KV.summaries, s["id"])
+        if summary:
+            content = (
+                f"## {summary.get('title', 'Session summary')}\n{summary.get('narrative', '')}\n"
+                f"Decisions: {'; '.join(summary.get('keyDecisions', []))}\n"
+                f"Files: {', '.join(summary.get('filesModified', []))}"
+            )
+            blocks.append(
+                {
+                    "type": "summary",
+                    "content": content,
+                    "tokens": estimate_tokens(content),
+                    "recency": int(time.time() * 1000),
+                }
+            )
+        else:
+            obs_list = kv.list(KV.observations(s["id"]))
+            important = [
+                o for o in obs_list if o.get("title") and o.get("importance", 0) >= 5
+            ]
+            if important:
+                important.sort(key=lambda o: o.get("importance", 0), reverse=True)
+                top = important[:5]
+                items = [
+                    f"- [{o.get('type')}] {o.get('title')}: {o.get('narrative')}"
+                    for o in top
+                ]
+                content = (
+                    f"## Session {s['id'][:8]} ({s.get('startedAt')})\n"
+                    + "\n".join(items)
+                )
+                blocks.append(
+                    {
+                        "type": "observation",
+                        "content": content,
+                        "tokens": estimate_tokens(content),
+                        "recency": int(time.time() * 1000),
+                    }
+                )
+
+    blocks.sort(key=lambda b: b.get("recency", 0), reverse=True)
+
+    header = f'<agentcache-context project="{escape_xml_attr(project)}">'
+    footer = "</agentcache-context>"
+    used_tokens = estimate_tokens(header) + estimate_tokens(footer)
+
+    selected = []
+    for b in blocks:
+        if used_tokens + b["tokens"] > budget:
+            continue
+        selected.append(b["content"])
+        used_tokens += b["tokens"]
+
+    if not selected:
+        return {"context": "", "blocks": 0, "tokens": 0}
+
+    res_context = f"{header}\n" + "\n\n".join(selected) + f"\n{footer}"
+    return {"context": res_context, "blocks": len(selected), "tokens": used_tokens}

agentcache/core/graph.py

@@ -0,0 +1,120 @@
+"""Folder graph builder for the viewer's Graph tab."""
+
+import os
+from typing import Any, Dict, List, Set, Tuple
+
+from ..db import StateKV
+from .config import get_agent_id, is_agent_scope_isolated
+from .kv_scopes import KV
+
+
+def folder_color(path: str) -> str:
+    """Hash a folder path string to an HSL color string.
+
+    Replicates the JS ``folderColor(id)`` function in src/viewer/index.html
+    exactly, using the light-mode lightness range (38 + h%14).
+    """
+    h = 0
+    for ch in path:
+        h = (h * 31 + ord(ch)) & 0xFFFFFFF
+
+    hue = (h % 360 + 360) % 360
+    sat_pct = 55 + (h % 25)
+    lig_pct = 38 + (h % 14)
+
+    return f"hsl({hue}, {sat_pct}%, {lig_pct}%)"
+
+
+def folder_graph_build(kv: StateKV) -> Dict[str, Any]:
+    """Build graph data for the viewer's Graph tab."""
+    index_entries = kv.list(KV.folders)
+    if is_agent_scope_isolated():
+        aid = get_agent_id()
+        if aid:
+            index_entries = [e for e in index_entries if e.get("agentId") == aid]
+
+    folder_map: Dict[str, Dict[str, Any]] = {}
+    pair_obs_texts: Dict[Tuple[str, str], str] = {}
+
+    for entry in index_entries:
+        fp = entry.get("folderPath", "")
+        aid = entry.get("agentId", "")
+        if not fp:
+            continue
+
+        if fp not in folder_map:
+            folder_map[fp] = {
+                "folderPath": fp,
+                "agentIds": set(),
+                "obsCount": 0,
+                "color": folder_color(fp),
+            }
+
+        folder_map[fp]["agentIds"].add(aid)
+        folder_map[fp]["obsCount"] += entry.get("obsCount", 0)
+
+        obs_scope = KV.folder_obs(fp, aid)
+        obs_list = kv.list(obs_scope)
+        combined_parts = []
+        for obs in obs_list:
+            text = obs.get("text") or ""
+            title = obs.get("title") or ""
+            combined_parts.append(f"{text} {title}")
+        pair_obs_texts[(fp, aid)] = " ".join(combined_parts)
+
+    nodes = []
+    for fp, info in folder_map.items():
+        nodes.append(
+            {
+                "id": fp,
+                "label": os.path.basename(fp) or fp,
+                "folderPath": fp,
+                "agentIds": sorted(info["agentIds"]),
+                "obsCount": info["obsCount"],
+                "color": info["color"],
+            }
+        )
+
+    edges: List[Dict[str, Any]] = []
+    seen_edges: Set[Tuple[Any, str]] = set()
+
+    def add_edge(edge: Dict[str, Any]) -> None:
+        key = (frozenset([edge["source"], edge["target"]]), edge["type"])
+        if key not in seen_edges:
+            seen_edges.add(key)
+            edges.append(edge)
+
+    folder_paths = list(folder_map.keys())
+
+    for i in range(len(folder_paths)):
+        for j in range(i + 1, len(folder_paths)):
+            a = folder_paths[i]
+            b = folder_paths[j]
+            if a.rsplit("/", 1)[0] == b.rsplit("/", 1)[0] and "/" in a and "/" in b:
+                add_edge({"source": a, "target": b, "type": "same-parent"})
+            elif os.path.dirname(a) == os.path.dirname(b) and os.path.dirname(a) != "":
+                add_edge({"source": a, "target": b, "type": "same-parent"})
+
+    for (fp_a, _agent_a), text_a in pair_obs_texts.items():
+        for fp_b in folder_paths:
+            if fp_b != fp_a and fp_b in text_a:
+                add_edge({"source": fp_a, "target": fp_b, "type": "cross-ref"})
+
+    agent_to_folders: Dict[str, List[str]] = {}
+    for fp, info in folder_map.items():
+        for aid in info["agentIds"]:
+            agent_to_folders.setdefault(aid, []).append(fp)
+
+    for aid, fps in agent_to_folders.items():
+        for i in range(len(fps)):
+            for j in range(i + 1, len(fps)):
+                add_edge(
+                    {
+                        "source": fps[i],
+                        "target": fps[j],
+                        "type": "agent-shared",
+                        "agentId": aid,
+                    }
+                )
+
+    return {"nodes": nodes, "edges": edges}

agentcache/core/image_store.py

@@ -0,0 +1,111 @@
+"""Image storage helpers — disk persistence and extraction from payloads."""
+
+import hashlib
+import os
+from typing import Any, Optional, Tuple
+
+IMAGES_DIR = os.path.join(os.path.expanduser("~"), ".agentcache", "images")
+
+
+def get_max_bytes() -> int:
+    return int(
+        os.getenv("AGENTCACHE_IMAGE_STORE_MAX_BYTES")
+        or os.getenv("AGENTMEMORY_IMAGE_STORE_MAX_BYTES")
+        or 500 * 1024 * 1024
+    )
+
+
+def is_managed_image_path(file_path: str) -> bool:
+    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]:
+    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:
+    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"[agentcache] Failed to delete image context: {e}")
+    return 0
+
+
+def touch_image(file_path: str) -> None:
+    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
+
+
+def extract_image(d: Any) -> Optional[str]:
+    if not d:
+        return None
+    if isinstance(d, str):
+        if (
+            d.startswith("data:image/")
+            or d.startswith("iVBORw0KGgo")
+            or d.startswith("/9j/")
+        ):
+            return d
+        return None
+    if isinstance(d, dict):
+        for k in ["image_data", "image_path", "imageBase64", "imagePath"]:
+            if isinstance(d.get(k), str):
+                return d[k]
+        for key, val in d.items():
+            match = extract_image(val)
+            if match:
+                return match
+    return None