memplex 3.2.0__py3-none-any.whl

memnex/core/extractors/docx.py

@@ -0,0 +1,97 @@
+"""Extract content from DOCX files."""
+
+from typing import Optional
+
+
+class DOCXExtractor:
+    """Extracts text content from .docx files."""
+
+    def is_available(self) -> bool:
+        """Check if python-docx is installed."""
+        try:
+            import docx
+            return True
+        except ImportError:
+            return False
+
+    def extract(self, path: str) -> Optional[str]:
+        """
+        Extract text from a DOCX file.
+
+        Args:
+            path: Path to the .docx file
+
+        Returns:
+            Extracted text content, or None if extraction fails
+        """
+        if not self.is_available():
+            return None
+
+        try:
+            import docx
+            doc = docx.Document(path)
+            paragraphs = []
+
+            for para in doc.paragraphs:
+                text = para.text.strip()
+                if text:
+                    paragraphs.append(text)
+
+            for table in doc.tables:
+                for row in table.rows:
+                    for cell in row.cells:
+                        text = cell.text.strip()
+                        if text:
+                            paragraphs.append(text)
+
+            return "\n\n".join(paragraphs)
+
+        except Exception:
+            return None
+
+    def extract_full(self, path: str) -> dict:
+        """
+        Extract full content from DOCX including metadata.
+
+        Returns:
+            dict with keys: text, paragraphs, page_count (estimate), tables
+        """
+        if not self.is_available():
+            return None
+
+        try:
+            import docx
+            doc = docx.Document(path)
+            paragraphs = []
+            tables_text = []
+
+            for para in doc.paragraphs:
+                text = para.text.strip()
+                if text:
+                    paragraphs.append(text)
+
+            for table in doc.tables:
+                table_rows = []
+                for row in table.rows:
+                    row_texts = [cell.text.strip() for cell in row.cells if cell.text.strip()]
+                    if row_texts:
+                        table_rows.append(" | ".join(row_texts))
+                if table_rows:
+                    tables_text.append("\n".join(table_rows))
+
+            total_chars = sum(len(p) for p in paragraphs)
+            page_count = max(1, total_chars // 500)
+
+            return {
+                "text": "\n\n".join(paragraphs),
+                "paragraphs": paragraphs,
+                "page_count": page_count,
+                "tables": tables_text,
+                "metadata": {
+                    "paragraph_count": len(paragraphs),
+                    "table_count": len(tables_text)
+                }
+            }
+
+        except Exception:
+            return None

memnex/core/extractors/image.py

@@ -0,0 +1,233 @@
+"""Extract text from images using OCR or external vision providers."""
+
+from typing import Optional, Callable
+import os
+
+
+class ImageExtractor:
+    """
+    Extracts text and visual information from images.
+
+    Supports two modes:
+    1. Internal OCR: uses pytesseract (if available)
+    2. External providers: registered via set_*_provider() methods
+
+    Priority: External provider > Internal OCR
+    """
+
+    def __init__(self):
+        self._ocr_available = None
+        self._external_ocr: Optional[Callable] = None
+        self._external_vision: Optional[Callable] = None
+        self._vision_timeout = 60  # seconds
+        self._vision_max_retries = 2
+
+    def set_ocr_provider(self, fn: Callable[[str], Optional[str]]) -> None:
+        """
+        Register an external OCR provider.
+
+        Args:
+            fn: Callable that takes (image_path) returns OCR text or None.
+                Example: lambda path: subprocess.run(['tesseract', path, 'stdout'])
+        """
+        self._external_ocr = fn
+
+    def set_vision_provider(self, fn: Callable[[str], Optional[dict]]) -> None:
+        """
+        Register an external vision/LLM provider.
+
+        Args:
+            fn: Callable that takes (image_path) returns vision dict or None.
+                The dict should have keys: page_type, components[], layout, design_tools, design_system
+        """
+        self._external_vision = fn
+
+    @property
+    def has_ocr(self) -> bool:
+        """Check if any OCR is available (external or internal)."""
+        if self._external_ocr is not None:
+            return True
+        if self._ocr_available is None:
+            try:
+                import pytesseract
+                from PIL import Image
+                self._ocr_available = True
+            except ImportError:
+                self._ocr_available = False
+        return self._ocr_available
+
+    @property
+    def has_vision(self) -> bool:
+        """Check if vision capability is available (external or internal)."""
+        return self._external_vision is not None
+
+    def extract(self, image_path: str) -> Optional[str]:
+        """
+        Extract text from image using OCR.
+
+        Priority: External OCR provider > Internal pytesseract.
+
+        Args:
+            image_path: Path to image file
+
+        Returns:
+            Extracted text or None if OCR unavailable
+        """
+        if not os.path.exists(image_path):
+            return None
+
+        # 1. External OCR provider (priority)
+        if self._external_ocr is not None:
+            try:
+                result = self._external_ocr(image_path)
+                if result:
+                    return result.strip() if isinstance(result, str) else result
+            except Exception as e:
+                print(f"External OCR failed: {e}")
+
+        # 2. Internal pytesseract
+        try:
+            import pytesseract
+            from PIL import Image
+            image = Image.open(image_path)
+            text = pytesseract.image_to_string(image, lang='eng+chi')
+            return text.strip()
+        except Exception as e:
+            print(f"OCR failed for {image_path}: {e}")
+            return None
+
+    def extract_with_vision(self, image_path: str, prompt: str = None) -> Optional[dict]:
+        """
+        Extract visual understanding using vision model.
+
+        Priority: External vision provider (MCP/LLM) > None.
+        Applies timeout and retry with exponential backoff.
+
+        Args:
+            image_path: Path to image file
+            prompt: Custom prompt for vision analysis
+
+        Returns:
+            dict with vision analysis or None
+        """
+        import time
+
+        if not os.path.exists(image_path):
+            return None
+
+        # 1. External Vision provider (MCP/LLM)
+        if self._external_vision is not None:
+            last_error = None
+            for attempt in range(self._vision_max_retries):
+                try:
+                    result = self._external_vision(image_path)
+                    if result:
+                        return result
+                except TimeoutError as e:
+                    last_error = f"Timeout after {self._vision_timeout}s (attempt {attempt + 1}/{self._vision_max_retries})"
+                    print(f"External vision timeout: {last_error}")
+                except Exception as e:
+                    last_error = f"{type(e).__name__}: {e} (attempt {attempt + 1}/{self._vision_max_retries})"
+                    print(f"External vision failed: {last_error}")
+
+                if attempt < self._vision_max_retries - 1:
+                    wait_time = 2 ** attempt  # exponential backoff: 1s, 2s
+                    time.sleep(wait_time)
+
+            if last_error:
+                print(f"Vision exhausted after {self._vision_max_retries} attempts")
+
+        return None
+
+    def extract_full(self, image_path: str, vision_result: dict = None) -> dict:
+        """
+        Extract both OCR text and optionally pre-extracted vision understanding.
+
+        Args:
+            image_path: Path to image file
+            vision_result: Pre-extracted vision analysis (from LLM MCP).
+                          If provided, skips internal vision extraction.
+
+        Returns:
+            dict with:
+            - ocr_text: raw text from OCR
+            - has_ocr: whether OCR succeeded
+            - vision: structured vision analysis
+            - has_vision: whether vision was provided or extracted
+            - combined_text: OCR + Vision text for paragraph extraction
+        """
+        result = {
+            "ref": image_path,
+            "type": "image",
+            "ocr_text": None,
+            "has_ocr": False,
+            "vision": vision_result,
+            "has_vision": vision_result is not None,
+            "combined_text": "",
+        }
+
+        # 1. OCR extraction
+        ocr_text = self.extract(image_path)
+        if ocr_text:
+            result["ocr_text"] = ocr_text
+            result["has_ocr"] = True
+            result["combined_text"] = ocr_text
+
+        # 2. Vision result (may be pre-extracted via MCP)
+        if vision_result:
+            result["vision"] = vision_result
+            result["has_vision"] = True
+            vision_text = self._vision_to_text(vision_result)
+            if result["combined_text"]:
+                result["combined_text"] += "\n" + vision_text
+            else:
+                result["combined_text"] = vision_text
+        else:
+            internal_vision = self.extract_with_vision(image_path)
+            if internal_vision:
+                result["vision"] = internal_vision
+                result["has_vision"] = True
+                vision_text = self._vision_to_text(internal_vision)
+                if result["combined_text"]:
+                    result["combined_text"] += "\n" + vision_text
+                else:
+                    result["combined_text"] = vision_text
+
+        return result
+
+    def _vision_to_text(self, vision: dict) -> str:
+        """Convert vision result to readable text."""
+        lines = []
+
+        if vision.get("page_type"):
+            lines.append(f"页面类型: {vision['page_type']}")
+
+        if vision.get("design_tools"):
+            lines.append(f"设计工具: {', '.join(vision['design_tools'])}")
+
+        if vision.get("design_system"):
+            lines.append(f"设计系统: {vision['design_system']}")
+
+        if vision.get("layout"):
+            lines.append(f"布局结构: {vision['layout']}")
+
+        if vision.get("components"):
+            lines.append("组件列表:")
+            for comp in vision["components"]:
+                data_str = f" (数据: {comp['data']})" if comp.get("data") else ""
+                lines.append(f"  - [{comp['type']}] {comp['label']}: {comp.get('function', '')}{data_str}")
+
+        return "\n".join(lines)
+
+    def extract_with_metadata(self, image_path: str) -> dict:
+        """Extract text and image metadata (legacy method)."""
+        full_result = self.extract_full(image_path)
+        return {
+            "ref": image_path,
+            "type": "image",
+            "ocr_text": full_result["ocr_text"] or "",
+            "has_text": full_result["has_ocr"],
+            "vision": full_result["vision"],
+            "needs_vision_model": not full_result["has_vision"],
+            "visual_note": f"OCR: {len(full_result.get('ocr_text') or '')} chars, Vision: {'yes' if full_result['has_vision'] else 'no'}"
+        }

memnex/core/extractors/markdown.py

@@ -0,0 +1,139 @@
+"""Extract content from Markdown/Text documents."""
+
+import re
+from typing import List
+from memnex.models.paragraph import Paragraph, Sentence, SentenceRelation, ParagraphCollection
+
+
+class MarkdownExtractor:
+    """Extracts L1 paragraphs and L2 structured data from markdown."""
+
+    def extract(self, content: str, source: str = "document.md") -> ParagraphCollection:
+        """
+        Extract paragraphs from markdown content.
+
+        Args:
+            content: Markdown text content
+            source: Source identifier
+
+        Returns:
+            ParagraphCollection with extracted paragraphs
+        """
+        paragraphs = ParagraphCollection()
+
+        # Split by double newlines (paragraph separation)
+        blocks = re.split(r'\n\s*\n', content)
+
+        for i, block in enumerate(blocks):
+            block = block.strip()
+            if not block:
+                continue
+
+            para_id = f"para_{i+1:03d}"
+
+            # Detect section header
+            header_match = re.match(r'^(#{1,6})\s+(.+)$', block, re.MULTILINE)
+            section = ""
+            if header_match:
+                section = header_match.group(2).strip()
+
+            # Extract sentences and roles
+            sentences = self._extract_sentences(block, para_id)
+            relations = self._extract_relations(sentences)
+
+            paragraph = Paragraph(
+                id=para_id,
+                source=f"{source}#{para_id}",
+                section=section,
+                raw_text=block,
+                semantic_unit=True,
+                sentences=sentences,
+                sentence_relations=relations
+            )
+
+            paragraphs.add(paragraph)
+
+        return paragraphs
+
+    def _extract_sentences(self, text: str, para_id: str) -> List[Sentence]:
+        """Extract sentences and their roles from text."""
+        # Split on sentence-ending punctuation followed by whitespace and uppercase/Chinese
+        # Also split on newlines (paragraph breaks)
+        # Avoids splitting on decimals (1.5) or common abbreviations (e.g., i.e.)
+        sentence_texts = re.split(r'(?<=[.!?。！？])\s+(?=[A-Z一-鿿])|[\n]+', text)
+        sentences = []
+
+        for i, sent in enumerate(sentence_texts):
+            sent = sent.strip()
+            if not sent:
+                continue
+
+            role = self._infer_role(sent)
+            sentences.append(Sentence(
+                id=f"{para_id}_s{i+1}",
+                text=sent,
+                role=role
+            ))
+
+        return sentences
+
+    def _infer_role(self, sentence: str) -> str:
+        """Infer the role of a sentence from its content."""
+        sentence_lower = sentence.lower()
+
+        # Trigger indicators — user interaction or event start
+        # NOTE: avoid overly generic words like "登录" or "用户" that appear in all sentence types
+        trigger_patterns = [
+            '点击', '选择', '提交', '按下', '输入', '勾选',
+            '当', 'when', 'after', 'before',
+            '登录时', '登出时', '注册时',
+        ]
+        for p in trigger_patterns:
+            if p in sentence_lower:
+                return "trigger"
+
+        # Condition indicators — prerequisite or conditional logic
+        cond_patterns = [
+            '如果', '满足', '条件是', '前提是', 'when', 'if', 'unless',
+            '条件', 'required', '前提',
+        ]
+        for p in cond_patterns:
+            if p in sentence_lower:
+                return "condition"
+
+        # Action indicators — system or user performs an operation
+        action_patterns = [
+            '自动', '发送', '创建', '更新', '删除', '跳转', '打开', '关闭',
+            '显示', '隐藏', '提交', '保存', '取消',
+            'action', 'do', 'perform', 'execute',
+        ]
+        for p in action_patterns:
+            if p in sentence_lower:
+                return "action"
+
+        # Result indicators — outcome or benefit
+        result_patterns = [
+            '享受', '获得', '收到', '看到', '返回', '跳转到',
+            'result', 'then', '因此', '所以', '进入',
+        ]
+        for p in result_patterns:
+            if p in sentence_lower:
+                return "result"
+
+        return "statement"
+
+    def _extract_relations(self, sentences: List[Sentence]) -> List[SentenceRelation]:
+        """Extract relations between sentences."""
+        relations = []
+
+        for i, sent in enumerate(sentences):
+            if sent.role == "condition" and i + 1 < len(sentences):
+                next_sent = sentences[i + 1]
+                if next_sent.role == "action":
+                    relations.append(SentenceRelation(
+                        from_id=sent.id,
+                        to_id=next_sent.id,
+                        type="if_then"
+                    ))
+
+        return relations

memnex/core/extractors/pdf.py

@@ -0,0 +1,133 @@
+"""Extract text and images from PDF files."""
+
+from typing import List, Optional, Dict, Any
+import os
+import tempfile
+
+
+class PDFExtractor:
+    """Extracts text and images from PDF files."""
+
+    def __init__(self):
+        self._available = None
+        self._pymupdf_available = None
+
+    def is_available(self) -> bool:
+        """Check if PDF extraction is available."""
+        if self._available is None:
+            try:
+                import pdfplumber
+                self._available = True
+            except ImportError:
+                self._available = False
+        return self._available
+
+    def _is_pymupdf_available(self) -> bool:
+        """Check if PyMuPDF is available for image extraction."""
+        if self._pymupdf_available is None:
+            try:
+                import fitz
+                self._pymupdf_available = True
+            except ImportError:
+                self._pymupdf_available = False
+        return self._pymupdf_available
+
+    def extract(self, pdf_path: str) -> Optional[List[str]]:
+        """Extract text from PDF file. Returns list of page texts."""
+        if not self.is_available():
+            return None
+        if not os.path.exists(pdf_path):
+            return None
+        try:
+            import pdfplumber
+            pages = []
+            with pdfplumber.open(pdf_path) as pdf:
+                for page in pdf.pages:
+                    text = page.extract_text()
+                    if text:
+                        pages.append(text)
+            return pages if pages else None
+        except Exception:
+            return None
+
+    def _extract_images_pymupdf(self, pdf_path: str) -> List[List[Dict[str, Any]]]:
+        """Extract images from PDF using PyMuPDF. Returns list of images per page."""
+        try:
+            import fitz
+            images_per_page = []
+            doc = fitz.open(pdf_path)
+            for page_num, page in enumerate(doc):
+                page_images = []
+                image_list = page.get_images(full=True)
+                for img_index, img in enumerate(image_list):
+                    xref = img[0]
+                    pix = fitz.Pixmap(doc, xref)
+                    if pix.n - pix.alpha < 4:
+                        img_data = pix.tobytes("png")
+                    else:
+                        pix = fitz.Pixmap(fitz.csRGB, pix)
+                        img_data = pix.tobytes("png")
+                    temp_file = tempfile.NamedTemporaryFile(
+                        suffix=".png", delete=False
+                    )
+                    temp_file.write(img_data)
+                    temp_file.close()
+                    page_images.append({
+                        "path": temp_file.name,
+                        "page": page_num,
+                        "index": img_index,
+                        "width": pix.width,
+                        "height": pix.height,
+                    })
+                images_per_page.append(page_images)
+            doc.close()
+            return images_per_page
+        except Exception:
+            return []
+
+    def _extract_images_pdfplumber(self, pdf_path: str) -> List[List[Dict[str, Any]]]:
+        """Extract image metadata from PDF using pdfplumber (no actual bytes)."""
+        try:
+            import pdfplumber
+            images_per_page = []
+            with pdfplumber.open(pdf_path) as pdf:
+                for page in pdf.pages:
+                    page_images = []
+                    for img in page.images:
+                        page_images.append({
+                            "path": None,
+                            "page": page.page_number - 1,
+                            "index": len(page_images),
+                            "width": img.get("width"),
+                            "height": img.get("height"),
+                            "bbox": (img.get("x0"), img.get("y0"), img.get("x1"), img.get("y1")),
+                        })
+                    images_per_page.append(page_images)
+            return images_per_page
+        except Exception:
+            return []
+
+    def extract_full(self, pdf_path: str) -> Optional[dict]:
+        """Extract full content with text, metadata, and images."""
+        if not self.is_available():
+            return None
+        if not os.path.exists(pdf_path):
+            return None
+        try:
+            import pdfplumber
+            with pdfplumber.open(pdf_path) as pdf:
+                pages_text = [page.extract_text() or "" for page in pdf.pages]
+
+            if self._is_pymupdf_available():
+                images = self._extract_images_pymupdf(pdf_path)
+            else:
+                images = self._extract_images_pdfplumber(pdf_path)
+
+            return {
+                "pages": pages_text,
+                "metadata": pdf.metadata if hasattr(pdf, 'metadata') else {},
+                "page_count": len(pages_text),
+                "images": images,
+            }
+        except Exception:
+            return None