cortex-llm 1.0.9__tar.gz → 1.0.11__tar.gz

{cortex_llm-1.0.9 → cortex_llm-1.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-llm
-Version: 1.0.9
+Version: 1.0.11
 Summary: GPU-Accelerated LLM Terminal for Apple Silicon
 Home-page: https://github.com/faisalmumtaz/Cortex
 Author: Cortex Development Team
@@ -60,6 +60,8 @@ Dynamic: requires-python
 
 GPU-accelerated local LLMs on Apple Silicon, built for the terminal.
 
+![Cortex preview](docs/assets/cortex-llm.png)
+
 Cortex is a fast, native CLI for running and fine-tuning LLMs on Apple Silicon using MLX and Metal. It automatically detects chat templates, supports multiple model formats, and keeps your workflow inside the terminal.
 
 ## Highlights

{cortex_llm-1.0.9 → cortex_llm-1.0.11}/README.md

@@ -2,6 +2,8 @@
 
 GPU-accelerated local LLMs on Apple Silicon, built for the terminal.
 
+![Cortex preview](docs/assets/cortex-llm.png)
+
 Cortex is a fast, native CLI for running and fine-tuning LLMs on Apple Silicon using MLX and Metal. It automatically detects chat templates, supports multiple model formats, and keeps your workflow inside the terminal.
 
 ## Highlights

{cortex_llm-1.0.9 → cortex_llm-1.0.11}/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.9"
+__version__ = "1.0.11"
 __author__ = "Cortex Development Team"
 __license__ = "MIT"
 

{cortex_llm-1.0.9 → cortex_llm-1.0.11}/cortex/config.py

@@ -146,18 +146,21 @@ class DeveloperConfig(BaseModel):
 
 class PathsConfig(BaseModel):
     """Path configuration."""
-    claude_md_path: Path = Field(default_factory=lambda: Path("./CLAUDE.md"))
     templates_dir: Path = Field(default_factory=lambda: Path.home() / ".cortex" / "templates")
     plugins_dir: Path = Field(default_factory=lambda: Path.home() / ".cortex" / "plugins")
 
 class Config:
     """Main configuration class for Cortex."""
-    
+
+    # State file for runtime state (not committed to git)
+    STATE_FILE = Path.home() / ".cortex" / "state.yaml"
+
     def __init__(self, config_path: Optional[Path] = None):
         """Initialize configuration."""
         self.config_path = config_path or Path("config.yaml")
         self._raw_config: Dict[str, Any] = {}
-        
+        self._state: Dict[str, Any] = {}
+
         self.gpu: GPUConfig
         self.memory: MemoryConfig
         self.performance: PerformanceConfig
@@ -169,8 +172,9 @@ class Config:
         self.system: SystemConfig
         self.developer: DeveloperConfig
         self.paths: PathsConfig
-        
+
         self.load()
+        self._load_state()
     
     def load(self) -> None:
         """Load configuration from YAML file."""
@@ -273,7 +277,7 @@ class Config:
             
             self.paths = PathsConfig(**self._get_section({
                 k: v for k, v in self._raw_config.items()
-                if k in ["claude_md_path", "templates_dir", "plugins_dir"]
+                if k in ["templates_dir", "plugins_dir"]
             }))
             
         except Exception as e:
@@ -303,26 +307,58 @@ class Config:
     def save(self, path: Optional[Path] = None) -> None:
         """Save configuration to YAML file."""
         save_path = path or self.config_path
-        
+
+        # Keys that belong in state file, not config file
+        state_keys = {"last_used_model"}
+
         # Convert Path objects to strings for YAML serialization
         config_dict = {}
         for section in [self.gpu, self.memory, self.performance, self.inference,
                        self.model, self.ui, self.logging, self.conversation,
                        self.system, self.developer, self.paths]:
             section_dict = section.model_dump()
-            # Convert Path objects to strings
+            # Convert Path objects to strings and exclude state keys
             for key, value in section_dict.items():
+                if key in state_keys:
+                    continue  # Skip state keys - they go in state file
                 if isinstance(value, Path):
                     section_dict[key] = str(value)
+            # Remove state keys from section_dict
+            for key in state_keys:
+                section_dict.pop(key, None)
             config_dict.update(section_dict)
-        
+
         with open(save_path, 'w') as f:
             yaml.dump(config_dict, f, default_flow_style=False, sort_keys=False)
     
+    def _load_state(self) -> None:
+        """Load runtime state from state file."""
+        if self.STATE_FILE.exists():
+            try:
+                with open(self.STATE_FILE, 'r') as f:
+                    self._state = yaml.safe_load(f) or {}
+                # Apply state to model config
+                if "last_used_model" in self._state:
+                    self.model.last_used_model = self._state["last_used_model"]
+            except Exception as e:
+                print(f"Warning: Failed to load state from {self.STATE_FILE}: {e}")
+                self._state = {}
+
+    def _save_state(self) -> None:
+        """Save runtime state to state file."""
+        # Ensure directory exists
+        self.STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with open(self.STATE_FILE, 'w') as f:
+                yaml.dump(self._state, f, default_flow_style=False)
+        except Exception as e:
+            print(f"Warning: Failed to save state to {self.STATE_FILE}: {e}")
+
     def update_last_used_model(self, model_name: str) -> None:
-        """Update the last used model and save to config file."""
+        """Update the last used model and save to state file."""
         self.model.last_used_model = model_name
-        self.save()
+        self._state["last_used_model"] = model_name
+        self._save_state()
     
     def __repr__(self) -> str:
         """String representation."""

{cortex_llm-1.0.9 → cortex_llm-1.0.11}/cortex/inference_engine.py

@@ -82,6 +82,62 @@ class GenerationRequest:
         if self.stop_sequences is None:
             self.stop_sequences = []
 
+
+class StreamDeltaNormalizer:
+    """Normalize streaming chunks to deltas, handling cumulative or overlapping output."""
+
+    def __init__(self, max_overlap: int = 4096, min_cumulative_length: int = 32) -> None:
+        self._total_text = ""
+        self._max_overlap = max_overlap
+        self._min_cumulative_length = min_cumulative_length
+        self._cumulative_mode = False
+
+    def normalize(self, chunk: Any) -> str:
+        if chunk is None:
+            return ""
+        if not isinstance(chunk, str):
+            chunk = str(chunk)
+        if not chunk:
+            return ""
+
+        if not self._total_text:
+            self._total_text = chunk
+            return chunk
+
+        if not self._cumulative_mode:
+            if len(chunk) > len(self._total_text) and chunk.startswith(self._total_text):
+                self._cumulative_mode = True
+                delta = chunk[len(self._total_text):]
+                self._total_text = chunk
+                return delta
+            if chunk == self._total_text and len(chunk) >= self._min_cumulative_length:
+                # Likely a cumulative stream repeating the full text; don't re-emit.
+                self._cumulative_mode = True
+                return ""
+            # Default to delta mode to avoid dropping legitimate repeats.
+            self._total_text += chunk
+            return chunk
+
+        # Cumulative mode: emit only new suffix.
+        if chunk.startswith(self._total_text):
+            delta = chunk[len(self._total_text):]
+            self._total_text = chunk
+            return delta
+
+        # Handle partial overlap in cumulative streams.
+        max_overlap = min(len(self._total_text), len(chunk), self._max_overlap)
+        if max_overlap > 0:
+            tail = self._total_text[-max_overlap:]
+            for i in range(max_overlap, 0, -1):
+                if tail[-i:] == chunk[:i]:
+                    delta = chunk[i:]
+                    self._total_text += delta
+                    return delta
+
+        # Fallback: treat as fresh delta to avoid loss.
+        self._total_text += chunk
+        return chunk
+
 class InferenceEngine:
     """GPU-accelerated inference engine."""
     
@@ -243,33 +299,7 @@ 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
+        normalizer = StreamDeltaNormalizer() if request.stream else None
         
         try:
             # Use MLX accelerator's optimized generation if available
@@ -290,7 +320,7 @@ class InferenceEngine:
                         self.status = InferenceStatus.CANCELLED
                         break
 
-                    delta = normalize_stream_chunk(token) if request.stream else str(token)
+                    delta = normalizer.normalize(token) if normalizer else str(token)
                     if not delta:
                         continue
 
@@ -365,7 +395,7 @@ class InferenceEngine:
                     else:
                         token = str(response)
 
-                    delta = normalize_stream_chunk(token) if request.stream else token
+                    delta = normalizer.normalize(token) if normalizer else token
                     if request.stream and not delta:
                         continue
 
@@ -477,6 +507,7 @@ class InferenceEngine:
                 if request.stream:
                     from transformers import TextIteratorStreamer
                     
+                    normalizer = StreamDeltaNormalizer()
                     streamer = TextIteratorStreamer(
                         tokenizer,
                         skip_prompt=True,
@@ -499,6 +530,10 @@ class InferenceEngine:
                         if self._cancel_event.is_set():
                             self.status = InferenceStatus.CANCELLED
                             break
+
+                        delta = normalizer.normalize(token)
+                        if not delta:
+                            continue
                         
                         if first_token_time is None:
                             first_token_time = time.time() - start_time
@@ -523,7 +558,7 @@ class InferenceEngine:
                             )
                             last_metrics_update = current_time
                         
-                        yield token
+                        yield delta
                         
                         if any(stop in token for stop in request.stop_sequences):
                             break
@@ -603,6 +638,7 @@ class InferenceEngine:
             )
             
             if request.stream:
+                normalizer = StreamDeltaNormalizer()
                 # Stream tokens
                 for chunk in response:
                     if self._cancel_event.is_set():
@@ -610,11 +646,12 @@ class InferenceEngine:
                     
                     if 'choices' in chunk and len(chunk['choices']) > 0:
                         token = chunk['choices'][0].get('text', '')
-                        if token:
+                        delta = normalizer.normalize(token)
+                        if delta:
                             if first_token_time is None:
                                 first_token_time = time.time()
                             tokens_generated += 1
-                            yield token
+                            yield delta
             else:
                 # Return full response
                 if 'choices' in response and len(response['choices']) > 0:

cortex_llm-1.0.11/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.11/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.11/cortex/tools/fs_ops.py

@@ -0,0 +1,182 @@
+"""Filesystem operations scoped to a repo root."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+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")
+        if "\x00" in path:
+            raise ValidationError("path contains null byte")
+        if path.startswith("~"):
+            raise ValidationError("path must be repo-relative (no ~)")
+        raw = Path(path)
+        if raw.is_absolute():
+            raise ValidationError("path must be repo-relative (no absolute paths)")
+        resolved = (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 _validate_bool(self, name: str, value: object) -> None:
+        if not isinstance(value, bool):
+            raise ValidationError(f"{name} must be a bool")
+
+    def _validate_int(self, name: str, value: object, minimum: int = 0) -> int:
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValidationError(f"{name} must be an int")
+        if value < minimum:
+            raise ValidationError(f"{name} must be >= {minimum}")
+        return value
+
+    def _validate_content(self, content: object) -> None:
+        if not isinstance(content, str):
+            raise ValidationError("content must be a string")
+
+    def _validate_sha256(self, value: object) -> str:
+        if not isinstance(value, str):
+            raise ValidationError("expected_sha256 must be a string")
+        normalized = value.lower()
+        if not re.fullmatch(r"[0-9a-f]{64}", normalized):
+            raise ValidationError("expected_sha256 must be a 64-character hex string")
+        return normalized
+
+    def list_dir(self, path: str = ".", recursive: bool = False, max_depth: int = 2, max_entries: int = 200) -> Dict[str, List[str]]:
+        self._validate_bool("recursive", recursive)
+        max_depth = self._validate_int("max_depth", max_depth, minimum=0)
+        max_entries = self._validate_int("max_entries", max_entries, minimum=1)
+        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]:
+        start_line = self._validate_int("start_line", start_line, minimum=1)
+        if end_line is not None:
+            end_line = self._validate_int("end_line", end_line, minimum=start_line)
+        max_bytes = self._validate_int("max_bytes", max_bytes, minimum=1)
+        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")
+
+        lines: List[str] = []
+        try:
+            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"))
+        except UnicodeDecodeError as e:
+            raise ToolError(f"file is not valid utf-8: {e}") from e
+        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]:
+        self._validate_content(content)
+        if expected_sha256 is not None:
+            expected_sha256 = self._validate_sha256(expected_sha256)
+        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]:
+        self._validate_content(content)
+        self._validate_bool("overwrite", overwrite)
+        target = self.resolve_path(path)
+        if target.exists() and target.is_dir():
+            raise ValidationError("path already exists and is a directory")
+        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 is_git_tracked(self, target: Path) -> bool:
+        """Return True if the path is tracked by git."""
+        return self._is_git_tracked(target)
+
+    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.11/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}"