husk-local 0.1.0__tar.gz

husk_local-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Husk Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

husk_local-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: husk-local
+Version: 0.1.0
+Summary: A local-first CLI engine for legacy codebases
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: tree-sitter>=0.21.3
+Requires-Dist: tree-sitter-python>=0.21.0
+Requires-Dist: tree-sitter-javascript>=0.21.0
+Requires-Dist: tree-sitter-typescript>=0.21.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: certifi>=2023.7.22
+Dynamic: license-file
+
+# Husk
+
+*Your codebase's past, present, and architecture—laid bare.*
+
+Understand legacy codebases quickly and privately with offline static analysis and local LLMs, without uploading code or fighting heavy setups.
+
+---
+
+## ❓ Why Husk?
+> Because code archaeology should be secure, local, and instant — without SaaS lock-in or platform-specific vector databases.
+
+---
+
+## 🚀 Key Features
+
+* **Static Analysis (Tier 1):** Code complexity, git churn, hotspots rankings, dead code detection, and Mermaid dependency graph exports.
+* **Semantic AI (Tier 2):** Hierarchical Map-Reduce documentation generator, token/budget limits, and natural language Q&A index with Git Blame annotations.
+* **Remote Git Scanning:** Provide a Git clone link (`https://github.com/...`) instead of a local directory, and Husk will automatically download and scan it temporarily.
+* **Local Offline AI:** Fully integrates with local Ollama servers (like `llama3`) for offline, zero-cost semantic search and summarization.
+
+---
+
+## 📦 Quick Start
+
+```bash
+# Set up environment
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt && pip install -e .
+
+# Configure LLM credentials (or select Ollama for local model)
+husk init
+
+# Scan a local folder or remote repository link
+husk scan https://github.com/example/project.git --detailed
+
+# Generate documentation suite statically or with AI
+husk doc . --with-ai
+
+# Query codebase using RAG
+husk ask "how does authentication work?" https://github.com/example/project.git
+```
+
+---
+
+## 🛠️ CLI Commands
+
+* `husk scan [repo_path_or_url] [--detailed]`: Inventory source files and code symbols.
+* `husk graph [repo_path_or_url] [--output path]`: Export visual Mermaid dependency flows.
+* `husk hotspots [repo_path_or_url]`: Rank files by complexity × churn risks.
+* `husk deadcode [repo_path_or_url]`: List unreferenced files (in-degree = 0).
+* `husk init`: Configure LLM credentials (OpenAI, Anthropic, Ollama).
+* `husk doc [repo_path_or_url] [--with-ai]`: Generate structured documentation under `/docs`.
+* `husk ask "query" [repo_path_or_url]`: Ask natural language questions with git blame context.

husk_local-0.1.0/README.md

@@ -0,0 +1,54 @@
+# Husk
+
+*Your codebase's past, present, and architecture—laid bare.*
+
+Understand legacy codebases quickly and privately with offline static analysis and local LLMs, without uploading code or fighting heavy setups.
+
+---
+
+## ❓ Why Husk?
+> Because code archaeology should be secure, local, and instant — without SaaS lock-in or platform-specific vector databases.
+
+---
+
+## 🚀 Key Features
+
+* **Static Analysis (Tier 1):** Code complexity, git churn, hotspots rankings, dead code detection, and Mermaid dependency graph exports.
+* **Semantic AI (Tier 2):** Hierarchical Map-Reduce documentation generator, token/budget limits, and natural language Q&A index with Git Blame annotations.
+* **Remote Git Scanning:** Provide a Git clone link (`https://github.com/...`) instead of a local directory, and Husk will automatically download and scan it temporarily.
+* **Local Offline AI:** Fully integrates with local Ollama servers (like `llama3`) for offline, zero-cost semantic search and summarization.
+
+---
+
+## 📦 Quick Start
+
+```bash
+# Set up environment
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt && pip install -e .
+
+# Configure LLM credentials (or select Ollama for local model)
+husk init
+
+# Scan a local folder or remote repository link
+husk scan https://github.com/example/project.git --detailed
+
+# Generate documentation suite statically or with AI
+husk doc . --with-ai
+
+# Query codebase using RAG
+husk ask "how does authentication work?" https://github.com/example/project.git
+```
+
+---
+
+## 🛠️ CLI Commands
+
+* `husk scan [repo_path_or_url] [--detailed]`: Inventory source files and code symbols.
+* `husk graph [repo_path_or_url] [--output path]`: Export visual Mermaid dependency flows.
+* `husk hotspots [repo_path_or_url]`: Rank files by complexity × churn risks.
+* `husk deadcode [repo_path_or_url]`: List unreferenced files (in-degree = 0).
+* `husk init`: Configure LLM credentials (OpenAI, Anthropic, Ollama).
+* `husk doc [repo_path_or_url] [--with-ai]`: Generate structured documentation under `/docs`.
+* `husk ask "query" [repo_path_or_url]`: Ask natural language questions with git blame context.

husk_local-0.1.0/husk/__init__.py

@@ -0,0 +1,5 @@
+from husk.crawler import RepoCrawler
+from husk.parser import CodeParser
+from husk.graph import DependencyGraphBuilder
+
+__version__ = "0.1.0"

husk_local-0.1.0/husk/ai/__init__.py

@@ -0,0 +1 @@
+# Husk AI Subpackage

husk_local-0.1.0/husk/ai/adapters.py

@@ -0,0 +1,186 @@
+import os
+import json
+import urllib.request
+import urllib.error
+import ssl
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+
+def get_ssl_context():
+    """
+    Returns an SSL context. Prefers certifi's bundle if available.
+    """
+    try:
+        import certifi
+        return ssl.create_default_context(cafile=certifi.where())
+    except Exception:
+        try:
+            return ssl._create_unverified_context()
+        except AttributeError:
+            return None
+
+class BaseAdapter(ABC):
+    """
+    Abstract Base Class for LLM API Adapters.
+    """
+    def __init__(self, api_key: Optional[str] = None, model: Optional[str] = None):
+        self.api_key = api_key
+        self.model = model
+
+    @abstractmethod
+    def generate(self, prompt: str, system: str = "") -> str:
+        """
+        Sends a request to the LLM provider and returns the text response.
+        """
+        pass
+
+class OpenAIAdapter(BaseAdapter):
+    """
+    Adapter for OpenAI completions.
+    """
+    def __init__(self, api_key: Optional[str] = None, model: Optional[str] = None):
+        # Fallback to environment variable
+        key = api_key or os.environ.get("OPENAI_API_KEY")
+        mdl = model or "gpt-4o-mini"
+        super().__init__(key, mdl)
+
+    def generate(self, prompt: str, system: str = "") -> str:
+        if not self.api_key:
+            raise ValueError("OpenAI API Key is missing. Set OPENAI_API_KEY or configure it in husk.")
+            
+        url = "https://api.openai.com/v1/chat/completions"
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}"
+        }
+        
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": 0.2
+        }
+        
+        req = urllib.request.Request(
+            url, 
+            data=json.dumps(payload).encode("utf-8"), 
+            headers=headers,
+            method="POST"
+        )
+        
+        try:
+            with urllib.request.urlopen(req, timeout=30, context=get_ssl_context()) as response:
+                res_data = json.loads(response.read().decode("utf-8"))
+                return res_data["choices"][0]["message"]["content"]
+        except urllib.error.HTTPError as e:
+            err_body = e.read().decode("utf-8", errors="ignore")
+            raise RuntimeError(f"OpenAI HTTP Error {e.code}: {err_body}")
+        except Exception as e:
+            raise RuntimeError(f"Failed to communicate with OpenAI: {e}")
+
+class AnthropicAdapter(BaseAdapter):
+    """
+    Adapter for Anthropic messages API.
+    """
+    def __init__(self, api_key: Optional[str] = None, model: Optional[str] = None):
+        key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        mdl = model or "claude-3-5-sonnet-20241022"
+        super().__init__(key, mdl)
+
+    def generate(self, prompt: str, system: str = "") -> str:
+        if not self.api_key:
+            raise ValueError("Anthropic API Key is missing. Set ANTHROPIC_API_KEY or configure it in husk.")
+            
+        url = "https://api.anthropic.com/v1/messages"
+        headers = {
+            "content-type": "application/json",
+            "x-api-key": self.api_key,
+            "anthropic-version": "2023-06-01"
+        }
+        
+        payload = {
+            "model": self.model,
+            "max_tokens": 2048,
+            "messages": [{"role": "user", "content": prompt}]
+        }
+        if system:
+            payload["system"] = system
+            
+        req = urllib.request.Request(
+            url, 
+            data=json.dumps(payload).encode("utf-8"), 
+            headers=headers,
+            method="POST"
+        )
+        
+        try:
+            with urllib.request.urlopen(req, timeout=30, context=get_ssl_context()) as response:
+                res_data = json.loads(response.read().decode("utf-8"))
+                return res_data["content"][0]["text"]
+        except urllib.error.HTTPError as e:
+            err_body = e.read().decode("utf-8", errors="ignore")
+            raise RuntimeError(f"Anthropic HTTP Error {e.code}: {err_body}")
+        except Exception as e:
+            raise RuntimeError(f"Failed to communicate with Anthropic: {e}")
+
+class OllamaAdapter(BaseAdapter):
+    """
+    Adapter for local Ollama instances.
+    """
+    def __init__(self, host: Optional[str] = None, model: Optional[str] = None):
+        # host maps to api_key argument in base
+        hst = host or os.environ.get("OLLAMA_HOST") or "http://localhost:11434"
+        mdl = model or "llama3"
+        super().__init__(hst, mdl)
+
+    def generate(self, prompt: str, system: str = "") -> str:
+        url = f"{self.api_key}/api/generate"
+        headers = {
+            "Content-Type": "application/json"
+        }
+        
+        payload = {
+            "model": self.model,
+            "prompt": prompt,
+            "stream": False
+        }
+        if system:
+            payload["system"] = system
+            
+        req = urllib.request.Request(
+            url, 
+            data=json.dumps(payload).encode("utf-8"), 
+            headers=headers,
+            method="POST"
+        )
+        
+        try:
+            with urllib.request.urlopen(req, timeout=300, context=get_ssl_context()) as response:
+                res_data = json.loads(response.read().decode("utf-8"))
+                return res_data["response"]
+        except urllib.error.HTTPError as e:
+            err_body = e.read().decode("utf-8", errors="ignore")
+            raise RuntimeError(f"Ollama HTTP Error {e.code}: {err_body}")
+        except Exception as e:
+            import socket
+            if isinstance(e, socket.timeout) or "timed out" in str(e).lower():
+                raise RuntimeError(f"Ollama request timed out: {e}")
+            raise RuntimeError(f"Failed to communicate with Ollama at {self.api_key}: {e}. Ensure Ollama is running.")
+
+def get_adapter(provider: str, api_key: Optional[str] = None, model: Optional[str] = None) -> BaseAdapter:
+    """
+    Factory function to retrieve LLM adapter based on provider name.
+    """
+    prov = provider.lower()
+    if prov == "openai":
+        return OpenAIAdapter(api_key, model)
+    elif prov == "anthropic":
+        return AnthropicAdapter(api_key, model)
+    elif prov in ("ollama", "local"):
+        return OllamaAdapter(api_key, model) # api_key stores host URL for Ollama
+    else:
+        raise ValueError(f"Unknown LLM provider: {provider}")

husk_local-0.1.0/husk/ai/cache.py

@@ -0,0 +1,106 @@
+import os
+import json
+import hashlib
+from typing import Dict, Optional
+
+class FileCache:
+    """
+    Manages local filesystem caching for file analysis results using content SHA256 hashes.
+    Stores data in `.husk/cache.json`.
+    """
+    def __init__(self, repo_path: str):
+        self.repo_path = os.path.abspath(repo_path)
+        self.husk_dir = os.path.join(self.repo_path, ".husk")
+        self.cache_file = os.path.join(self.husk_dir, "cache.json")
+        self.cache_data: Dict[str, Dict[str, str]] = {}
+        self.load()
+
+    def load(self):
+        """
+        Loads the cache from disk.
+        """
+        if os.path.exists(self.cache_file):
+            try:
+                with open(self.cache_file, "r") as f:
+                    self.cache_data = json.load(f)
+            except Exception:
+                self.cache_data = {}
+        else:
+            self.cache_data = {}
+
+    def save(self):
+        """
+        Saves the cache to disk.
+        """
+        try:
+            os.makedirs(self.husk_dir, exist_ok=True)
+            with open(self.cache_file, "w") as f:
+                json.dump(self.cache_data, f, indent=2)
+        except Exception:
+            pass
+
+    @staticmethod
+    def compute_sha256(file_path: str) -> str:
+        """
+        Computes the SHA256 hash of a file's content.
+        """
+        if not os.path.exists(file_path):
+            return ""
+        hasher = hashlib.sha256()
+        with open(file_path, "rb") as f:
+            for chunk in iter(lambda: f.read(4096), b""):
+                hasher.update(chunk)
+        return hasher.hexdigest()
+
+    def get_summary(self, rel_path: str, file_path: str) -> Optional[str]:
+        """
+        Retrieves the cached summary for a file if the content hash matches.
+        """
+        sha = self.compute_sha256(file_path)
+        if not sha:
+            return None
+            
+        entry = self.cache_data.get(rel_path)
+        if entry and entry.get("sha256") == sha:
+            return entry.get("summary")
+        return None
+
+    def set_summary(self, rel_path: str, file_path: str, summary: str):
+        """
+        Updates the cached summary for a file.
+        """
+        sha = self.compute_sha256(file_path)
+        if not sha:
+            return
+            
+        self.cache_data[rel_path] = {
+            "sha256": sha,
+            "summary": summary
+        }
+        self.save()
+
+    def get_dir_summary(self, rel_path: str, combined_hash: str) -> Optional[str]:
+        """
+        Retrieves directory summary if the combined hash matches.
+        """
+        entry = self.cache_data.get(rel_path)
+        if entry and entry.get("sha256") == combined_hash:
+            return entry.get("summary")
+        return None
+
+    def set_dir_summary(self, rel_path: str, combined_hash: str, summary: str):
+        """
+        Sets directory summary with combined hash.
+        """
+        self.cache_data[rel_path] = {
+            "sha256": combined_hash,
+            "summary": summary
+        }
+        self.save()
+
+    def clear(self):
+        """
+        Clears the cache data.
+        """
+        self.cache_data = {}
+        self.save()

husk_local-0.1.0/husk/ai/estimator.py

@@ -0,0 +1,66 @@
+from typing import Dict, Tuple
+
+# Pricing per 1,000,000 tokens (in USD)
+MODEL_PRICING: Dict[str, Dict[str, float]] = {
+    # OpenAI
+    "gpt-4o-mini": {"input": 0.15, "output": 0.60},
+    "gpt-4o": {"input": 2.50, "output": 10.00},
+    # Anthropic
+    "claude-3-5-sonnet-20241022": {"input": 3.00, "output": 15.00},
+    "claude-3-5-haiku-20241022": {"input": 0.80, "output": 4.00},
+    # Ollama / Local
+    "llama3": {"input": 0.0, "output": 0.0},
+    "mistral": {"input": 0.0, "output": 0.0},
+}
+
+class TokenEstimator:
+    """
+    Handles local token estimation and cost calculation for LLM processing.
+    """
+    def __init__(self, model_name: str):
+        self.model_name = model_name
+        self.pricing = MODEL_PRICING.get(model_name, {"input": 0.50, "output": 1.50}) # fallback default
+
+    @staticmethod
+    def count_tokens(text: str) -> int:
+        """
+        Estimates the token count of a given text.
+        Uses tiktoken if installed, otherwise falls back to character approximation.
+        """
+        try:
+            import tiktoken
+            # cl100k_base is the standard vocabulary for GPT-4 and Claude tokens are closely aligned
+            encoding = tiktoken.get_encoding("cl100k_base")
+            return len(encoding.encode(text))
+        except ImportError:
+            # Fallback approximation: ~4 characters per token
+            return len(text) // 4
+
+    def calculate_cost(self, total_tokens: int, estimated_completion_ratio: float = 0.25) -> Tuple[float, int, int]:
+        """
+        Calculates the estimated cost (in USD) for processing total_tokens.
+        
+        Args:
+            total_tokens: Number of prompt/input tokens.
+            estimated_completion_ratio: Multiplier to estimate completion output tokens.
+            
+        Returns:
+            Tuple: (Estimated Cost USD, Input Tokens, Output Tokens)
+        """
+        input_tokens = total_tokens
+        output_tokens = int(total_tokens * estimated_completion_ratio)
+        
+        input_cost = (input_tokens / 1_000_000) * self.pricing["input"]
+        output_cost = (output_tokens / 1_000_000) * self.pricing["output"]
+        
+        total_cost = input_cost + output_cost
+        return total_cost, input_tokens, output_tokens
+
+    @staticmethod
+    def format_cost(cost_usd: float) -> str:
+        """
+        Formats cost in a user-friendly way.
+        """
+        if cost_usd < 0.01:
+            return f"${cost_usd:.5f}"
+        return f"${cost_usd:.2f}"