cortex-llm 1.0.8__tar.gz → 1.0.10__tar.gz

{cortex_llm-1.0.8 → cortex_llm-1.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-llm
-Version: 1.0.8
+Version: 1.0.10
 Summary: GPU-Accelerated LLM Terminal for Apple Silicon
 Home-page: https://github.com/faisalmumtaz/Cortex
 Author: Cortex Development Team
@@ -131,6 +131,10 @@ Cortex supports:
   - `docs/template-registry.md`
 - **Inference engine details** and backend behavior
   - `docs/inference-engine.md`
+- **Tooling (experimental, WIP)** for repo-scoped read/search and optional file edits with explicit confirmation
+  - `docs/cli.md`
+
+**Important (Work in Progress):** Tooling is actively evolving and should be considered experimental. Behavior, output format, and available actions may change; tool calls can fail; and UI presentation may be adjusted. Use tooling on non-critical work first, and always review any proposed file changes before approving them.
 
 ## Configuration
 

{cortex_llm-1.0.8 → cortex_llm-1.0.10}/README.md

@@ -73,6 +73,10 @@ Cortex supports:
   - `docs/template-registry.md`
 - **Inference engine details** and backend behavior
   - `docs/inference-engine.md`
+- **Tooling (experimental, WIP)** for repo-scoped read/search and optional file edits with explicit confirmation
+  - `docs/cli.md`
+
+**Important (Work in Progress):** Tooling is actively evolving and should be considered experimental. Behavior, output format, and available actions may change; tool calls can fail; and UI presentation may be adjusted. Use tooling on non-critical work first, and always review any proposed file changes before approving them.
 
 ## Configuration
 

{cortex_llm-1.0.8 → cortex_llm-1.0.10}/cortex/__init__.py

@@ -5,7 +5,7 @@ A high-performance terminal interface for running Hugging Face LLMs locally
 with exclusive GPU acceleration via Metal Performance Shaders (MPS) and MLX.
 """
 
-__version__ = "1.0.8"
+__version__ = "1.0.10"
 __author__ = "Cortex Development Team"
 __license__ = "MIT"
 

{cortex_llm-1.0.8 → cortex_llm-1.0.10}/cortex/inference_engine.py

@@ -243,6 +243,33 @@ class InferenceEngine:
         tokens_generated = 0
         first_token_time = None
         last_metrics_update = time.time()
+        stream_total_text = ""
+        stream_cumulative = False
+
+        def normalize_stream_chunk(chunk: Any) -> str:
+            """Normalize streaming output to delta chunks when backend yields cumulative text."""
+            nonlocal stream_total_text, stream_cumulative
+            if chunk is None:
+                return ""
+            if not isinstance(chunk, str):
+                chunk = str(chunk)
+
+            if stream_cumulative:
+                if chunk.startswith(stream_total_text):
+                    delta = chunk[len(stream_total_text):]
+                    stream_total_text = chunk
+                    return delta
+                stream_total_text += chunk
+                return chunk
+
+            if stream_total_text and len(chunk) > len(stream_total_text) and chunk.startswith(stream_total_text):
+                stream_cumulative = True
+                delta = chunk[len(stream_total_text):]
+                stream_total_text = chunk
+                return delta
+
+            stream_total_text += chunk
+            return chunk
         
         try:
             # Use MLX accelerator's optimized generation if available
@@ -262,10 +289,14 @@ class InferenceEngine:
                     if self._cancel_event.is_set():
                         self.status = InferenceStatus.CANCELLED
                         break
-                    
+
+                    delta = normalize_stream_chunk(token) if request.stream else str(token)
+                    if not delta:
+                        continue
+
                     if first_token_time is None:
                         first_token_time = time.time() - start_time
-                    
+
                     tokens_generated += 1
                     
                     # Update metrics less frequently
@@ -284,13 +315,18 @@ class InferenceEngine:
                         last_metrics_update = current_time
                     
                     # Token is already a string from generate_optimized
-                    yield token
+                    yield delta
                     
                     if any(stop in token for stop in request.stop_sequences):
                         break
             elif mlx_generate:
                 # Fallback to standard MLX generation
-                logger.info("Using standard MLX generation")
+                if request.stream and mlx_stream_generate:
+                    logger.info("Using MLX streaming generation")
+                    generate_fn = mlx_stream_generate
+                else:
+                    logger.info("Using standard MLX generation")
+                    generate_fn = mlx_generate
                 
                 # Import sample_utils for creating sampler
                 try:
@@ -314,7 +350,7 @@ class InferenceEngine:
                 if request.seed is not None and request.seed >= 0:
                     mx.random.seed(request.seed)
                 
-                for response in mlx_generate(
+                for response in generate_fn(
                     model,
                     tokenizer,
                     **generation_kwargs
@@ -328,10 +364,14 @@ class InferenceEngine:
                         token = response.text
                     else:
                         token = str(response)
-                    
+
+                    delta = normalize_stream_chunk(token) if request.stream else token
+                    if request.stream and not delta:
+                        continue
+
                     if first_token_time is None:
                         first_token_time = time.time() - start_time
-                    
+
                     tokens_generated += 1
                     
                     # Update metrics less frequently to reduce overhead
@@ -352,7 +392,7 @@ class InferenceEngine:
                         )
                         last_metrics_update = current_time
                     
-                    yield token
+                    yield delta
                     
                     if any(stop in token for stop in request.stop_sequences):
                         break

cortex_llm-1.0.10/cortex/tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tooling support for Cortex CLI."""
+
+from cortex.tools.tool_runner import ToolRunner
+
+__all__ = ["ToolRunner"]

cortex_llm-1.0.10/cortex/tools/errors.py

@@ -0,0 +1,9 @@
+"""Tooling error types."""
+
+
+class ToolError(Exception):
+    """Base error for tool execution failures."""
+
+
+class ValidationError(ToolError):
+    """Raised when tool arguments or inputs are invalid."""

cortex_llm-1.0.10/cortex/tools/fs_ops.py

@@ -0,0 +1,135 @@
+"""Filesystem operations scoped to a repo root."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from cortex.tools.errors import ToolError, ValidationError
+
+
+class RepoFS:
+    """Filesystem helper constrained to a single repo root."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = Path(root).expanduser().resolve()
+
+    def resolve_path(self, path: str) -> Path:
+        if not path or not isinstance(path, str):
+            raise ValidationError("path must be a non-empty string")
+        raw = Path(path).expanduser()
+        resolved = raw.resolve() if raw.is_absolute() else (self.root / raw).resolve()
+        if not resolved.is_relative_to(self.root):
+            raise ValidationError(f"path escapes repo root ({self.root}); use a relative path like '.'")
+        return resolved
+
+    def list_dir(self, path: str = ".", recursive: bool = False, max_depth: int = 2, max_entries: int = 200) -> Dict[str, List[str]]:
+        target = self.resolve_path(path)
+        if not target.is_dir():
+            raise ValidationError("path is not a directory")
+        entries: List[str] = []
+        if not recursive:
+            for item in sorted(target.iterdir()):
+                rel = item.relative_to(self.root)
+                suffix = "/" if item.is_dir() else ""
+                entries.append(f"{rel}{suffix}")
+                if len(entries) >= max_entries:
+                    break
+            return {"entries": entries}
+
+        base_depth = len(target.relative_to(self.root).parts)
+        for dirpath, dirnames, filenames in os.walk(target):
+            depth = len(Path(dirpath).relative_to(self.root).parts) - base_depth
+            if depth > max_depth:
+                dirnames[:] = []
+                continue
+            for name in sorted(dirnames):
+                rel = (Path(dirpath) / name).relative_to(self.root)
+                entries.append(f"{rel}/")
+                if len(entries) >= max_entries:
+                    return {"entries": entries}
+            for name in sorted(filenames):
+                rel = (Path(dirpath) / name).relative_to(self.root)
+                entries.append(str(rel))
+                if len(entries) >= max_entries:
+                    return {"entries": entries}
+        return {"entries": entries}
+
+    def read_text(self, path: str, start_line: int = 1, end_line: Optional[int] = None, max_bytes: int = 2_000_000) -> Dict[str, object]:
+        target = self.resolve_path(path)
+        if not target.is_file():
+            raise ValidationError("path is not a file")
+        size = target.stat().st_size
+        if size > max_bytes and start_line == 1 and end_line is None:
+            raise ToolError("file too large; specify a line range")
+        if start_line < 1:
+            raise ValidationError("start_line must be >= 1")
+        if end_line is not None and end_line < start_line:
+            raise ValidationError("end_line must be >= start_line")
+
+        lines: List[str] = []
+        with target.open("r", encoding="utf-8") as handle:
+            for idx, line in enumerate(handle, start=1):
+                if idx < start_line:
+                    continue
+                if end_line is not None and idx > end_line:
+                    break
+                lines.append(line.rstrip("\n"))
+        content = "\n".join(lines)
+        return {"path": str(target.relative_to(self.root)), "content": content, "start_line": start_line, "end_line": end_line}
+
+    def read_full_text(self, path: str) -> str:
+        target = self.resolve_path(path)
+        if not target.is_file():
+            raise ValidationError("path is not a file")
+        try:
+            return target.read_text(encoding="utf-8")
+        except UnicodeDecodeError as e:
+            raise ToolError(f"file is not valid utf-8: {e}") from e
+
+    def write_text(self, path: str, content: str, expected_sha256: Optional[str] = None) -> Dict[str, object]:
+        target = self.resolve_path(path)
+        if not target.exists() or not target.is_file():
+            raise ValidationError("path does not exist or is not a file")
+        if expected_sha256:
+            current = self.read_full_text(path)
+            if self.sha256_text(current) != expected_sha256:
+                raise ToolError("file changed; expected hash does not match")
+        target.write_text(content, encoding="utf-8")
+        return {"path": str(target.relative_to(self.root)), "sha256": self.sha256_text(content)}
+
+    def create_text(self, path: str, content: str, overwrite: bool = False) -> Dict[str, object]:
+        target = self.resolve_path(path)
+        if target.exists() and not overwrite:
+            raise ValidationError("path already exists")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        return {"path": str(target.relative_to(self.root)), "sha256": self.sha256_text(content)}
+
+    def delete_file(self, path: str) -> Dict[str, object]:
+        target = self.resolve_path(path)
+        if not target.exists() or not target.is_file():
+            raise ValidationError("path does not exist or is not a file")
+        if not self._is_git_tracked(target):
+            raise ToolError("delete blocked: file is not tracked by git")
+        target.unlink()
+        return {"path": str(target.relative_to(self.root)), "deleted": True}
+
+    def sha256_text(self, content: str) -> str:
+        return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+    def _is_git_tracked(self, target: Path) -> bool:
+        git_dir = self.root / ".git"
+        if not git_dir.exists():
+            return False
+        rel = str(target.relative_to(self.root))
+        result = subprocess.run(
+            ["git", "ls-files", "--error-unmatch", rel],
+            cwd=self.root,
+            capture_output=True,
+            text=True,
+        )
+        return result.returncode == 0

cortex_llm-1.0.10/cortex/tools/protocol.py

@@ -0,0 +1,76 @@
+"""Protocol helpers for tool calling."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Tuple
+
+TOOL_CALLS_START = "<tool_calls>"
+TOOL_CALLS_END = "</tool_calls>"
+TOOL_RESULTS_START = "<tool_results>"
+TOOL_RESULTS_END = "</tool_results>"
+
+
+def find_tool_calls_block(text: str) -> Tuple[Optional[int], Optional[int], Optional[str]]:
+    """Return (start, end, block) for tool_calls JSON, if present."""
+    start = text.find(TOOL_CALLS_START)
+    if start == -1:
+        return None, None, None
+    end = text.find(TOOL_CALLS_END, start + len(TOOL_CALLS_START))
+    if end == -1:
+        return start, None, None
+    block = text[start + len(TOOL_CALLS_START) : end].strip()
+    return start, end + len(TOOL_CALLS_END), block
+
+
+def strip_tool_blocks(text: str) -> str:
+    """Remove tool_calls block from text (including incomplete block)."""
+    start, end, _ = find_tool_calls_block(text)
+    if start is None:
+        return text
+    if end is None:
+        return text[:start]
+    return text[:start] + text[end:]
+
+
+def parse_tool_calls(text: str) -> Tuple[List[Dict[str, Any]], Optional[str]]:
+    """Parse tool calls from text. Returns (calls, error)."""
+    start, end, block = find_tool_calls_block(text)
+    if start is None:
+        return [], None
+    if end is None or block is None:
+        return [], "tool_calls block is incomplete"
+    try:
+        payload = json.loads(block)
+    except json.JSONDecodeError as e:
+        return [], f"invalid tool_calls JSON: {e}"
+
+    if not isinstance(payload, dict):
+        return [], "tool_calls payload must be a JSON object"
+    calls = payload.get("calls")
+    if not isinstance(calls, list):
+        return [], "tool_calls payload missing 'calls' list"
+
+    normalized: List[Dict[str, Any]] = []
+    for idx, call in enumerate(calls):
+        if not isinstance(call, dict):
+            return [], f"tool call at index {idx} must be an object"
+        name = call.get("name")
+        arguments = call.get("arguments")
+        call_id = call.get("id") or f"call_{idx + 1}"
+        if not isinstance(name, str) or not name.strip():
+            return [], f"tool call at index {idx} missing valid name"
+        if arguments is None:
+            arguments = {}
+        if not isinstance(arguments, dict):
+            return [], f"tool call '{name}' arguments must be an object"
+        normalized.append({"id": str(call_id), "name": name, "arguments": arguments})
+
+    return normalized, None
+
+
+def format_tool_results(results: List[Dict[str, Any]]) -> str:
+    """Format tool results for model consumption."""
+    payload = {"results": results}
+    body = json.dumps(payload, ensure_ascii=True)
+    return f"{TOOL_RESULTS_START}\n{body}\n{TOOL_RESULTS_END}"

cortex_llm-1.0.10/cortex/tools/search.py

@@ -0,0 +1,70 @@
+"""Search utilities for repo tools."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict, List
+
+from cortex.tools.errors import ToolError, ValidationError
+from cortex.tools.fs_ops import RepoFS
+
+
+class RepoSearch:
+    """Search helper constrained to a repo root."""
+
+    def __init__(self, repo_fs: RepoFS) -> None:
+        self.repo_fs = repo_fs
+
+    def search(self, query: str, path: str = ".", use_regex: bool = True, max_results: int = 100) -> Dict[str, List[Dict[str, object]]]:
+        if not isinstance(query, str) or not query:
+            raise ValidationError("query must be a non-empty string")
+        if max_results < 1:
+            raise ValidationError("max_results must be >= 1")
+        root = self.repo_fs.root
+        target = self.repo_fs.resolve_path(path)
+
+        if shutil.which("rg"):
+            return {"results": self._rg_search(query, target, use_regex, max_results)}
+        return {"results": self._python_search(query, target, use_regex, max_results)}
+
+    def _rg_search(self, query: str, target: Path, use_regex: bool, max_results: int) -> List[Dict[str, object]]:
+        args = ["rg", "--line-number", "--with-filename", "--no-heading"]
+        if not use_regex:
+            args.append("-F")
+        args.extend(["-e", query, str(target)])
+        result = subprocess.run(args, cwd=self.repo_fs.root, capture_output=True, text=True)
+        if result.returncode not in (0, 1):
+            raise ToolError(f"rg failed: {result.stderr.strip()}")
+        matches: List[Dict[str, object]] = []
+        for line in result.stdout.splitlines():
+            try:
+                file_path, line_no, text = line.split(":", 2)
+            except ValueError:
+                continue
+            matches.append({"path": file_path, "line": int(line_no), "text": text})
+            if len(matches) >= max_results:
+                break
+        return matches
+
+    def _python_search(self, query: str, target: Path, use_regex: bool, max_results: int) -> List[Dict[str, object]]:
+        pattern = re.compile(query) if use_regex else None
+        results: List[Dict[str, object]] = []
+        for dirpath, dirnames, filenames in os.walk(target):
+            dirnames[:] = [d for d in dirnames if d != ".git"]
+            for name in filenames:
+                path = Path(dirpath) / name
+                try:
+                    text = path.read_text(encoding="utf-8")
+                except Exception:
+                    continue
+                for idx, line in enumerate(text.splitlines(), start=1):
+                    found = bool(pattern.search(line)) if pattern else (query in line)
+                    if found:
+                        results.append({"path": str(path.relative_to(self.repo_fs.root)), "line": idx, "text": line})
+                        if len(results) >= max_results:
+                            return results
+        return results

cortex_llm-1.0.10/cortex/tools/tool_runner.py

@@ -0,0 +1,144 @@
+"""Tool runner and specifications for Cortex."""
+
+from __future__ import annotations
+
+import difflib
+import json
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from cortex.tools.errors import ToolError, ValidationError
+from cortex.tools.fs_ops import RepoFS
+from cortex.tools.search import RepoSearch
+
+
+ConfirmCallback = Callable[[str], bool]
+
+
+class ToolRunner:
+    """Execute tool calls with safety checks."""
+
+    def __init__(self, root: Path, confirm_callback: Optional[ConfirmCallback] = None) -> None:
+        self.fs = RepoFS(root)
+        self.search = RepoSearch(self.fs)
+        self.confirm_callback = confirm_callback
+
+    def set_confirm_callback(self, callback: ConfirmCallback) -> None:
+        self.confirm_callback = callback
+
+    def tool_spec(self) -> Dict[str, Any]:
+        return {
+            "list_dir": {"args": {"path": "string", "recursive": "bool", "max_depth": "int"}},
+            "read_file": {"args": {"path": "string", "start_line": "int", "end_line": "int", "max_bytes": "int"}},
+            "search": {"args": {"query": "string", "path": "string", "use_regex": "bool", "max_results": "int"}},
+            "write_file": {"args": {"path": "string", "content": "string", "expected_sha256": "string"}},
+            "create_file": {"args": {"path": "string", "content": "string", "overwrite": "bool"}},
+            "delete_file": {"args": {"path": "string"}},
+            "replace_in_file": {"args": {"path": "string", "old": "string", "new": "string", "expected_replacements": "int"}},
+            "insert_after": {"args": {"path": "string", "anchor": "string", "content": "string", "expected_matches": "int"}},
+            "insert_before": {"args": {"path": "string", "anchor": "string", "content": "string", "expected_matches": "int"}},
+        }
+
+    def tool_instructions(self) -> str:
+        spec = json.dumps(self.tool_spec(), ensure_ascii=True, indent=2)
+        repo_root = str(self.fs.root)
+        return (
+            "[CORTEX_TOOL_INSTRUCTIONS v2]\n"
+            "You have access to file tools. If a tool is required, respond ONLY with a <tool_calls> JSON block.\n"
+            "Do not include any other text when calling tools.\n"
+            f"Repo root: {repo_root}\n"
+            "All paths must be relative to the repo root (use '.' for root). Do not use absolute paths or ~.\n"
+            "If you are unsure about paths, call list_dir with path '.' first.\n"
+            "Format:\n"
+            "<tool_calls>{\"calls\":[{\"id\":\"call_1\",\"name\":\"tool_name\",\"arguments\":{...}}]}</tool_calls>\n"
+            "Available tools:\n"
+            f"{spec}"
+        )
+
+    def run_calls(self, calls: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        results: List[Dict[str, Any]] = []
+        for call in calls:
+            call_id = call.get("id", "unknown")
+            name = call.get("name")
+            args = call.get("arguments") or {}
+            try:
+                if name == "list_dir":
+                    result = self.fs.list_dir(**args)
+                elif name == "read_file":
+                    result = self.fs.read_text(**args)
+                elif name == "search":
+                    result = self.search.search(**args)
+                elif name == "write_file":
+                    result = self._write_file(**args)
+                elif name == "create_file":
+                    result = self._create_file(**args)
+                elif name == "delete_file":
+                    result = self._delete_file(**args)
+                elif name == "replace_in_file":
+                    result = self._replace_in_file(**args)
+                elif name == "insert_after":
+                    result = self._insert_relative(after=True, **args)
+                elif name == "insert_before":
+                    result = self._insert_relative(after=False, **args)
+                else:
+                    raise ValidationError(f"unknown tool: {name}")
+                results.append({"id": call_id, "name": name, "ok": True, "result": result, "error": None})
+            except Exception as e:
+                results.append({"id": call_id, "name": name, "ok": False, "result": None, "error": str(e)})
+        return results
+
+    def _write_file(self, path: str, content: str, expected_sha256: Optional[str] = None) -> Dict[str, Any]:
+        before = self.fs.read_full_text(path)
+        self._confirm_change(path, before, content, "write")
+        return self.fs.write_text(path, content, expected_sha256=expected_sha256)
+
+    def _create_file(self, path: str, content: str, overwrite: bool = False) -> Dict[str, Any]:
+        before = ""
+        self._confirm_change(path, before, content, "create")
+        return self.fs.create_text(path, content, overwrite=overwrite)
+
+    def _delete_file(self, path: str) -> Dict[str, Any]:
+        before = self.fs.read_full_text(path)
+        self._confirm_change(path, before, "", "delete")
+        return self.fs.delete_file(path)
+
+    def _replace_in_file(self, path: str, old: str, new: str, expected_replacements: int = 1) -> Dict[str, Any]:
+        if not old:
+            raise ValidationError("old must be a non-empty string")
+        content = self.fs.read_full_text(path)
+        count = content.count(old)
+        if count != expected_replacements:
+            raise ToolError(f"expected {expected_replacements} replacements, found {count}")
+        updated = content.replace(old, new)
+        self._confirm_change(path, content, updated, "replace")
+        return self.fs.write_text(path, updated)
+
+    def _insert_relative(self, path: str, anchor: str, content: str, expected_matches: int = 1, after: bool = True) -> Dict[str, Any]:
+        if not anchor:
+            raise ValidationError("anchor must be a non-empty string")
+        original = self.fs.read_full_text(path)
+        count = original.count(anchor)
+        if count != expected_matches:
+            raise ToolError(f"expected {expected_matches} matches, found {count}")
+        insert_text = anchor + content if after else content + anchor
+        updated = original.replace(anchor, insert_text, count if expected_matches > 1 else 1)
+        self._confirm_change(path, original, updated, "insert")
+        return self.fs.write_text(path, updated)
+
+    def _confirm_change(self, path: str, before: str, after: str, action: str) -> None:
+        if self.confirm_callback is None:
+            raise ToolError("confirmation required but no callback configured")
+        if before == after:
+            raise ToolError("no changes to apply")
+        diff = "\n".join(
+            difflib.unified_diff(
+                before.splitlines(),
+                after.splitlines(),
+                fromfile=f"{path} (before)",
+                tofile=f"{path} (after)",
+                lineterm="",
+            )
+        )
+        prompt = f"Apply {action} to {path}?\n{diff}\n"
+        if not self.confirm_callback(prompt):
+            raise ToolError("change declined by user")