concierge-graph 3.8.2__py3-none-any.whl

interface/__init__.py

@@ -0,0 +1,16 @@
+"""
+interface/ - External Interface of Grafo Concierge v3.8.0
+
+Modules:
+    mcp_server.py    -> FastMCP server with 7 tools (mine, search, commit, wakeup, resume, load, status)
+    action_hooks.py  -> Reactive lifecycle triggers (on_planning, on_execution, on_done)
+    cli.py           -> Terminal interface (argparse) with 9 commands
+"""
+
+from interface.mcp_server import GrafoConciergeServer
+from interface.action_hooks import ActionHooks
+
+__all__ = [
+    "GrafoConciergeServer",
+    "ActionHooks",
+]

interface/action_hooks.py

@@ -0,0 +1,261 @@
+"""
+interface/action_hooks.py — Grafo Concierge v3.8.0 (Absolute Solidity)
+
+Reactive Lifecycle Triggers for Operational Modules.
+
+This module exposes decorators and functions that allow any
+Operational Module (Cursor Skills, n8n Agents, Automations)
+to connect to Grafo Concierge at key lifecycle moments.
+
+Triggers:
+    on_planning()   -> Reactivates consciousness + searches relevant drawers
+    on_execution()  -> Focused search + lazy load of specific nodes
+    on_done()       -> Audited commit + trajectory decay
+
+Typical flow of an Operational Module:
+    1. Module receives user task
+    2. Calls hooks.on_planning() -> receives Compass + context
+    3. Executes task using hooks.on_execution() to fetch code
+    4. Finishes with hooks.on_done() -> writes result to graph
+
+Integration:
+    - Consumes core.middleware.GrafoConcierge as sole dependency
+    - Consumes agents.revisor_critico.RevisorCritico for auditing
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from core.middleware import GrafoConcierge
+from agents.revisor_critico import RevisorCritico
+
+logger = logging.getLogger("grafo-concierge.hooks")
+
+
+class ActionHooks:
+    """Reactive triggers for Operational Modules.
+
+    Centralizes contact points between Operational Modules and
+    Grafo Concierge. Each method corresponds to a phase of
+    a task's lifecycle.
+
+    Args:
+        concierge: Central Facade instance.
+        revisor: Critical Reviewer instance (optional).
+                 If None, commits do not go through LLM auditing.
+    """
+
+    def __init__(
+        self,
+        concierge: GrafoConcierge,
+        revisor: Optional[RevisorCritico] = None,
+    ) -> None:
+        self._gc = concierge
+        self._revisor = revisor or RevisorCritico()
+
+        logger.info(
+            "ActionHooks initialized: reviewer=%s",
+            "LLM" if revisor and revisor._llm else "heuristic",
+        )
+
+    # ===================================================================
+    # ON_PLANNING — Consciousness reactivation
+    # ===================================================================
+
+    def on_planning(
+        self,
+        project_uuid: str,
+        task: str,
+        top_k: int = 5,
+        node_type: Optional[str] = None,
+    ) -> dict:
+        """Planning trigger — prepares the context for the task.
+
+        Flow:
+            1. Wake-up -> loads Compass + Reference Wings + commits
+            2. Hybrid Search -> finds relevant drawers for the task
+            3. Returns full context package
+
+        Args:
+            project_uuid: UUID of the project.
+            task: Description of the task to be executed.
+            top_k: Maximum number of search results.
+            node_type: Optional surgical filter.
+
+        Returns:
+            Dict with:
+            {
+                "wake_up": dict (Compass + Wings + commits),
+                "relevant_nodes": list[dict] (search results),
+                "task": str,
+            }
+        """
+        logger.info("on_planning: project=%s, task='%.50s...'", project_uuid, task)
+
+        # 1. Wake-up
+        wake_data = self._gc.wake_up(project_uuid)
+
+        # 2. Hybrid Search
+        search_results = self._gc.hybrid_search(
+            query=task,
+            project_uuid=project_uuid,
+            top_k=top_k,
+            node_type=node_type,
+        )
+
+        result = {
+            "wake_up": wake_data,
+            "relevant_nodes": search_results,
+            "task": task,
+        }
+
+        logger.info(
+            "on_planning OK: wake_up with %d commits, %d relevant nodes.",
+            len(wake_data.get("recent_commits", [])),
+            len(search_results),
+        )
+        return result
+
+    # ===================================================================
+    # ON_EXECUTION — Focused search during execution
+    # ===================================================================
+
+    def on_execution(
+        self,
+        project_uuid: str,
+        task: str,
+        top_k: int = 10,
+        node_type: Optional[str] = None,
+        include_references: bool = False,
+        rerank: bool = True,
+    ) -> list[dict]:
+        """Execution trigger — searches and filters drawers by relevance.
+
+        Flow:
+            1. Hybrid Search v4 with Strict Scoping
+            2. If rerank=True, Critical Reviewer filters top-5
+            3. Returns relevant drawers for the task
+
+        Args:
+            project_uuid: UUID of the project.
+            task: Description of the current task.
+            top_k: Maximum number of initial search results.
+            node_type: Surgical filter (FACT, SKILL, INSIGHT, etc.).
+            include_references: Include Reference Wings.
+            rerank: Apply Critical Reviewer Reranking.
+
+        Returns:
+            List of dicts with filtered results.
+        """
+        logger.info("on_execution: project=%s, task='%.50s...'", project_uuid, task)
+
+        # 1. Hybrid Search
+        search_results = self._gc.hybrid_search(
+            query=task,
+            project_uuid=project_uuid,
+            top_k=top_k,
+            include_references=include_references,
+            node_type=node_type,
+        )
+
+        # 2. Reranking (if active and there are results)
+        if rerank and search_results:
+            search_results = self._revisor.rerank(
+                candidates=search_results,
+                task_context=task,
+                max_results=5,
+            )
+
+        logger.info(
+            "on_execution OK: %d results (rerank=%s).",
+            len(search_results), rerank,
+        )
+        return search_results
+
+    # ===================================================================
+    # ON_DONE — Audited commit post-task
+    # ===================================================================
+
+    def on_done(
+        self,
+        project_uuid: str,
+        outcome: dict,
+    ) -> dict:
+        """Conclusion trigger — registers result in the graph.
+
+        Flow:
+            1. Critical Reviewer audits the draft
+            2. If approved, writes commit to the graph
+            3. If there is an error/solution, registers episodic trajectory
+            4. Returns operation result
+
+        Args:
+            project_uuid: UUID of the project.
+            outcome: Dict with task outcome:
+                - phase (str): Phase (planning, build, done, review)
+                - technical_changes (str): Technical changes
+                - updated_pointers (list[str]): Updated pointers
+                - node_ids (list[int], optional): Affected nodes
+                - erro_encontrado (str, optional): Error occurred
+                - solucao_aplicada (str, optional): Solution applied
+
+        Returns:
+            Dict with:
+            {
+                "commit_id": int,
+                "audit": AuditResult.to_dict(),
+                "trajectory_id": int (if there was an error),
+            }
+        """
+        logger.info("on_done: project=%s, phase='%s'", project_uuid, outcome.get("phase", "?"))
+
+        result: dict[str, Any] = {}
+
+        # 1. Auditoria do commit
+        audit = self._revisor.audit({
+            "phase": outcome.get("phase", "done"),
+            "technical_changes": outcome.get("technical_changes", ""),
+            "updated_pointers": outcome.get("updated_pointers", []),
+            "source_wing": "primary",
+        })
+        result["audit"] = audit.to_dict()
+
+        # 2. Grava commit (mesmo se partial_audit, para não perder dados)
+        if audit.approved:
+            commit_id = self._gc.commit_memory(
+                project_uuid=project_uuid,
+                phase=outcome.get("phase", "done"),
+                technical_changes=audit.technical_changes,
+                updated_pointers=audit.updated_pointers,
+                node_ids=outcome.get("node_ids"),
+            )
+            result["commit_id"] = commit_id
+        else:
+            result["commit_id"] = None
+            logger.warning("on_done: commit REJEITADO — %s", audit.reason)
+
+        # 3. Registra trajetória episódica (se houve erro)
+        if outcome.get("erro_encontrado"):
+            try:
+                trajectory_id = self._gc.store.create_trajectory(
+                    project_uuid=project_uuid,
+                    prompt_origem=outcome.get("task", ""),
+                    tentativa_execucao=outcome.get("technical_changes", ""),
+                    erro_encontrado=outcome.get("erro_encontrado"),
+                    solucao_aplicada=outcome.get("solucao_aplicada"),
+                )
+                result["trajectory_id"] = trajectory_id
+                logger.info(
+                    "Trajetória episódica registrada: id=%d", trajectory_id,
+                )
+            except Exception as e:
+                logger.error("Falha ao registrar trajetória: %s", e)
+                result["trajectory_id"] = None
+
+        logger.info(
+            "on_done OK: commit_id=%s, audit_approved=%s, partial=%s",
+            result.get("commit_id"), audit.approved, audit.partial_audit,
+        )
+        return result

interface/cli.py

@@ -0,0 +1,391 @@
+"""
+interface/cli.py — Grafo Concierge v3.8.0 (Absolute Solidity)
+
+Terminal Interface (CLI) to manage Grafo Concierge
+via Bash/PowerShell.
+
+Commands:
+    grafo-concierge register  → Registers a new project
+    grafo-concierge mine      → Directory ingestion
+    grafo-concierge search    → Hybrid Search v4
+    grafo-concierge wakeup    → Consciousness reactivation
+    grafo-concierge resume    → Context Compass
+    grafo-concierge commit    → Changelog registration
+    grafo-concierge load      → Node Lazy Load
+    grafo-concierge status    → System health status
+    grafo-concierge projects  → Lists projects
+
+Usage:
+    python -m interface.cli mine --path /projects/vortex --name vortex-pro
+    python -m interface.cli search --query "JWT authentication" --project abc123
+    python -m interface.cli wakeup --project abc123
+
+Integration:
+    Consumes core.middleware.GrafoConcierge as sole dependency.
+    Bootstrap is automatically performed via _bootstrap_concierge().
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("grafo-concierge.cli")
+
+
+# ---------------------------------------------------------------------------
+# Bootstrap — Initializes the GrafoConcierge for CLI use
+# ---------------------------------------------------------------------------
+
+def _bootstrap_concierge():
+    """Initializes the Central Facade for CLI usage.
+
+    Uses the same environment variables as main.py.
+    Returns a ready-to-use GrafoConcierge instance.
+    """
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    from storage import SqliteStore, EmbeddingManager, EmbeddingTier, ChromaVectorStore
+    from ingestion import IngestionManager, ZoomSummarizer
+    from ingestion.summarizer import LLMAdapter
+    from core.middleware import GrafoConcierge
+
+    # Dynamic anchor: interface/ → project root
+    _project_root = Path(__file__).parent.parent.resolve()
+
+    def resolve_project_path(env_value: str, default_rel: str) -> str:
+        val = env_value or default_rel
+        path = Path(val)
+        if path.is_absolute():
+            return str(path)
+        return str((_project_root / path).resolve())
+
+    db_path = resolve_project_path(os.environ.get("GRAFO_DB_PATH", ""), "data/concierge.db")
+    chroma_path = resolve_project_path(os.environ.get("GRAFO_CHROMA_PATH", ""), "data/chroma")
+    chroma_collection = os.environ.get("GRAFO_CHROMA_COLLECTION", "grafo_concierge")
+    llm_model = os.environ.get("GRAFO_LLM_MODEL", "gemini-2.0-flash")
+    llm_api_key = os.environ.get("GRAFO_LLM_API_KEY", "")
+    llm_base_url = os.environ.get("GRAFO_LLM_BASE_URL", "")
+
+    os.makedirs(os.path.dirname(db_path) or ".", exist_ok=True)
+    os.makedirs(chroma_path, exist_ok=True)
+
+    store = SqliteStore(db_path)
+    embedder = EmbeddingManager(tier=EmbeddingTier.FLASH)
+
+    vector_backend = os.environ.get("GRAFO_VECTOR_BACKEND", "chroma").lower()
+    if vector_backend == "qdrant":
+        qdrant_url = os.environ.get("GRAFO_QDRANT_URL", "http://localhost:6333")
+        qdrant_key = os.environ.get("GRAFO_QDRANT_API_KEY", "") or None
+        from core.vector_backend import QdrantVectorStore
+        vector_store = QdrantVectorStore(
+            url=qdrant_url,
+            api_key=qdrant_key,
+            collection_name=chroma_collection,
+            embedding_dimensions=embedder.dimensions,
+        )
+    else:
+        vector_store = ChromaVectorStore(
+            persist_dir=chroma_path,
+            collection_name=chroma_collection,
+            embedding_manager=embedder,
+        )
+
+    llm_adapter = LLMAdapter(
+        model_name=llm_model,
+        api_key=llm_api_key or None,
+        base_url=llm_base_url or None,
+    )
+    summarizer = ZoomSummarizer(llm_adapter=llm_adapter, sqlite_store=store)
+
+    ingestion_manager = IngestionManager(
+        sqlite_store=store,
+        vector_store=vector_store,
+        embedding_manager=embedder,
+        summarizer=summarizer,
+    )
+
+    gc = GrafoConcierge(
+        sqlite_store=store,
+        vector_store=vector_store,
+        embedding_manager=embedder,
+        ingestion_manager=ingestion_manager,
+    )
+
+    return gc, store
+
+
+def _print_json(data: dict) -> None:
+    """Prints result formatted as JSON."""
+    print(json.dumps(data, indent=2, ensure_ascii=False, default=str))
+
+
+# ---------------------------------------------------------------------------
+# CLI Commands
+# ---------------------------------------------------------------------------
+
+def cmd_register(args, gc, store):
+    """Registers a new project."""
+    uuid = gc.register_project(
+        folder_name=args.name,
+        wing=args.wing,
+        privacy_level=args.privacy or "PUBLIC",
+        summary=args.summary,
+    )
+    print(f"Project registered: {args.name} → {uuid}")
+
+
+def cmd_mine(args, gc, store):
+    """Executes directory ingestion."""
+    uuid = gc.register_project(folder_name=args.name)
+    result = gc.mine(uuid, args.path, auto_tag=not args.no_tag)
+    _print_json(result)
+
+
+def cmd_search(args, gc, store):
+    """Hybrid Search v4."""
+    results = gc.hybrid_search(
+        query=args.query,
+        project_uuid=args.project,
+        top_k=args.top_k,
+        node_type=args.node_type,
+        include_references=args.refs,
+        all_wings=args.all_wings,
+    )
+    _print_json({"results_count": len(results), "results": results})
+
+
+def cmd_wakeup(args, gc, store):
+    """Consciousness reactivation."""
+    result = gc.wake_up(args.project)
+    _print_json(result)
+
+
+def cmd_resume(args, gc, store):
+    """Context Compass."""
+    resume = gc.get_resume(args.project)
+    print(resume)
+
+
+def cmd_commit(args, gc, store):
+    """Commit registration."""
+    pointers = args.pointers.split(",") if args.pointers else []
+    commit_id = gc.commit_memory(
+        project_uuid=args.project,
+        phase=args.phase,
+        technical_changes=args.changes,
+        updated_pointers=pointers,
+    )
+    print(f"Commit registered: id={commit_id}")
+
+
+def cmd_load(args, gc, store):
+    """Lazy Load of a node."""
+    result = gc.lazy_load(args.node_id)
+    _print_json(result)
+
+
+def cmd_status(args, gc, store):
+    """System status."""
+    if args.project:
+        result = gc.status(args.project)
+    else:
+        projects = store.list_projects()
+        result = {
+            "system": "Grafo Concierge v3.8.0",
+            "total_projects": len(projects),
+            "projects": [
+                {"uuid": p["uuid"], "name": p.get("folder_name", ""), "wing": p.get("primary_wing", "geral")}
+                for p in projects
+            ],
+        }
+    _print_json(result)
+
+
+def cmd_projects(args, gc, store):
+    """Lists all projects."""
+    projects = store.list_projects()
+    if not projects:
+        print("No projects registered.")
+        return
+
+    print(f"{'UUID':<38} {'Name':<25} {'Wing':<20} {'Privacy':<12}")
+    print("-" * 95)
+    for p in projects:
+        print(
+            f"{p['uuid']:<38} {p.get('folder_name', ''):<25} "
+            f"{p.get('primary_wing', 'general'):<20} {p.get('privacy_level', 'PUBLIC'):<12}"
+        )
+
+
+def cmd_sync_vector(args, gc, store):
+    """Synchronizes and reconciles missing embeddings in the active vector store manually."""
+    from services.janitor import JanitorService, MaintenanceReport
+    
+    # Initializes local JanitorService
+    janitor = JanitorService(
+        sqlite_store=store,
+        vector_store=gc._vector,
+        ingestion_manager=gc._ingestion,
+    )
+    
+    projects_to_sync = []
+    if args.project:
+        projects_to_sync.append(args.project)
+    else:
+        all_projects = store.list_projects()
+        projects_to_sync = [p["uuid"] for p in all_projects]
+        
+    if not projects_to_sync:
+        print("No registered projects found to synchronize.")
+        return
+        
+    print(f"Starting manual batch vector reconciliation for {len(projects_to_sync)} projects...")
+    for p_uuid in projects_to_sync:
+        p_name = next((p["folder_name"] for p in store.list_projects() if p["uuid"] == p_uuid), p_uuid)
+        print(f"-> Synchronizing project: {p_name} ({p_uuid})...")
+        report = MaintenanceReport()
+        # Executes bidirectional reconciliation (deletes orphans and generates missing)
+        janitor._sync_vectors(p_uuid, report)
+        if report.errors:
+            print(f"   [ERROR] {report.errors[0]}")
+        else:
+            print(f"   [OK] Vector reconciliation completed successfully.")
+    print("Reconciliation and synchronization finished!")
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    """Builds the CLI argument parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="grafo-concierge",
+        description="Grafo Concierge v3.8.0 — Sovereign Memory for AI Agents",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available command")
+
+    # --- register ---
+    p_register = subparsers.add_parser("register", help="Registers a new project")
+    p_register.add_argument("--name", required=True, help="Project name")
+    p_register.add_argument("--wing", default=None, help="Primary Wing")
+    p_register.add_argument("--privacy", default="PUBLIC", help="Privacy level")
+    p_register.add_argument("--summary", default=None, help="Project description")
+
+    # --- mine ---
+    p_mine = subparsers.add_parser("mine", help="Directory ingestion")
+    p_mine.add_argument("--path", required=True, help="Directory path")
+    p_mine.add_argument("--name", required=True, help="Project name")
+    p_mine.add_argument("--no-tag", action="store_true", help="Disables auto-tag")
+
+    # --- search ---
+    p_search = subparsers.add_parser("search", help="Hybrid Search v4")
+    p_search.add_argument("--query", required=True, help="Search text")
+    p_search.add_argument("--project", required=True, help="Project UUID")
+    p_search.add_argument("--top-k", type=int, default=10, help="Maximum results")
+    p_search.add_argument("--node-type", default=None, help="Node type filter")
+    p_search.add_argument("--refs", action="store_true", help="Include Reference Wings")
+    p_search.add_argument("--all-wings", action="store_true", help="Search in all wings")
+
+    # --- wakeup ---
+    p_wakeup = subparsers.add_parser("wakeup", help="Consciousness reactivation")
+    p_wakeup.add_argument("--project", required=True, help="Project UUID")
+
+    # --- resume ---
+    p_resume = subparsers.add_parser("resume", help="Context Compass")
+    p_resume.add_argument("--project", required=True, help="Project UUID")
+
+    # --- commit ---
+    p_commit = subparsers.add_parser("commit", help="Registers a memory commit")
+    p_commit.add_argument("--project", required=True, help="Project UUID")
+    p_commit.add_argument("--phase", required=True, help="Current phase")
+    p_commit.add_argument("--changes", required=True, help="Technical changes")
+    p_commit.add_argument("--pointers", required=True, help="Pointers (comma-separated)")
+
+    # --- load ---
+    p_load = subparsers.add_parser("load", help="Lazy Load of a node")
+    p_load.add_argument("--node-id", type=int, required=True, help="Node ID")
+
+    # --- status ---
+    p_status = subparsers.add_parser("status", help="System status")
+    p_status.add_argument("--project", default=None, help="Project UUID (optional)")
+
+    # --- projects ---
+    subparsers.add_parser("projects", help="Lists all projects")
+
+    # --- sync-vector ---
+    p_sync_vector = subparsers.add_parser("sync-vector", help="Synchronizes and reconciles missing embeddings in the active vector store manually")
+    p_sync_vector.add_argument("--project", default=None, help="UUID of a specific project to synchronize (optional)")
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+COMMAND_MAP = {
+    "register": cmd_register,
+    "mine": cmd_mine,
+    "search": cmd_search,
+    "wakeup": cmd_wakeup,
+    "resume": cmd_resume,
+    "commit": cmd_commit,
+    "load": cmd_load,
+    "status": cmd_status,
+    "projects": cmd_projects,
+    "sync-vector": cmd_sync_vector,
+}
+
+
+def main():
+    """CLI entry point."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    # Setup minimal logging for CLI
+    logging.basicConfig(
+        level=logging.WARNING,
+        format="%(levelname)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    # Bootstrap
+    try:
+        gc, store = _bootstrap_concierge()
+    except Exception as e:
+        print(f"Error initializing Grafo Concierge: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Executes command
+    handler = COMMAND_MAP.get(args.command)
+    if handler:
+        try:
+            handler(args, gc, store)
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+        finally:
+            try:
+                store.close()
+            except Exception:
+                pass
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()