local-llm-wrapper 26.4__py3-none-any.whl

local_llm_wrapper/errors.py

@@ -0,0 +1,31 @@
+"""
+Standardized exception types for the LLM wrapper.
+"""
+
+from __future__ import annotations
+
+#============================================
+
+
+class LLMError(RuntimeError):
+	"""
+	Base class for LLM wrapper errors.
+	"""
+
+
+class TransportUnavailableError(LLMError):
+	"""
+	Raised when a transport cannot be used on this machine.
+	"""
+
+
+class ContextWindowError(LLMError):
+	"""
+	Raised when the prompt exceeds a model context window.
+	"""
+
+
+class GuardrailRefusalError(LLMError):
+	"""
+	Raised when a model refuses a prompt due to safety/guardrails.
+	"""

local_llm_wrapper/llm.py

@@ -0,0 +1,46 @@
+"""
+Convenience facade for local_llm_wrapper.
+
+External callers can use `import local_llm_wrapper.llm as llm` to access
+the most common names from a single import.
+"""
+
+from __future__ import annotations
+
+from local_llm_wrapper.errors import (
+	ContextWindowError,
+	GuardrailRefusalError,
+	LLMError,
+	TransportUnavailableError,
+)
+from local_llm_wrapper.llm_client import LLMClient
+from local_llm_wrapper.llm_parsers import RenameResult, SortResult
+from local_llm_wrapper.llm_utils import (
+	apple_models_available,
+	choose_model,
+	extract_xml_tag_content,
+	get_vram_size_in_gb,
+	sanitize_filename,
+	total_ram_bytes,
+)
+from local_llm_wrapper.transports.apple import AppleTransport
+from local_llm_wrapper.transports.ollama import OllamaTransport
+
+# Re-exports are intentional; __all__ suppresses pyflakes unused-import warnings.
+__all__ = [
+	"AppleTransport",
+	"ContextWindowError",
+	"GuardrailRefusalError",
+	"LLMClient",
+	"LLMError",
+	"OllamaTransport",
+	"RenameResult",
+	"SortResult",
+	"TransportUnavailableError",
+	"apple_models_available",
+	"choose_model",
+	"extract_xml_tag_content",
+	"get_vram_size_in_gb",
+	"sanitize_filename",
+	"total_ram_bytes",
+]

local_llm_wrapper/llm_client.py

@@ -0,0 +1,82 @@
+"""
+Public client wrapper for the local LLM engine.
+"""
+
+from __future__ import annotations
+
+# local repo modules
+from local_llm_wrapper.llm_engine import LLMEngine
+from local_llm_wrapper.llm_parsers import RenameResult, SortResult
+from local_llm_wrapper.llm_prompts import SortItem
+from local_llm_wrapper.transports.base import LLMTransport
+
+#============================================
+
+
+class LLMClient:
+	"""
+	Public entry point for local LLM usage.
+	"""
+
+	def __init__(
+		self,
+		transports: list[LLMTransport],
+		*,
+		context: str | None = None,
+		quiet: bool = False,
+	) -> None:
+		self._engine = LLMEngine(
+			transports=transports,
+			context=context,
+			quiet=quiet,
+		)
+
+	#============================================
+	def generate(
+		self,
+		prompt: str | None = None,
+		*,
+		messages: list[dict[str, str]] | None = None,
+		purpose: str | None = None,
+		max_tokens: int = 1200,
+	) -> str:
+		return self._engine.generate(
+			prompt,
+			messages=messages,
+			purpose=purpose,
+			max_tokens=max_tokens,
+		)
+
+	#============================================
+	def rename(self, current_name: str, metadata: dict) -> RenameResult:
+		return self._engine.rename(current_name, metadata)
+
+	#============================================
+	def sort(self, files: list[SortItem | dict]) -> SortResult:
+		items: list[SortItem] = []
+		for item in files:
+			if isinstance(item, SortItem):
+				items.append(item)
+				continue
+			if isinstance(item, dict):
+				required_keys = ("path", "name", "ext", "description")
+				for key in required_keys:
+					if key not in item:
+						raise ValueError(
+							"Sort items require path, name, ext, and description."
+						)
+				path = item["path"]
+				name = item["name"]
+				ext = item["ext"]
+				description = item["description"]
+				items.append(
+					SortItem(
+						path=path,
+						name=name,
+						ext=ext,
+						description=description,
+					)
+				)
+				continue
+			raise TypeError("Sort items must be SortItem or dict.")
+		return self._engine.sort(items)

local_llm_wrapper/llm_engine.py

@@ -0,0 +1,293 @@
+"""
+Backend-agnostic LLM engine with fallback and strict parsing.
+"""
+
+from __future__ import annotations
+
+# Standard Library
+from dataclasses import dataclass
+from typing import cast
+
+# local repo modules
+from local_llm_wrapper.errors import TransportUnavailableError
+from local_llm_wrapper.llm_parsers import ParseError, KeepResult, RenameResult, SortResult, parse_keep_response, parse_rename_response, parse_sort_response
+from local_llm_wrapper.llm_prompts import (
+	KeepRequest,
+	RenameRequest,
+	SortItem,
+	SortRequest,
+	RENAME_EXAMPLE_OUTPUT,
+	KEEP_EXAMPLE_OUTPUT,
+	SORT_EXAMPLE_OUTPUT,
+	build_format_fix_prompt,
+	build_keep_prompt,
+	build_rename_prompt,
+	build_rename_prompt_minimal,
+	build_sort_prompt,
+)
+from local_llm_wrapper.llm_utils import (
+	compute_stem_features,
+	_ensure_text_prompt,
+	_ensure_chat_messages,
+	format_chat_prompt,
+	_is_guardrail_error,
+	_is_context_window_error,
+	_print_llm,
+	log_parse_failure,
+	normalize_reason,
+	sanitize_filename,
+)
+from local_llm_wrapper.transports.base import LLMTransport
+
+#============================================
+
+
+@dataclass(slots=True)
+class LLMEngine:
+	transports: list[LLMTransport]
+	context: str | None = None
+	quiet: bool = False
+
+	#============================================
+	def generate(
+		self,
+		prompt: str | None = None,
+		*,
+		messages: list[dict[str, str]] | None = None,
+		purpose: str | None = None,
+		max_tokens: int = 1200,
+	) -> str:
+		if prompt is None and messages is None:
+			raise ValueError("Prompt or messages are required.")
+		if prompt is not None and messages is not None:
+			raise ValueError("Provide prompt or messages, not both.")
+		text_prompt: str | None = None
+		chat_messages: list[dict[str, str]] | None = None
+		if messages is not None:
+			chat_messages = _ensure_chat_messages(messages)
+		else:
+			text_prompt = _ensure_text_prompt(prompt)
+		return self._generate_with_fallback(
+			text_prompt,
+			messages=chat_messages,
+			purpose=purpose or "general response",
+			max_tokens=max_tokens,
+			retry_prompt=None,
+		)
+
+	#============================================
+	def rename(self, current_name: str, metadata: dict) -> RenameResult:
+		req = RenameRequest(metadata=metadata, current_name=current_name, context=self.context)
+		prompt = build_rename_prompt(req)
+		raw = self._generate_with_fallback(
+			prompt,
+			messages=None,
+			purpose="filename based on content",
+			max_tokens=200,
+			retry_prompt=build_rename_prompt_minimal(req),
+		)
+		result = self._parse_with_retry(
+			lambda text: parse_rename_response(text),
+			prompt,
+			RENAME_EXAMPLE_OUTPUT,
+			raw,
+			purpose="filename based on content",
+			max_tokens=200,
+		)
+		result.new_name = sanitize_filename(result.new_name)
+		result.reason = normalize_reason(result.reason)
+		return result
+
+	#============================================
+	def stem_action(self, original_stem: str, suggested_name: str, extension: str | None = None) -> KeepResult:
+		features = compute_stem_features(original_stem, suggested_name)
+		req = KeepRequest(
+			original_stem=original_stem,
+			suggested_name=suggested_name,
+			extension=extension,
+			features=features,
+		)
+		prompt = build_keep_prompt(req)
+		raw = self._generate_with_fallback(
+			prompt,
+			messages=None,
+			purpose="how to handle the original filename stem",
+			max_tokens=120,
+			retry_prompt=None,
+		)
+		result = self._parse_with_retry(
+			lambda text: parse_keep_response(text, original_stem),
+			prompt,
+			KEEP_EXAMPLE_OUTPUT,
+			raw,
+			purpose="how to handle the original filename stem",
+			max_tokens=120,
+		)
+		result.reason = normalize_reason(result.reason)
+		return result
+
+	#============================================
+	def sort(self, files: list[SortItem]) -> SortResult:
+		if not files:
+			return SortResult(assignments={}, raw_text="")
+		assignments: dict[str, str] = {}
+		reasons: dict[str, str] = {}
+		last_raw = ""
+		for item in files:
+			req = SortRequest(files=[item], context=self.context)
+			prompt = build_sort_prompt(req)
+			raw = self._generate_with_fallback(
+				prompt,
+				messages=None,
+				purpose="category assignment",
+				max_tokens=120,
+				retry_prompt=None,
+			)
+			result = self._parse_with_retry(
+				lambda text: parse_sort_response(text, [item.path]),
+				prompt,
+				SORT_EXAMPLE_OUTPUT,
+				raw,
+				purpose="category assignment",
+				max_tokens=120,
+			)
+			assignments.update(result.assignments)
+			for path, reason in result.reasons.items():
+				reasons[path] = normalize_reason(reason)
+			last_raw = result.raw_text
+		return SortResult(assignments=assignments, reasons=reasons, raw_text=last_raw)
+
+	#============================================
+	def _generate_with_fallback(
+		self,
+		prompt: str | None,
+		*,
+		messages: list[dict[str, str]] | None,
+		purpose: str,
+		max_tokens: int,
+		retry_prompt: str | None,
+	) -> str:
+		last_exc: Exception | None = None
+		for idx, transport in enumerate(self.transports):
+			try:
+				if not self.quiet:
+					_print_llm(f"asking {transport.name} for {purpose}")
+				return self._generate_on_transport(
+					transport,
+					prompt,
+					messages,
+					purpose,
+					max_tokens,
+				)
+			except Exception as exc:
+				last_exc = exc
+				if isinstance(exc, TransportUnavailableError):
+					continue
+				if _is_guardrail_error(exc) or _is_context_window_error(exc):
+					if retry_prompt and idx == 0:
+						try:
+							if not self.quiet:
+								_print_llm(
+									f"retrying {transport.name} with minimal prompt for {purpose}"
+								)
+							return self._generate_on_transport(
+								transport,
+								retry_prompt,
+								None,
+								purpose,
+								max_tokens,
+							)
+						except Exception as retry_exc:
+							last_exc = retry_exc
+							if _is_guardrail_error(retry_exc) or _is_context_window_error(retry_exc):
+								continue
+							raise
+					continue
+				raise
+		if last_exc:
+			raise last_exc
+		raise TransportUnavailableError("No LLM transports available.")
+
+	#============================================
+	def _parse_with_retry(
+		self,
+		parser,
+		original_prompt: str,
+		example_output: str,
+		raw_text: str,
+		*,
+		purpose: str,
+		max_tokens: int,
+	):
+		try:
+			return parser(raw_text)
+		except ParseError as exc:
+			excerpt = " ".join(raw_text.split())[:160]
+			if not self.quiet:
+				print(f"[WHY] parse_error: {exc} (excerpt: {excerpt})")
+			log_parse_failure(
+				purpose=purpose,
+				error=exc,
+				raw_text=exc.raw_text or raw_text,
+				prompt=original_prompt,
+				stage="initial",
+			)
+			fix_prompt = build_format_fix_prompt(example_output)
+			last_parse: ParseError | None = None
+			last_transport: Exception | None = None
+			last_fixed: str | None = None
+			for transport in self.transports:
+				try:
+					if not self.quiet:
+						_print_llm(f"asking {transport.name} for {purpose} (format fix)")
+					fixed = self._generate_on_transport(
+						transport,
+						fix_prompt,
+						None,
+						f"{purpose} (format fix)",
+						max_tokens,
+					)
+					last_fixed = fixed
+				except Exception as transport_exc:
+					if _is_guardrail_error(transport_exc):
+						last_transport = transport_exc
+						continue
+					last_transport = transport_exc
+					continue
+				try:
+					return parser(fixed)
+				except ParseError as parse_exc:
+					last_parse = parse_exc
+					log_parse_failure(
+						purpose=purpose,
+						error=parse_exc,
+						raw_text=parse_exc.raw_text or fixed,
+						prompt=fix_prompt,
+						stage=f"format fix ({transport.name})",
+					)
+					continue
+			if last_parse:
+				text = last_fixed or raw_text
+				raise ParseError(str(last_parse), raw_text=text)
+			if last_transport:
+				raise last_transport
+			raise ParseError("Format-fix retry failed.")
+
+	#============================================
+	def _generate_on_transport(
+		self,
+		transport: LLMTransport,
+		prompt: str | None,
+		messages: list[dict[str, str]] | None,
+		purpose: str,
+		max_tokens: int,
+	) -> str:
+		if messages is not None:
+			generate_chat = getattr(transport, "generate_chat", None)
+			if callable(generate_chat):
+				result = generate_chat(messages, purpose=purpose, max_tokens=max_tokens)
+				return cast(str, result)
+			prompt = format_chat_prompt(messages)
+		if prompt is None:
+			raise ValueError("Prompt or messages are required.")
+		return transport.generate(prompt, purpose=purpose, max_tokens=max_tokens)

local_llm_wrapper/llm_parsers.py

@@ -0,0 +1,173 @@
+"""
+Backend-agnostic response parsers.
+"""
+
+from __future__ import annotations
+
+# Standard Library
+from dataclasses import dataclass, field
+import html
+import re
+
+# local repo modules
+
+#============================================
+
+
+class ParseError(RuntimeError):
+	"""
+	Raised when a model response does not match required tags.
+	"""
+
+	def __init__(self, message: str, raw_text: str = "") -> None:
+		super().__init__(message)
+		self.raw_text = raw_text
+
+
+@dataclass(slots=True)
+class RenameResult:
+	new_name: str
+	reason: str
+	raw_text: str
+
+
+@dataclass(slots=True)
+class KeepResult:
+	stem_action: str
+	reason: str
+	raw_text: str
+
+
+@dataclass(slots=True)
+class SortResult:
+	assignments: dict[str, str]
+	raw_text: str
+	reasons: dict[str, str] = field(default_factory=dict)
+
+
+_CODE_FENCE_RE = re.compile(r"```[a-zA-Z0-9_+-]*\n(.*?)```", re.DOTALL)
+_TAG_NAME_RE = re.compile(r"^[a-zA-Z0-9_:-]+$")
+
+
+def _strip_code_fences(text: str) -> str:
+	if not text:
+		return ""
+	cleaned = text.strip()
+	if "```" not in cleaned:
+		return cleaned
+	def _unwrap(match: re.Match) -> str:
+		return match.group(1)
+	cleaned = _CODE_FENCE_RE.sub(_unwrap, cleaned)
+	return cleaned.strip()
+
+
+def _coerce_response_body(text: str) -> str:
+	cleaned = _strip_code_fences(text).strip().strip('"').strip("'")
+	if "<" in cleaned:
+		unescaped = html.unescape(cleaned)
+		if unescaped:
+			cleaned = unescaped
+	return cleaned
+
+
+def _find_tag_values(text: str, tag: str) -> list[str]:
+	pattern = re.compile(
+		rf"<{tag}\b[^>]*>(.*?)</{tag}>",
+		flags=re.IGNORECASE | re.DOTALL,
+	)
+	return [match.strip() for match in pattern.findall(text)]
+
+
+def parse_tag_response(text: str, tag: str) -> str:
+	response_body = _coerce_response_body(text)
+	if not response_body:
+		raise ParseError("Missing required tags in response.", text)
+	if not isinstance(tag, str):
+		raise TypeError("Tag name must be a string.")
+	tag_name = tag.strip()
+	if not tag_name:
+		raise ValueError("Tag name must not be empty.")
+	if not _TAG_NAME_RE.match(tag_name):
+		raise ValueError("Tag name must use letters, numbers, underscores, dashes, or colons.")
+	values = _find_tag_values(response_body, tag_name)
+	if not values:
+		raise ParseError(f"Missing <{tag_name}> in response.", text)
+	if len(values) > 1:
+		raise ParseError(f"Duplicate <{tag_name}> tags in response.", text)
+	return values[0]
+
+
+def parse_rename_response(text: str) -> RenameResult:
+	response_body = _coerce_response_body(text)
+	if not response_body:
+		raise ParseError("Missing required tags in rename response.", text)
+	new_names = _find_tag_values(response_body, "new_name")
+	if not new_names:
+		raise ParseError("Missing <new_name> in rename response.", text)
+	if len(new_names) > 1:
+		raise ParseError("Duplicate <new_name> tags in rename response.", text)
+	reasons = _find_tag_values(response_body, "reason")
+	if len(reasons) > 1:
+		raise ParseError("Duplicate <reason> tags in rename response.", text)
+	new_name = new_names[0]
+	reason = reasons[0] if reasons else ""
+	return RenameResult(new_name=new_name, reason=reason, raw_text=text)
+
+def parse_keep_response(
+	text: str, original_stem: str
+) -> KeepResult:
+	response_body = _coerce_response_body(text)
+	if not response_body:
+		raise ParseError("Missing required tags in keep response.", text)
+	stem_actions = _find_tag_values(response_body, "stem_action")
+	if len(stem_actions) > 1:
+		raise ParseError("Duplicate <stem_action> tags in keep response.", text)
+	reason_values = _find_tag_values(response_body, "reason")
+	if not reason_values:
+		raise ParseError("Missing <reason> in keep response.", text)
+	if len(reason_values) > 1:
+		raise ParseError("Duplicate <reason> tags in keep response.", text)
+	reason = reason_values[0].strip()
+	if stem_actions:
+		stem_action = stem_actions[0].strip().lower()
+	else:
+		keep_values = _find_tag_values(response_body, "keep_original")
+		if not keep_values:
+			raise ParseError("Missing <stem_action> in keep response.", text)
+		if len(keep_values) > 1:
+			raise ParseError("Duplicate <keep_original> tags in keep response.", text)
+		keep_text = keep_values[0].strip().lower()
+		stem_action = (
+			"keep"
+			if (keep_text.startswith("t") or keep_text == "1" or keep_text == "yes")
+			else "drop"
+		)
+	reason = reason.replace('\\"', '"').replace("\\'", "'")
+	if stem_action not in {"drop", "keep", "normalize"}:
+		raise ParseError("Invalid <stem_action> value in keep response.", text)
+	if not reason:
+		raise ParseError("Missing <reason> in keep response.", text)
+	return KeepResult(stem_action=stem_action, reason=reason, raw_text=text)
+
+
+def parse_sort_response(text: str, expected_paths: list[str]) -> SortResult:
+	response_body = _coerce_response_body(text)
+	if not response_body:
+		raise ParseError("Missing required tags in sort response.", text)
+	if len(expected_paths) != 1:
+		raise ParseError("Sort responses only support a single file.", text)
+	categories = _find_tag_values(response_body, "category")
+	if not categories:
+		raise ParseError("Missing <category> in sort response.", text)
+	if len(categories) > 1:
+		raise ParseError("Duplicate <category> tags in sort response.", text)
+	category = categories[0].strip()
+	reasons = _find_tag_values(response_body, "reason")
+	if len(reasons) > 1:
+		raise ParseError("Duplicate <reason> tags in sort response.", text)
+	reason = reasons[0].strip() if reasons else ""
+	return SortResult(
+		assignments={expected_paths[0]: category},
+		reasons={expected_paths[0]: reason} if reason else {},
+		raw_text=text,
+	)