contextual-engine 0.9.2__tar.gz → 0.9.5__tar.gz

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextual-engine
-Version: 0.9.2
+Version: 0.9.5
 Summary: Temporal-first local code memory for AI tools via MCP
 Project-URL: Homepage, https://contextuallabs.dev
 Project-URL: Documentation, https://contextuallabs.dev/docs

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/cli/commands/index.py

@@ -47,6 +47,15 @@ async def index(
         "-f",
         help="Force full re-index even if already up-to-date",
     ),
+    bootstrap_cochange: bool = typer.Option(
+        False,
+        "--bootstrap-cochange",
+        help=(
+            "Walk up to 2000 git commits to pre-populate entity_commits for "
+            "co-change analysis. Only effective with --force. Commits touching "
+            ">50 files are excluded as noise."
+        ),
+    ),
     ctx: str | None = typer.Option(None, hidden=True),
 ) -> None:
     """Index codebase for semantic search."""
@@ -151,6 +160,7 @@ async def index(
                                             context=cli_ctx.request_context,
                                             force=force,
                                             incremental=incremental,
+                                            bootstrap_cochange=bootstrap_cochange,
                                             on_discovery=_on_discovery,
                                             on_file_chunked=_on_file_chunked,
                                             on_batch_embedded=_on_batch_embedded,

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/cli/commands/initialisation.py

@@ -531,6 +531,28 @@ async def run_workspace_init(workspace_root: Path) -> None:
 
         await _register_workspace_globally(global_conn, workspace_id, workspace_root, logger)
 
+        # Also register in workspaces.json for multi-workspace MCP support.
+        # Non-fatal: the DB registration above is authoritative for init; the
+        # registry entry is a convenience that `contextual workspace add` can
+        # replicate if this fails.
+        try:
+            from contextual.mcp.workspace_registry import WORKSPACE_REGISTRY
+
+            try:
+                WORKSPACE_REGISTRY.add_workspace(workspace_root.name, workspace_root)
+                logger.info(
+                    "workspace_registry_json_added",
+                    name=workspace_root.name,
+                    path=str(workspace_root),
+                )
+            except ValueError:
+                logger.debug(
+                    "workspace_registry_json_already_registered",
+                    name=workspace_root.name,
+                )
+        except Exception as exc:
+            logger.warning("workspace_registry_json_add_failed", error=str(exc))
+
         try:
             if not (
                 config_path.exists()

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/cli/commands/mcp.py

@@ -144,7 +144,7 @@ def mcp_logs(
                 console.print(line, highlight=False, end="")
     except Exception as e:
         print_error(f"Failed to read logs: {e}")
-        return
+        raise typer.Exit(1)
 
     if follow:
         try:

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/cli/commands/stats.py

@@ -22,7 +22,6 @@ from contextual.security.sanitize import sql_str_literal
 @require_config
 @require_index
 async def stats(
-    path: str = typer.Option(".", "--path", "-p", help="Repository path"),
     temporal: bool = typer.Option(False, "--temporal", "-t", help="Show temporal stats"),
     graph: bool = typer.Option(False, "--graph", "-g", help="Show graph stats"),
     show_all: bool = typer.Option(False, "--all", "-a", help="Show all stats"),

contextual_engine-0.9.5/contextual/cli/commands/workspace.py

@@ -0,0 +1,100 @@
+"""Workspace management commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from contextual.cli.core import register_command
+from contextual.cli.core.output import print_error, print_workspace_list
+
+
+@register_command(group="workspace", name="list")
+async def workspace_list() -> None:
+    """List all registered workspaces."""
+    from contextual.mcp.workspace_registry import WORKSPACE_REGISTRY
+
+    ws_map = WORKSPACE_REGISTRY.load_registered_workspaces()
+    if not ws_map:
+        print_workspace_list([])
+        return
+
+    workspaces = []
+    for name, path_str in ws_map.items():
+        path = Path(path_str)
+        workspace_id = ""
+        last_indexed_at = "never"
+
+        try:
+            state_file = path / ".contextual" / "state.json"
+            if state_file.exists():
+                state_data = json.loads(state_file.read_text(encoding="utf-8"))
+                last_indexed_at = state_data.get("last_indexed_at", "never")
+        except Exception:
+            pass
+
+        try:
+            from contextual.indexing._config import load_runtime_config
+
+            cfg = load_runtime_config(path)
+            workspace_id = str(cfg.workspace_id)
+        except Exception:
+            pass
+
+        workspaces.append({
+            "path": f"{name}  {path_str}",
+            "workspace_id": workspace_id,
+            "last_indexed_at": last_indexed_at,
+        })
+
+    print_workspace_list(workspaces)
+
+
+@register_command(group="workspace", name="add")
+async def workspace_add(
+    path: str = typer.Argument(..., help="Absolute path to the workspace root"),
+    name: str = typer.Option(
+        None,
+        "--name",
+        "-n",
+        help="Human-readable workspace name (defaults to directory basename)",
+    ),
+) -> None:
+    """Register a workspace in the multi-workspace registry."""
+    from contextual.mcp.workspace_registry import WORKSPACE_REGISTRY
+
+    resolved = Path(path).expanduser().resolve()
+    ws_name = name or resolved.name
+    if not ws_name:
+        print_error("Could not derive a workspace name.", hint="Use --name <name>")
+        raise typer.Exit(1)
+
+    try:
+        WORKSPACE_REGISTRY.add_workspace(ws_name, resolved)
+        typer.echo(f"Registered workspace '{ws_name}' at {resolved}")
+    except ValueError as exc:
+        print_error(str(exc))
+        raise typer.Exit(1) from exc
+    except Exception as exc:
+        print_error(f"Failed to register workspace: {exc}")
+        raise typer.Exit(1) from exc
+
+
+@register_command(group="workspace", name="remove")
+async def workspace_remove(
+    name: str = typer.Argument(..., help="Workspace name to deregister"),
+) -> None:
+    """Remove a workspace from the multi-workspace registry."""
+    from contextual.mcp.workspace_registry import WORKSPACE_REGISTRY
+
+    try:
+        WORKSPACE_REGISTRY.remove_workspace(name)
+        typer.echo(f"Removed workspace '{name}'")
+    except KeyError as exc:
+        print_error(str(exc))
+        raise typer.Exit(1) from exc
+    except Exception as exc:
+        print_error(f"Failed to remove workspace: {exc}")
+        raise typer.Exit(1) from exc

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/config/global_/mcp_config.py

@@ -50,6 +50,15 @@ class DaemonConfig(BaseModel):
     compaction_interval_hours: float = 6.0   # How often the background loop runs (0 disables)
     compaction_retention_hours: float = 1.0  # Prune versions older than this; never 0 (breaks concurrent writes)
 
+    # Heap / memory trimmer
+    # When the daemon's physical footprint exceeds heap_trim_threshold_mb a
+    # hard trim fires (GC + malloc page return). If the footprint is still over
+    # the threshold on the next tick and no sessions are active, models are
+    # offloaded to CPU to recover MPS/GPU pages. Set to 0 to disable.
+    heap_monitor_enabled: bool = True
+    heap_monitor_interval_seconds: int = 30
+    heap_trim_threshold_mb: int = 2500
+
     # Logging
     log_level: str = "INFO"
 

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/config/indexing.py

@@ -113,7 +113,7 @@ class SearchConfig(BaseModel):
         le=200,
         description="Number of candidates retrieved before reranking.",
     )
-    enable_reranker: bool = Field(default=True)
+    enable_reranker: bool = Field(default=False)  # 124x latency overhead with no accuracy gain on MPS
     rerank_top_k: int = Field(
         default=10,
         ge=5,
@@ -149,12 +149,10 @@ class RetrievalConfig:
     bm25_candidates: int = 100
     dense_candidates: int = 100
     rrf_candidates: int = 50
-    bm25_k1: float = 1.2
-    bm25_b: float = 0.3
     rrf_k: int = 60
     rrf_dense_weight: float = 0.6
     rrf_bm25_weight: float = 0.4
-    reranker_enabled: bool = True
+    reranker_enabled: bool = False  # 124x latency overhead with no accuracy gain on MPS
     reranker_top_n: int = 15
     reranker_max_chunk_chars: int = 2000
     mmr_enabled: bool = True
@@ -195,8 +193,6 @@ class RetrievalConfig:
                 retrieval_data.get("dense_candidates", defaults.dense_candidates)
             ),
             rrf_candidates=int(retrieval_data.get("rrf_candidates", defaults.rrf_candidates)),
-            bm25_k1=float(retrieval_data.get("bm25_k1", defaults.bm25_k1)),
-            bm25_b=float(retrieval_data.get("bm25_b", defaults.bm25_b)),
             rrf_k=int(retrieval_data.get("rrf_k", defaults.rrf_k)),
             rrf_dense_weight=float(
                 retrieval_data.get("rrf_dense_weight", defaults.rrf_dense_weight)
@@ -316,12 +312,10 @@ class RuntimeIndexingConfig:
 
 @dataclass(slots=True)
 class RuntimeRetrievalConfig:
-    bm25_k1: float = 1.2
-    bm25_b: float = 0.3
     rrf_k: int = 60
     rrf_dense_weight: float = 0.6
     rrf_bm25_weight: float = 0.4
-    reranker_enabled: bool = True
+    reranker_enabled: bool = False  # 124x latency overhead with no accuracy gain on MPS
     reranker_top_n: int = 15
     mmr_lambda: float = 0.7
     mmr_max_chunks_per_file: int = 2
@@ -393,12 +387,10 @@ class ConfigLoader:
                 "workers": 8,
             },
             "retrieval": {
-                "bm25_k1": 1.2,
-                "bm25_b": 0.3,
                 "rrf_k": 60,
                 "rrf_dense_weight": 0.6,
                 "rrf_bm25_weight": 0.4,
-                "reranker_enabled": True,
+                "reranker_enabled": False,  # 124x latency overhead with no accuracy gain on MPS
                 "reranker_top_n": 15,
                 "mmr_lambda": 0.7,
                 "mmr_max_chunks_per_file": 2,
@@ -437,10 +429,6 @@ class ConfigLoader:
             env_overrides["indexing"]["chunk_overlap"] = int(value)
         if value := os.getenv("CONTEXTUAL_MAX_FILE_SIZE_KB"):
             env_overrides["indexing"]["max_file_size_kb"] = int(value)
-        if value := os.getenv("CONTEXTUAL_BM25_K1"):
-            env_overrides["retrieval"]["bm25_k1"] = float(value)
-        if value := os.getenv("CONTEXTUAL_BM25_B"):
-            env_overrides["retrieval"]["bm25_b"] = float(value)
         if value := os.getenv("CONTEXTUAL_RRF_K"):
             env_overrides["retrieval"]["rrf_k"] = int(value)
         if value := os.getenv("CONTEXTUAL_RRF_DENSE_WEIGHT"):

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/config/paths.py

@@ -43,6 +43,7 @@ DAEMON_LOCK = CONTEXTUAL_HOME / "daemon.lock"
 DAEMON_LOG = CONTEXTUAL_HOME / "daemon.log"
 VERSION_FILE = CONTEXTUAL_HOME / ".version"
 MCP_CONFIG_FILE = CONTEXTUAL_HOME / "mcp.json"
+WORKSPACES_JSON_PATH = CONTEXTUAL_HOME / "workspaces.json"
 LOG_DIR = Path.home() / ".local" / "state" / "contextual" / "logs"
 
 # Canonical per-model weight directories. `contextual fetch` downloads into

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/config/workspace/retrieval_config.py

@@ -6,8 +6,6 @@ from pydantic import BaseModel
 class BM25Config(BaseModel):
     """BM25 retrieval settings."""
 
-    k1: float = 1.2
-    b: float = 0.3
     top_k: int = 100
 
 

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/core/models.py

@@ -98,7 +98,14 @@ class FactSource(StrEnum):
 class Language(StrEnum):
     """Supported programming languages for indexing.
 
-    Week 1 MVP: Python, TypeScript, JavaScript, Go, Java, Rust, C#
+    Each value MUST equal the tree-sitter language name used by
+    ``contextual.indexing.chunker.LANGUAGE_MAP`` (the string handed to
+    ``tree_sitter_language_pack.get_parser``). The chunker maps a file
+    extension to that name; ``_build_chunk`` then does ``Language(name)``.
+    Any name present in ``LANGUAGE_MAP`` but absent here silently casts to
+    ``Language.PYTHON`` — mislabelling the chunk and breaking language
+    filtering. Keep the two in lockstep. ``c_sharp`` is the sole divergence
+    (enum value ``csharp``) and is bridged by ``chunker._TS_TO_LANG``.
     """
 
     PYTHON = "python"
@@ -109,12 +116,53 @@ class Language(StrEnum):
     JAVA = "java"
     RUST = "rust"
     CSHARP = "csharp"
+    # C family
+    C = "c"
+    CPP = "cpp"
+    # JVM / mobile
+    KOTLIN = "kotlin"
+    SWIFT = "swift"
+    SCALA = "scala"
+    DART = "dart"
+    # Scripting
+    RUBY = "ruby"
+    PHP = "php"
+    LUA = "lua"
+    PERL = "perl"
+    R = "r"
+    BASH = "bash"
+    # Functional / emerging
+    HASKELL = "haskell"
+    ELIXIR = "elixir"
     # Config formats (free wins)
     JSON = "json"
     YAML = "yaml"
     TOML = "toml"
     MARKDOWN = "markdown"
     DOCKERFILE = "dockerfile"
+    # Data / schema / infra
+    SQL = "sql"
+    HCL = "hcl"
+    PROTO = "proto"
+    # Web frontend
+    HTML = "html"
+    CSS = "css"
+    SCSS = "scss"
+    # JVM / enterprise
+    GROOVY = "groovy"
+    # Systems / emerging
+    NIM = "nim"
+    ZIG = "zig"
+    V = "v"
+    # Functional
+    ELM = "elm"
+    OCAML = "ocaml"
+    ERLANG = "erlang"
+    # Scientific
+    JULIA = "julia"
+    # Platform / Web3
+    OBJC = "objc"
+    SOLIDITY = "solidity"
 
 
 class ModelType(StrEnum):

{contextual_engine-0.9.2 → contextual_engine-0.9.5}/contextual/git/incremental_git.py

@@ -202,6 +202,7 @@ class GitIntegration:
                 return []
 
             entries: list[BlameEntry] = []
+            current_line = 1
             for (commit, tree_entry), content in blamed:
                 try:
                     text = content.decode("utf-8", errors="replace")
@@ -232,11 +233,12 @@ class GitIntegration:
                         timestamp=datetime.fromtimestamp(commit.commit_time, tz=UTC),
                         commit_sha=commit.id.decode("ascii"),
                         commit_message=commit_message,
-                        line_start=1,
-                        line_end=line_count,
+                        line_start=current_line,
+                        line_end=current_line + line_count - 1,
                         path=tree_entry.path.decode("utf-8", errors="replace"),
                     )
                 )
+                current_line += line_count
 
             return entries
 
@@ -281,6 +283,67 @@ def get_git_integration(repo_path: Path | str) -> GitIntegration:
     return integration
 
 
+async def walk_commit_history(
+    repo_root: Path,
+    max_commits: int = 2000,
+    max_files_per_commit: int = 50,
+) -> list[dict]:
+    """Walk git commit history, returning per-commit file change sets.
+
+    Commits touching more than ``max_files_per_commit`` files are excluded —
+    bulk operations (vendor drops, mass-renames) add noise to co-change coupling
+    and inflate pair counts across the entire repo.
+
+    Args:
+        repo_root: Absolute path to the repository root.
+        max_commits: Maximum commits to inspect (most recent first).
+        max_files_per_commit: Commits with more changed files are skipped.
+
+    Returns:
+        List of ``{commit_hash, timestamp, author, files_changed}`` dicts,
+        ordered most-recent first.
+    """
+
+    def _walk_sync() -> list[dict]:
+        try:
+            import pygit2  # type: ignore[import-untyped]
+        except ImportError:
+            return []
+        try:
+            repo = pygit2.Repository(str(repo_root))
+            head_target = repo.head.target
+        except Exception:
+            return []
+
+        results: list[dict] = []
+        count = 0
+        for commit in repo.walk(head_target, pygit2.GIT_SORT_TIME):
+            if count >= max_commits:
+                break
+            count += 1
+            try:
+                if commit.parents:
+                    diff = repo.diff(commit.parents[0], commit)
+                else:
+                    diff = commit.tree.diff_to_tree()
+                files = {d.new_file.path for d in diff.deltas if d.new_file.path}
+                if len(files) > max_files_per_commit:
+                    continue
+                results.append(
+                    {
+                        "commit_hash": str(commit.id),
+                        "timestamp": datetime.fromtimestamp(commit.commit_time, tz=UTC),
+                        "author": commit.author.name,
+                        "files_changed": sorted(files),
+                    }
+                )
+            except Exception:
+                continue
+        return results
+
+    return await asyncio.to_thread(_walk_sync)
+
+
 import atexit