agentcache-core 0.9.9__py3-none-any.whl

agentcache/routes/_deps.py

@@ -0,0 +1,46 @@
+"""
+Shared service accessors for route blueprints.
+
+Route handlers call these to reach the process-wide singletons that
+``app.py:init_services`` populates on the Flask ``extensions`` dict.
+Kept here so no route file has to re-derive the "extensions → app-module
+globals → raise" fallback chain that used to live in six copies.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from flask import current_app
+
+
+def _from_extensions(name: str) -> Any:
+    ext = getattr(current_app, "extensions", {}) or {}
+    value = ext.get(name)
+    if value is not None:
+        return value
+
+    from .. import app as app_module
+
+    return getattr(app_module, name, None)
+
+
+def get_kv() -> Any:
+    """Return the process StateKV. Raises RuntimeError if uninitialised."""
+    kv = _from_extensions("kv")
+    if kv is None:
+        raise RuntimeError("StateKV is not initialized")
+    return kv
+
+
+def get_search_service() -> Any:
+    """Return the SearchService singleton (or None if search is disabled)."""
+    return _from_extensions("search_service")
+
+
+def get_observation_store() -> Any:
+    """Return the ObservationStore. Raises RuntimeError if uninitialised."""
+    store = _from_extensions("observation_store")
+    if store is None:
+        raise RuntimeError("ObservationStore is not initialized")
+    return store

agentcache/routes/auth.py

@@ -0,0 +1,68 @@
+"""
+Shared authentication utilities for all route blueprints.
+
+Public API
+----------
+verify_token(provided, secret) -> bool
+    Raw HMAC comparison. Used directly by the WebSocket handler in app.py.
+
+require_auth
+    Flask route decorator. Reads AGENTCACHE_SECRET / AGENTMEMORY_SECRET from
+    the environment, validates the Authorization: Bearer <token> header, and
+    aborts with 401 JSON if the check fails. Routes with no secret configured
+    are always allowed through.
+
+Usage in a blueprint
+--------------------
+    from .auth import require_auth
+
+    @bp.route("/agentcache/something", methods=["GET"])
+    @require_auth
+    def api_something():
+        ...
+"""
+
+import hmac
+import os
+from functools import wraps
+
+from flask import abort, jsonify, make_response, request
+
+
+def verify_token(provided: str, secret: str) -> bool:
+    """Return True if *provided* matches *secret* via constant-time comparison."""
+    return hmac.compare_digest(
+        provided.encode("utf-8"),
+        secret.encode("utf-8"),
+    )
+
+
+def require_auth(f):
+    """Decorator that enforces Bearer-token authentication on a Flask route.
+
+    If no secret is configured the request is passed through unchanged —
+    consistent with the previous per-blueprint behaviour.
+    """
+
+    @wraps(f)
+    def _wrapped(*args, **kwargs):
+        secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
+        if not secret:
+            # No secret configured → open access (matches legacy behaviour).
+            return f(*args, **kwargs)
+
+        auth_header = request.headers.get("Authorization") or request.headers.get(
+            "authorization"
+        )
+        if not auth_header or not auth_header.startswith("Bearer "):
+            resp = make_response(jsonify({"error": "unauthorized"}), 401)
+            abort(resp)
+
+        provided_token = auth_header[7:].strip()
+        if not verify_token(provided_token, secret):
+            resp = make_response(jsonify({"error": "unauthorized"}), 401)
+            abort(resp)
+
+        return f(*args, **kwargs)
+
+    return _wrapped

agentcache/routes/graph.py

@@ -0,0 +1,81 @@
+"""
+Graph routes blueprint.
+
+Handles:
+  GET  /agentmemory/graph
+  GET  /agentmemory/graph/stats
+  POST /agentmemory/graph/query
+  POST /agentmemory/graph/build
+"""
+
+from flask import Blueprint, jsonify, request
+
+from .. import legacy as functions
+from ._deps import get_kv
+from .auth import require_auth
+
+
+def create_graph_bp(kv=None):
+    """Blueprint factory — receives kv at registration time (falls back to get_kv())."""
+    bp = Blueprint("graph", __name__)
+
+    def _kv():
+        return kv if kv is not None else get_kv()
+
+    # ------------------------------------------------------------------
+    # GET /agentcache/graph
+    # ------------------------------------------------------------------
+
+    @bp.route("/agentcache/graph", methods=["GET"])
+    @bp.route("/agentmemory/graph", methods=["GET"])
+    @require_auth
+    def api_graph():
+        result = functions.folder_graph_build(_kv())
+        return jsonify(result), 200
+
+    # ------------------------------------------------------------------
+    # GET /agentcache/graph/stats
+    # ------------------------------------------------------------------
+
+    @bp.route("/agentcache/graph/stats", methods=["GET"])
+    @bp.route("/agentmemory/graph/stats", methods=["GET"])
+    @require_auth
+    def api_graph_stats():
+        g = functions.folder_graph_build(_kv())
+        node_count = len(g.get("nodes", []))
+        edge_count = len(g.get("edges", []))
+        return jsonify({"nodes": node_count, "edges": edge_count, "success": True}), 200
+
+    # ------------------------------------------------------------------
+    # POST /agentcache/graph/query
+    # ------------------------------------------------------------------
+
+    @bp.route("/agentcache/graph/query", methods=["POST"])
+    @bp.route("/agentmemory/graph/query", methods=["POST"])
+    @require_auth
+    def api_graph_query():
+        try:
+            request.get_json(force=True) or {}
+            return jsonify({"nodes": [], "edges": [], "success": True}), 200
+        except Exception as e:
+            return jsonify({"error": str(e)}), 400
+
+    # ------------------------------------------------------------------
+    # POST /agentcache/graph/build
+    # ------------------------------------------------------------------
+
+    @bp.route("/agentcache/graph/build", methods=["POST"])
+    @bp.route("/agentmemory/graph/build", methods=["POST"])
+    @require_auth
+    def api_graph_build():
+        try:
+            if functions.is_consolidation_enabled():
+                functions.consolidate(_kv())
+            return jsonify({"success": True}), 200
+        except Exception as e:
+            return jsonify({"error": str(e)}), 400
+
+    return bp
+
+
+graph_bp = create_graph_bp(None)

agentcache/routes/health.py

@@ -0,0 +1,149 @@
+"""
+Health and audit routes blueprint.
+
+Handles:
+  GET /agentmemory/livez
+  GET /agentmemory/health
+  GET /agentmemory/audit
+  GET /agentmemory/config/flags
+"""
+
+import os
+
+from flask import Blueprint, Response, jsonify, request
+
+from .. import legacy as functions
+from ..legacy import query_audit
+from ._deps import get_kv
+from .auth import require_auth
+
+
+def create_health_bp(kv=None, embedding_provider=None):
+    """Blueprint factory — receives kv and embedding_provider at registration time."""
+    bp = Blueprint("health", __name__)
+
+    def _kv():
+        return kv if kv is not None else get_kv()
+
+    # ------------------------------------------------------------------
+    # GET /auth.md  (no auth required)
+    # ------------------------------------------------------------------
+
+    @bp.route("/auth.md", methods=["GET"])
+    def auth_docs():
+        """Serve the agent onboarding documentation in Markdown format."""
+        base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        auth_md_path = os.path.join(base_dir, "auth.md")
+
+        if os.path.exists(auth_md_path):
+            try:
+                with open(auth_md_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                return Response(
+                    content,
+                    mimetype="text/markdown",
+                    headers={"Content-Type": "text/markdown; charset=utf-8"},
+                )
+            except Exception as e:
+                return jsonify({"error": f"failed to read auth.md: {e}"}), 500
+
+        return jsonify({"error": "auth.md not found"}), 404
+
+    # ------------------------------------------------------------------
+    # GET /agentcache/livez  (no auth required)
+    # ------------------------------------------------------------------
+
+    @bp.route("/agentcache/livez", methods=["GET"])
+    @bp.route("/agentmemory/livez", methods=["GET"])
+    def livez():
+        port = int(os.getenv("III_REST_PORT", os.getenv("PORT", "3111")))
+        return jsonify(
+            {
+                "status": "ok",
+                "service": "agentcache",
+                "viewerPort": port,
+                "viewerSkipped": False,
+            }
+        )
+
+    # ------------------------------------------------------------------
+    # GET /agentcache/health
+    # ------------------------------------------------------------------
+
+    @bp.route("/agentcache/health", methods=["GET"])
+    @bp.route("/agentmemory/health", methods=["GET"])
+    def health():
+        return jsonify(functions.health_check(_kv()))
+
+    # ------------------------------------------------------------------
+    # GET /agentcache/audit
+    # ------------------------------------------------------------------
+
+    @bp.route("/agentcache/audit", methods=["GET"])
+    @bp.route("/agentmemory/audit", methods=["GET"])
+    @require_auth
+    def api_audit():
+        op = request.args.get("operation")
+        limit = int(request.args.get("limit", "50"))
+        res = query_audit(_kv(), {"operation": op, "limit": limit})
+        return jsonify({"entries": res, "success": True}), 200
+
+    # ------------------------------------------------------------------
+    # GET /agentcache/config/flags
+    # ------------------------------------------------------------------
+
+    @bp.route("/agentcache/config/flags", methods=["GET"])
+    @bp.route("/agentmemory/config/flags", methods=["GET"])
+    @require_auth
+    def config_flags():
+        provider_kind = "llm" if embedding_provider else "noop"
+        embedding_prov = "gemini" if embedding_provider else "none"
+
+        flags = [
+            {
+                "key": "GRAPH_EXTRACTION_ENABLED",
+                "label": "Knowledge graph extraction",
+                "enabled": functions.is_graph_extraction_enabled(),
+                "default": False,
+                "affects": ["Graph", "Dashboard"],
+                "needsLlm": True,
+                "description": "Extracts entities and relations from observations into a knowledge graph.",
+                "enableHow": "Set GRAPH_EXTRACTION_ENABLED=true and restart.",
+                "docsHref": "https://github.com/rohitg00/agentmemory#knowledge-graph",
+            },
+            {
+                "key": "CONSOLIDATION_ENABLED",
+                "label": "Memory consolidation",
+                "enabled": functions.is_consolidation_enabled(),
+                "default": False,
+                "affects": ["Dashboard", "Memories", "Crystals"],
+                "needsLlm": True,
+                "description": "Periodically summarizes sessions into semantic facts + procedures.",
+                "enableHow": "Set CONSOLIDATION_ENABLED=true and restart.",
+                "docsHref": "https://github.com/rohitg00/agentmemory#consolidation",
+            },
+            {
+                "key": "AGENTCACHE_AUTO_COMPRESS",
+                "label": "LLM-powered observation compression",
+                "enabled": functions.is_auto_compress_enabled(),
+                "default": False,
+                "affects": ["Memories", "Timeline"],
+                "needsLlm": True,
+                "description": "Every observation is compressed by the LLM for richer summaries. OFF uses synthetic compression.",
+                "enableHow": "Set AGENTCACHE_AUTO_COMPRESS=true.",
+                "docsHref": "https://github.com/rohitg00/agentmemory/issues/138",
+            },
+        ]
+        return jsonify(
+            {
+                "version": "0.9.9",
+                "provider": provider_kind,
+                "embeddingProvider": embedding_prov,
+                "flags": flags,
+            }
+        )
+
+    return bp
+
+
+health_bp = create_health_bp(None)