power-loop 0.2.0__py3-none-any.whl

llm_client/llm_utils.py

@@ -0,0 +1,205 @@
+"""
+Lightweight LLM utilities (no LangChain dependency).
+
+Goals:
+- Provide a unified return object (raw_text / json_data / token_usage / errors)
+- Provide robust JSON extraction similar to agent-psychology (strip fences, extract substring, fallback)
+- Keep call sites (LangGraph nodes) minimal and consistent
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from .interface import LLMResponse
+
+
+def log_llm_json_result(
+    logger: logging.Logger,
+    result: LLMResponse,
+    *,
+    level: str = "info",
+    prefix: str = "",
+    include_debug: bool = False,
+    max_raw_chars: int = 600,
+    max_content_chars: int = 600,
+) -> None:
+    """
+    Convenience helper to log a result with a consistent format.
+    """
+    msg = (prefix + " " if prefix else "") + result.to_log_str(
+        max_raw_chars=max_raw_chars,
+        max_content_chars=max_content_chars,
+        include_debug=include_debug,
+    )
+    fn = getattr(logger, level, None)
+    if not callable(fn):
+        fn = logger.info
+    fn(msg)
+
+
+def strip_code_fences(text: str) -> str:
+    stripped = (text or "").strip()
+    if not stripped.startswith("```"):
+        return stripped
+
+    lines = stripped.splitlines()
+    if not lines:
+        return stripped
+
+    # drop first fence line (``` or ```json etc)
+    lines = lines[1:]
+    # drop trailing fences
+    while lines and lines[-1].strip() == "```":
+        lines = lines[:-1]
+    return "\n".join(lines).strip()
+
+
+def extract_json_substring(text: str) -> str | None:
+    """
+    Extract the first top-level JSON object substring by brace matching.
+    """
+    if not text:
+        return None
+    start = text.find("{")
+    if start == -1:
+        return None
+    depth = 0
+    for i in range(start, len(text)):
+        c = text[i]
+        if c == "{":
+            depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start : i + 1]
+    return None
+
+
+def _try_json_loads(s: str) -> tuple[dict[str, Any] | None, str | None]:
+    try:
+        obj = json.loads(s)
+        if isinstance(obj, dict):
+            return obj, None
+        return None, "parsed_json_is_not_object"
+    except Exception as e:
+        return None, f"json_decode_error:{e}"
+
+
+def parse_json_from_model_output(raw_text: str) -> tuple[dict[str, Any], str | None]:
+    """
+    Parse JSON from model output with multi-step fallback.
+    Returns (json_data, error_message).
+    """
+    text = (raw_text or "").strip()
+    if not text:
+        return {}, "empty_response"
+
+    # Strategy 1: direct parse
+    obj, err = _try_json_loads(text)
+    if obj is not None:
+        return obj, None
+
+    # Strategy 2: strip code fences
+    cleaned = strip_code_fences(text)
+    if cleaned != text:
+        obj2, err2 = _try_json_loads(cleaned)
+        if obj2 is not None:
+            return obj2, None
+
+    # Strategy 3: extract substring by braces
+    sub = extract_json_substring(cleaned)
+    if sub:
+        obj3, err3 = _try_json_loads(sub)
+        if obj3 is not None:
+            return obj3, None
+
+    # Strategy 4: simple repairs (trailing commas)
+    repaired = re.sub(r",\s*([}\]])", r"\1", sub or cleaned)
+    if repaired and repaired != (sub or cleaned):
+        obj4, err4 = _try_json_loads(repaired)
+        if obj4 is not None:
+            return obj4, None
+
+    return {}, err
+
+
+def parse_json_from_model_output_detailed(raw_text: str) -> LLMResponse:
+    """
+    Detailed parser that returns a rich `LLMResponse` with intermediate artifacts.
+    This is the recommended API for new code.
+    """
+    raw = (raw_text or "")
+    text = raw.strip()
+    res = LLMResponse(raw_text=raw)
+
+    if not text:
+        res.parse_error = "empty_response"
+        res.debug = {"strategy": "empty"}
+        return res
+
+    # Attempt raw direct parse (raw_json_data)
+    raw_obj, raw_err = _try_json_loads(text)
+    res.raw_json_data = raw_obj or {}
+    res.raw_json_error = raw_err
+
+    if raw_obj is not None:
+        # In this case, business json is the same as raw json.
+        res.content_text = text
+        res.json_data = raw_obj
+        res.parse_error = None
+        res.debug = {"strategy": "direct"}
+        return res
+
+    cleaned = strip_code_fences(text)
+    res.debug["cleaned_text"] = cleaned
+
+    # Try cleaned direct parse
+    if cleaned != text:
+        obj2, err2 = _try_json_loads(cleaned)
+        if obj2 is not None:
+            res.content_text = cleaned
+            res.json_data = obj2
+            res.parse_error = None
+            res.debug["strategy"] = "strip_code_fences"
+            return res
+
+    # Extract substring
+    sub = extract_json_substring(cleaned)
+    res.debug["json_substring"] = sub or ""
+    if sub:
+        obj3, err3 = _try_json_loads(sub)
+        if obj3 is not None:
+            res.content_text = sub
+            res.json_data = obj3
+            res.parse_error = None
+            res.debug["strategy"] = "extract_substring"
+            return res
+
+    # Repairs: trailing commas
+    candidate = sub or cleaned
+    repaired = re.sub(r",\s*([}\]])", r"\1", candidate)
+    res.debug["repaired_text"] = repaired
+    if repaired and repaired != candidate:
+        obj4, err4 = _try_json_loads(repaired)
+        if obj4 is not None:
+            res.content_text = repaired
+            res.json_data = obj4
+            res.parse_error = None
+            res.debug["strategy"] = "repair_trailing_commas"
+            return res
+
+    # All failed
+    res.content_text = candidate
+    res.json_data = {}
+    res.parse_error = raw_err or "unable_to_parse_json"
+    res.debug["strategy"] = "failed"
+    return res
+
+
+# Note: do not add extra aliases here; keep naming consistent at the interfaces layer.
+
+

llm_client/multimodal.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import base64
+import mimetypes
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .capabilities import ModelCapabilities
+
+try:
+    from pypdf import PdfReader
+except Exception:  # pragma: no cover
+    PdfReader = None  # type: ignore[assignment,misc]
+
+
+MAX_PDF_TEXT_CHARS = 24_000
+
+
+@dataclass(frozen=True)
+class AttachmentRef:
+    path: str
+    filename: str
+    mime_type: str
+    kind: str
+
+
+@dataclass(frozen=True)
+class PreparedAttachment:
+    ref: AttachmentRef
+    text_fallback: str = ""
+    rendered_parts: tuple[dict[str, Any], ...] = ()
+    strategy: str = "text"
+
+
+def _guess_mime_type(path: Path) -> str:
+    mime_type, _ = mimetypes.guess_type(str(path))
+    return mime_type or "application/octet-stream"
+
+
+def create_attachment_ref(path: str | Path) -> dict[str, Any]:
+    file_path = Path(path).expanduser().resolve()
+    mime_type = _guess_mime_type(file_path)
+    kind = "other"
+    if mime_type.startswith("image/"):
+        kind = "image"
+    elif mime_type == "application/pdf":
+        kind = "pdf"
+    ref = AttachmentRef(
+        path=str(file_path),
+        filename=file_path.name,
+        mime_type=mime_type,
+        kind=kind,
+    )
+    return ref.__dict__.copy()
+
+
+def extract_text_from_content(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return str(content or "")
+
+    parts: list[str] = []
+    for block in content:
+        if isinstance(block, str):
+            parts.append(block)
+            continue
+        if not isinstance(block, dict):
+            parts.append(str(block))
+            continue
+
+        block_type = block.get("type")
+        if block_type == "text":
+            parts.append(str(block.get("text") or ""))
+            continue
+        if block_type == "attachment":
+            attachment = block.get("attachment") or {}
+            filename = attachment.get("filename") or Path(str(attachment.get("path") or "attachment")).name
+            parts.append(f"[Attached file: {filename}]")
+            continue
+        if "text" in block:
+            parts.append(str(block.get("text") or ""))
+    return "\n\n".join(part for part in parts if part).strip()
+
+
+def _file_to_data_url(path: Path, mime_type: str) -> str:
+    payload = base64.b64encode(path.read_bytes()).decode("ascii")
+    return f"data:{mime_type};base64,{payload}"
+
+
+def _extract_pdf_text(path: Path) -> str:
+    if PdfReader is None:
+        return ""
+
+    try:
+        reader = PdfReader(str(path))
+    except Exception:
+        return ""
+
+    pages: list[str] = []
+    for index, page in enumerate(reader.pages, start=1):
+        text = ""
+        try:
+            text = (page.extract_text() or "").strip()
+        except Exception:
+            text = ""
+        if text:
+            pages.append(f"[Page {index}]\n{text}")
+
+    return "\n\n".join(pages)[:MAX_PDF_TEXT_CHARS]
+
+
+def _render_image_attachment(ref: AttachmentRef, path: Path, capabilities: ModelCapabilities) -> PreparedAttachment:
+    if capabilities.supports_image_input and capabilities.supports_data_url:
+        part = {
+            "type": "image_url",
+            "image_url": {
+                "url": _file_to_data_url(path, ref.mime_type),
+            },
+        }
+        return PreparedAttachment(ref=ref, rendered_parts=(part,), strategy="native-image")
+
+    text = (
+        f"[Attached image: {ref.filename}]\n"
+        "The current model does not support image input, so the image was not sent natively."
+    )
+    return PreparedAttachment(
+        ref=ref,
+        text_fallback=text,
+        rendered_parts=({"type": "text", "text": text},),
+        strategy="image-unsupported",
+    )
+
+
+def _render_pdf_attachment(ref: AttachmentRef, path: Path, capabilities: ModelCapabilities) -> PreparedAttachment:
+    extracted_text = _extract_pdf_text(path)
+
+    if capabilities.supports_pdf_input_chat:
+        text = (
+            f"[Attached PDF: {ref.filename}]\n"
+            "Native PDF chat transmission is not enabled in this build, so extracted text fallback was used instead."
+        )
+        if extracted_text:
+            text = f"{text}\n\n{extracted_text}"
+        return PreparedAttachment(
+            ref=ref,
+            text_fallback=text,
+            rendered_parts=({"type": "text", "text": text},),
+            strategy="pdf-fallback-text",
+        )
+
+    if extracted_text:
+        text = f"[Attached PDF: {ref.filename}]\n\n{extracted_text}"
+        return PreparedAttachment(
+            ref=ref,
+            text_fallback=text,
+            rendered_parts=({"type": "text", "text": text},),
+            strategy="pdf-extracted-text",
+        )
+
+    text = (
+        f"[Attached PDF: {ref.filename}]\n"
+        "No readable text could be extracted from this PDF, and the current model/path does not support native PDF input."
+    )
+    return PreparedAttachment(
+        ref=ref,
+        text_fallback=text,
+        rendered_parts=({"type": "text", "text": text},),
+        strategy="pdf-unreadable",
+    )
+
+
+def prepare_attachment(ref_payload: dict[str, Any], capabilities: ModelCapabilities) -> PreparedAttachment:
+    ref = AttachmentRef(
+        path=str(ref_payload.get("path") or ""),
+        filename=str(ref_payload.get("filename") or Path(str(ref_payload.get("path") or "attachment")).name),
+        mime_type=str(ref_payload.get("mime_type") or "application/octet-stream"),
+        kind=str(ref_payload.get("kind") or "other"),
+    )
+    path = Path(ref.path)
+
+    if ref.kind == "image":
+        return _render_image_attachment(ref, path, capabilities)
+    if ref.kind == "pdf":
+        return _render_pdf_attachment(ref, path, capabilities)
+
+    text = f"[Attached file: {ref.filename}] Unsupported attachment type: {ref.mime_type}"
+    return PreparedAttachment(
+        ref=ref,
+        text_fallback=text,
+        rendered_parts=({"type": "text", "text": text},),
+        strategy="unsupported-file",
+    )
+
+
+def render_message_content(content: Any, role: str, capabilities: ModelCapabilities) -> Any:
+    if not isinstance(content, list) or role != "user":
+        return content
+
+    rendered: list[dict[str, Any]] = []
+    debug_strategies: list[str] = []
+    for block in content:
+        if isinstance(block, str):
+            rendered.append({"type": "text", "text": block})
+            continue
+        if not isinstance(block, dict):
+            rendered.append({"type": "text", "text": str(block)})
+            continue
+
+        block_type = block.get("type")
+        if block_type == "text":
+            text = str(block.get("text") or "")
+            if text:
+                rendered.append({"type": "text", "text": text})
+            continue
+
+        if block_type == "attachment":
+            prepared = prepare_attachment(block.get("attachment") or {}, capabilities)
+            debug_strategies.append(prepared.strategy)
+            rendered.extend(prepared.rendered_parts)
+            continue
+
+        rendered.append(block)
+
+    text_parts = [part.get("text", "") for part in rendered if isinstance(part, dict) and part.get("type") == "text"]
+    non_text_parts = [part for part in rendered if not (isinstance(part, dict) and part.get("type") == "text")]
+
+    if not non_text_parts:
+        return "\n\n".join(text for text in text_parts if text).strip()
+
+    if text_parts:
+        merged: list[dict[str, Any]] = [{"type": "text", "text": "\n\n".join(text for text in text_parts if text).strip()}]
+        merged.extend(non_text_parts)
+        return [part for part in merged if not (part.get("type") == "text" and not part.get("text"))]
+
+    return non_text_parts