mcp-plesk-dev-docs 0.4.2__py3-none-any.whl

plesk_unified/chunking.py

@@ -0,0 +1,360 @@
+import hashlib
+import re
+import logging
+from typing import Dict, List, Optional
+
+logger = logging.getLogger("plesk_unified")
+
+# Bump this version whenever the chunking logic or context injection changes
+# to force a re-embedding of changed chunks while preserving identical ones.
+CHUNK_VERSION = "v15"
+
+# Global registry for tree-sitter languages to avoid repeated lookups
+_TS_LANGS = {}
+
+
+def _get_ts_lang(lang_name: str):
+    """Get or load a tree-sitter language."""
+    if lang_name in _TS_LANGS:
+        return _TS_LANGS[lang_name]
+
+    try:
+        import tree_sitter_languages
+
+        lang = tree_sitter_languages.get_language(lang_name)
+        _TS_LANGS[lang_name] = lang
+        return lang
+    except Exception:
+        return None
+
+
+def _get_ts_query(lang_name: str) -> Optional[str]:
+    """Return the tree-sitter query string for the given language."""
+    if lang_name == "php":
+        return """
+            (class_declaration) @decl
+            (function_declaration) @decl
+            (method_declaration) @decl
+            (interface_declaration) @decl
+            (trait_declaration) @decl
+        """
+    if lang_name in ("javascript", "typescript"):
+        return """
+            (class_declaration) @decl
+            (function_declaration) @decl
+            (method_definition) @decl
+            (export_statement) @decl
+        """
+    return None
+
+
+def chunk_by_ast(
+    text: str, lang_name: str, max_chars: int = 1500, overlap: int = 200
+) -> Optional[List[str]]:
+    """Chunk code using tree-sitter AST nodes (classes, functions, methods)."""
+    lang = _get_ts_lang(lang_name)
+    query_str = _get_ts_query(lang_name)
+    if not lang or not query_str:
+        return None
+
+    try:
+        from tree_sitter import Parser
+
+        parser = Parser()
+        parser.set_language(lang)
+        tree = parser.parse(bytes(text, "utf-8"))
+        query = lang.query(query_str)
+        captures = query.captures(tree.root_node)
+
+        if not captures:
+            return None
+
+        chunks = []
+        last_end = 0
+
+        for node, _ in captures:
+            # Handle gap before this node
+            if node.start_byte > last_end:
+                gap = text[last_end : node.start_byte].strip()
+                if gap:
+                    chunks.extend(
+                        chunk_by_chars(gap, max_chars, overlap)
+                        if len(gap) > max_chars
+                        else [gap]
+                    )
+
+            block = text[node.start_byte : node.end_byte].strip()
+            if block:
+                chunks.extend(
+                    chunk_by_chars(block, max_chars, overlap)
+                    if len(block) > max_chars
+                    else [block]
+                )
+            last_end = node.end_byte
+
+        # Handle tail
+        if last_end < len(text):
+            tail = text[last_end:].strip()
+            if tail:
+                chunks.extend(
+                    chunk_by_chars(tail, max_chars, overlap)
+                    if len(tail) > max_chars
+                    else [tail]
+                )
+
+        return chunks
+    except Exception as e:
+        logger.warning("AST chunking failed for %s: %s", lang_name, e)
+        return None
+
+
+def chunk_by_chars(text: str, size: int = 1500, overlap: int = 200) -> List[str]:
+    """Chunk text by fixed character window with overlap."""
+    if not text:
+        return []
+    chunks: List[str] = []
+    start = 0
+    n = len(text)
+    step = max(1, size - overlap)
+    while start < n:
+        end = min(n, start + size)
+        chunk = text[start:end].strip()
+        if chunk:
+            chunks.append(chunk)
+        start += step
+    return chunks
+
+
+def chunk_by_lines(text: str, chunk_size: int, overlap: int = 0) -> List[str]:
+    """Chunk text by lines with optional overlap.
+
+    `chunk_size` is number of lines per chunk. `overlap` is number of lines
+    to overlap between consecutive chunks.
+    """
+    if not text:
+        return []
+    lines = text.splitlines()
+    if not lines:
+        return []
+    chunks: List[str] = []
+    step = max(1, chunk_size - overlap)
+    for i in range(0, len(lines), step):
+        chunk = "\n".join(lines[i : i + chunk_size])
+        if chunk.strip():
+            chunks.append(chunk)
+    return chunks
+
+
+def _split_sentences(text: str) -> List[str]:
+    """Split prose into sentences using a lightweight regex heuristic."""
+    if not text:
+        return []
+    normalized = re.sub(r"\s+", " ", text).strip()
+    if not normalized:
+        return []
+    parts = re.split(r"(?<=[.!?])\s+(?=[A-Z0-9\"'`])", normalized)
+    return [p.strip() for p in parts if p.strip()]
+
+
+def chunk_by_sentence_window(
+    text: str, window_size: int = 5, overlap: int = 2
+) -> List[str]:
+    """Build overlapping sentence windows with configurable stride.
+
+    Task C: Increased default window size to 5 for better context.
+    The stride is determined by window_size - overlap to prevent chunk explosion.
+    """
+    if not text:
+        return []
+    sentences = _split_sentences(text)
+    if not sentences:
+        return []
+    if len(sentences) <= window_size:
+        return [" ".join(sentences)]
+
+    chunks: List[str] = []
+    step = max(1, window_size - overlap)
+    for idx in range(0, len(sentences), step):
+        chunk = " ".join(sentences[idx : idx + window_size]).strip()
+        if chunk:
+            chunks.append(chunk)
+        # If this chunk already reached the end, stop to avoid redundant tail chunks
+        if idx + window_size >= len(sentences):
+            break
+    return chunks
+
+
+def chunk_php_hierarchical(
+    text: str, section_max_lines: int = 150, overlap: int = 20
+) -> List[str]:
+    """Chunk PHP by declarations, preserving docblocks and injecting context.
+
+    Task F: Improved boundary detection and block preservation.
+    Phase 5: Structural context injection for better method retrieval.
+    """
+    if not text:
+        return []
+
+    # Regex that matches PHP declarations, optionally preceded by a docblock.
+    # Pattern: (/** ... */)? (abstract|final|...)* (class|interface|trait|function)
+    boundary_regex = (
+        r"(?:/\*\*[\s\S]*?\*/\s*)?"
+        r"^\s*(?:abstract\s+|final\s+|public\s+|protected\s+|private\s+|static\s+)*"
+        r"(class|interface|trait|function)\s+([a-zA-Z0-9_]+)"
+    )
+
+    matches = list(re.finditer(boundary_regex, text, re.MULTILINE))
+
+    if not matches:
+        return chunk_by_lines(text, section_max_lines, overlap)
+
+    sections = []
+    current_class = ""
+
+    for i, match in enumerate(matches):
+        m_type = match.group(1)
+        m_name = match.group(2)
+
+        # If there's text before the first match (like <?php)
+        if i == 0 and match.start() > 0:
+            sections.append(text[0 : match.start()].strip())
+
+        # Determine header for this block
+        header = ""
+        if m_type == "function" and current_class:
+            header = f"// Context: {current_class}::{m_name}\n"
+        elif m_type in ("class", "interface", "trait"):
+            header = f"// Context: {m_type} {m_name}\n"
+            current_class = m_name
+
+        # Find end of this section
+        next_start = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        section_text = text[match.start() : next_start].strip()
+
+        if section_text:
+            sections.append(f"{header}{section_text}")
+
+    chunks: List[str] = []
+    for section in sections:
+        if not section:
+            continue
+        line_count = len(section.splitlines())
+        if line_count > section_max_lines:
+            chunks.extend(chunk_by_lines(section, section_max_lines, overlap))
+        else:
+            chunks.append(section)
+
+    return chunks
+
+
+def chunk_js_hierarchical(
+    text: str, section_max_lines: int = 60, overlap: int = 10
+) -> List[str]:
+    """Chunk JS/TS by export/class/function boundaries, preserving docblocks.
+
+    Task F: Improved boundary detection and block preservation.
+    """
+    if not text:
+        return []
+
+    # Regex for JS declarations, optionally preceded by a docblock
+    boundary_regex = (
+        r"(?:/\*\*[\s\S]*?\*/\s*)?"
+        r"^\s*(?:export\s+(?:default\s+)*)?"
+        r"(?:class|function|const|let|var|describe|test|it)\b"
+    )
+
+    sections = []
+    matches = list(re.finditer(boundary_regex, text, re.MULTILINE))
+
+    if not matches:
+        return chunk_by_lines(text, section_max_lines, overlap)
+
+    last_pos = 0
+    for match in matches:
+        if match.start() > last_pos:
+            section = text[last_pos : match.start()].strip()
+            if section:
+                sections.append(section)
+        last_pos = match.start()
+
+    if last_pos < len(text):
+        sections.append(text[last_pos:].strip())
+
+    chunks: List[str] = []
+    for section in sections:
+        line_count = len(section.splitlines())
+        if line_count > section_max_lines:
+            chunks.extend(chunk_by_lines(section, section_max_lines, overlap))
+        else:
+            chunks.append(section)
+
+    return chunks
+
+
+def build_doc_records(filename: str, chunks: List[str], meta: Dict) -> List[Dict]:
+    """Build a list of document dicts suitable for DB insertion.
+
+    Each record includes `text`, `title`, `filename`, `category`, `breadcrumb`,
+    `doctype`, `endpoint` and `summary`.
+
+    The `text` field is enriched with metadata for better retrieval.
+    """
+    records: List[Dict] = []
+    title = meta.get("title") or ""
+    breadcrumb = meta.get("breadcrumb") or ""
+    summary = meta.get("summary")
+    endpoint = meta.get("endpoint")
+
+    for i, c in enumerate(chunks):
+        # Task B & Phase 2: Prepend context to the text before embedding.
+        category = meta.get("category", "unknown").upper()
+        doctype = meta.get("doctype", "unknown")
+
+        header = f"[{category}] DocType: {doctype}\n"
+        header += f"[Title: {title} | Path: {breadcrumb}] \n"
+        if endpoint:
+            header += f"[Endpoint: {endpoint}] \n"
+        if summary:
+            header += f"[Summary: {summary}] \n"
+
+        enriched_text = f"{header}\n {c}"
+
+        # Strategy 2: Per-chunk fingerprinting
+        # Includes enriched_text (which has all context) and logic version.
+        h = hashlib.sha256()
+        h.update(f"{CHUNK_VERSION}:{enriched_text}".encode("utf-8"))
+        chunk_hash = h.hexdigest()
+
+        records.append(
+            {
+                "text": enriched_text,
+                "title": title,
+                "filename": filename,
+                "category": meta.get("category"),
+                "breadcrumb": breadcrumb,
+                "doctype": meta.get("doctype", "unknown"),
+                "endpoint": endpoint,
+                "summary": summary,
+                "chunk_id": i,
+                "chunk_hash": chunk_hash,
+            }
+        )
+    return records
+
+
+def persist_batch(table, docs: List[Dict]):
+    """Persist a batch of docs to `table`.
+
+    `table` is expected to implement an `add(iterable)` method
+    (LanceDB-like).
+
+    This wrapper keeps the call site testable. Returns the result of
+    `table.add` when present.
+    """
+    if not docs:
+        return None
+    if hasattr(table, "add"):
+        return table.add(docs)
+    # Fallback: try treating table as a callable
+    return table(docs)

plesk_unified/error_handling.py

@@ -0,0 +1,112 @@
+import functools
+import logging
+from typing import Any, Callable, TypeVar
+import inspect
+
+logger = logging.getLogger("plesk_unified")
+
+# Try to import LanceDB exceptions for precise matching
+try:
+    import lancedb.exceptions as lancedb_exc
+
+    LANCEDB_EXCEPTIONS_AVAILABLE = True
+except ImportError:
+    LANCEDB_EXCEPTIONS_AVAILABLE = False
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _classify_error(exc: Exception) -> str:  # noqa: PLR0911
+    """Map known exception types to user-friendly guidance strings."""
+    exc_msg = str(exc)
+    exc_msg_lower = exc_msg.lower()
+    exc_type_name = type(exc).__name__
+
+    # 1. LanceDB TableNotFoundError
+    if (
+        LANCEDB_EXCEPTIONS_AVAILABLE
+        and hasattr(lancedb_exc, "TableNotFoundError")
+        and isinstance(exc, lancedb_exc.TableNotFoundError)
+    ):
+        return (
+            "[ERROR] Knowledge base not indexed. "
+            "Call refresh_knowledge(reset_db=True) first."
+        )
+    if exc_type_name == "TableNotFoundError":
+        return (
+            "[ERROR] Knowledge base not indexed. "
+            "Call refresh_knowledge(reset_db=True) first."
+        )
+
+    # Handle ValueError that some versions of LanceDB raise when a table is missing
+    if isinstance(exc, ValueError) and "was not found" in exc_msg_lower:
+        return (
+            "[ERROR] Knowledge base not indexed. "
+            "Call refresh_knowledge(reset_db=True) first."
+        )
+
+    # 2. LanceDB connection error
+    # Connection errors in LanceDB can manifest as various exceptions
+    # depending on the storage backend
+    if (
+        "lancedb" in exc_msg_lower
+        or "database" in exc_msg_lower
+        or "connection" in exc_msg_lower
+    ):
+        if (
+            "not found" not in exc_msg_lower
+        ):  # Avoid collision with TableNotFoundError if not caught above
+            return (
+                "[ERROR] Database unavailable. Check storage/lancedb/ path. "
+                "Call daemon_health for details."
+            )
+
+    # 3. RuntimeError containing "model"
+    if isinstance(exc, RuntimeError) and "model" in exc_msg_lower:
+        return "[ERROR] Embedding model not loaded. Call warmup_server first."
+
+    # 4. PermissionError
+    if isinstance(exc, PermissionError):
+        return "[ERROR] Path traversal detected. Operation rejected."
+
+    # --- NEW FIX: Classify ValueError from _validate_category ---
+    if isinstance(exc, ValueError) and "invalid category" in exc_msg_lower:
+        # Re-raise as a more specific error message, keeping context
+        return f"[ERROR] Invalid argument: {exc_msg}. Check allowed category values."
+
+    # 5. Generic fallback
+    return (
+        "[ERROR] Unexpected server error. "
+        "Call daemon_health to check server state, then retry."
+    )
+
+
+def tool_error_boundary(fn: F) -> F:
+    """
+    Decorator for MCP tools to catch exceptions and return sanitized guidance.
+
+    Logs the full traceback to the module logger and returns a string starting
+    with [ERROR] that provides actionable instructions for the LLM.
+    """
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> str:
+            try:
+                return await fn(*args, **kwargs)
+            except Exception as exc:
+                logger.error("Tool %s failed", fn.__name__, exc_info=True)
+                return _classify_error(exc)
+
+        return async_wrapper  # type: ignore
+    else:
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> str:
+            try:
+                return fn(*args, **kwargs)
+            except Exception as exc:
+                logger.error("Tool %s failed", fn.__name__, exc_info=True)
+                return _classify_error(exc)
+
+        return sync_wrapper  # type: ignore

plesk_unified/html_utils.py

@@ -0,0 +1,217 @@
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Optional, Tuple, Set
+
+from bs4 import BeautifulSoup
+from markdownify import markdownify as _md
+
+from plesk_unified.ai_client import AIClient
+
+logger = logging.getLogger(__name__)
+
+# Constants for cognitive load rules
+MAX_TABLE_ROWS = 10
+MIN_PACKET_LEN = 5
+
+
+def _is_table_complex(table) -> bool:
+    """Heuristic to determine if a table is complex enough to need LLM normalization."""
+    # merged cells
+    if table.find_all(attrs={"colspan": True}) or table.find_all(
+        attrs={"rowspan": True}
+    ):
+        return True
+
+    rows = table.find_all("tr")
+    if len(rows) > MAX_TABLE_ROWS:  # Oversized table
+        return True
+
+    # Check for multi-level headers (th in non-first row or multiple rows with th)
+    th_rows = 0
+    for row in rows:
+        if row.find("th"):
+            th_rows += 1
+    if th_rows > 1:
+        return True
+
+    return False
+
+
+def _normalize_table_with_llm(
+    table, ai_client: AIClient, model: Optional[str] = None
+) -> str:
+    """Convert a complex HTML table into prose using an LLM."""
+    table_html = str(table)
+    prompt = (
+        "Convert the following HTML table into descriptive prose sentences "
+        "that preserve row-column semantic relationships. Output ONLY the prose.\n\n"
+        f"Table:\n{table_html}"
+    )
+
+    try:
+        models = [model] if model else ["google/gemini-2.5-flash-lite"]
+        res = ai_client.generate_description(prompt, model_list=models)
+        if res and res != "Description unavailable.":
+            return res
+    except Exception:
+        pass
+
+    return ""
+
+
+def _normalize_table_to_sentences(table) -> str:
+    """Convert an HTML table into descriptive prose sentences."""
+    rows = table.find_all("tr")
+    if not rows:
+        return ""
+
+    matrix = []
+    for row in rows:
+        cells = row.find_all(["th", "td"])
+        values = [c.get_text(" ", strip=True) for c in cells]
+        if any(values):
+            matrix.append(values)
+
+    if not matrix:
+        return ""
+
+    header_row = rows[0].find_all("th")
+    has_header = bool(header_row)
+
+    headers = matrix[0] if has_header else []
+    data_rows = matrix[1:] if has_header else matrix
+
+    sentences = []
+    for row in data_rows:
+        if headers and len(headers) == len(row):
+            parts = [f"{headers[i]}: {row[i]}" for i in range(len(row)) if row[i]]
+            sentence = ", ".join(parts)
+        else:
+            sentence = " | ".join(cell for cell in row if cell)
+        sentence = sentence.strip()
+        if sentence:
+            sentences.append(sentence + ".")
+
+    return "\n".join(sentences)
+
+
+def _replace_tables_with_prose(
+    soup: BeautifulSoup,
+    llm_enabled: bool = False,
+    ai_client: Optional[AIClient] = None,
+    llm_model: Optional[str] = None,
+) -> None:
+    """Replace HTML tables with prose blocks to preserve semantic relationships."""
+    for table in soup.find_all("table"):
+        prose = ""
+        if llm_enabled and ai_client and _is_table_complex(table):
+            prose = _normalize_table_with_llm(table, ai_client, llm_model)
+
+        if not prose:
+            prose = _normalize_table_to_sentences(table)
+
+        if not prose:
+            table.decompose()
+            continue
+        replacement = soup.new_tag("p")
+        replacement.string = prose
+        table.replace_with(replacement)
+
+
+def extract_api_endpoints(html: str) -> Optional[str]:
+    """Extract API endpoint signatures (REST, XML, CLI) from HTML content."""
+    found_endpoints: Set[str] = set()
+
+    # 1. REST API patterns
+    rest_matches = re.findall(
+        r"(GET|POST|PUT|DELETE|PATCH).{0,100}?((/api/v2)?/[a-zA-Z0-9\/\-\_{}]+)",
+        html,
+    )
+    for method, path, _ in rest_matches:
+        found_endpoints.add(f"{method} {path}")
+
+    # 2. XML API patterns
+    xml_matches = re.findall(r"([a-z0-9\_]+(?:_list|_get|_set))", html)
+    for packet in xml_matches:
+        if len(packet) > MIN_PACKET_LEN:  # avoid tiny noise
+            found_endpoints.add(f"XML: {packet}")
+
+    # 3. CLI patterns
+    cli_matches = re.findall(r"plesk\s+(?:bin\s+)?([a-z0-9\_]+)\s+([a-z0-9\_]+)", html)
+    for obj, cmd in cli_matches:
+        found_endpoints.add(f"CLI: {obj} {cmd}")
+
+    if not found_endpoints:
+        return None
+
+    return ", ".join(sorted(found_endpoints))
+
+
+def clean_dom_tree(soup: BeautifulSoup) -> BeautifulSoup:
+    """Remove nav, footer, scripts and other noisy elements from the DOM tree."""
+    for sel in soup.select(
+        "nav, footer, script, style, aside, .sidebar, .toc, noscript"
+    ):
+        sel.decompose()
+
+    llm_enabled = os.environ.get("PLESK_HTML_LLM_TABLE_NORMALIZE") == "1"
+    ai_client = AIClient() if llm_enabled else None
+    _replace_tables_with_prose(soup, llm_enabled=llm_enabled, ai_client=ai_client)
+
+    return soup
+
+
+def convert_soup_to_markdown(soup: BeautifulSoup) -> str:
+    """Convert a cleaned BeautifulSoup tree into Markdown text."""
+    main = soup.find("main") or soup.find("article") or soup.body
+    raw_html = str(main) if main else str(soup)
+
+    # Convert to Markdown to preserve code blocks and headings.
+    text = _md(raw_html, heading_style="ATX", strip=["a"])
+
+    # Collapse runs of 3+ blank lines
+    text = re.sub(r"\n{3,}", "\n\n", text).strip()
+    return text
+
+
+def parse_html(
+    path: Path, toc_meta: Optional[dict] = None
+) -> Tuple[str, str, Optional[str], str, Optional[str]]:
+    """Parse an HTML file and return (filename, title, breadcrumb, text, endpoint)."""
+    path = Path(path)
+    with path.open("r", encoding="utf-8", errors="ignore") as fh:
+        html = fh.read()
+
+    # 1. Extraction (Functional Decomposition)
+    endpoint = extract_api_endpoints(html)
+
+    soup = BeautifulSoup(html, "html.parser")
+
+    # 2. Title extraction
+    title_tag = soup.find("title")
+    title = (
+        title_tag.get_text(strip=True)
+        if title_tag
+        else (toc_meta or {}).get("title", "")
+    )
+
+    # 3. DOM Cleaning
+    soup = clean_dom_tree(soup)
+
+    # 4. Conversion
+    text = convert_soup_to_markdown(soup)
+
+    breadcrumb = (toc_meta or {}).get("breadcrumb")
+
+    return path.name, title, breadcrumb, text, endpoint
+
+
+def clean_html_for_markdown(html: str) -> str:
+    """Return cleaned HTML string suitable for markdown conversion."""
+    soup = BeautifulSoup(html, "html.parser")
+    soup = clean_dom_tree(soup)
+
+    main = soup.find("main") or soup.find("article") or soup.body
+    return str(main) if main else str(soup)