sirchmunk 0.0.0__py3-none-any.whl → 0.0.1.post1__py3-none-any.whl

sirchmunk/schema/request.py

@@ -0,0 +1,221 @@
+# Copyright (c) ModelScope Contributors. All rights reserved.
+from dataclasses import dataclass
+from typing import Dict, List, Literal, Optional, Union
+
+
+@dataclass
+class ImageURL:
+    """Represents an image URL with optional detail and media type."""
+
+    url: str
+    detail: str = "auto"
+    media_type: str = "image/jpeg"  # Necessary for Anthropic
+
+
+@dataclass
+class ContentItem:
+    """Represents a content item, which can be either text or an image URL."""
+
+    type: str  # "text" or "image_url"
+    text: Optional[str] = None
+    image_url: Optional[ImageURL] = None
+
+    def to_openai(self):
+        if self.type == "text":
+            return {"type": "text", "text": self.text}
+        return {
+            "type": "image_url",
+            "image_url": {"url": self.image_url.url, "detail": self.image_url.detail},
+        }
+
+    def to_anthropic(self):
+        if self.type == "text":
+            return {"type": "text", "text": self.text}
+
+        # Strip Base64 prefix if present for Anthropic
+        raw_data = self.image_url.url
+        if "base64," in raw_data:
+            raw_data = raw_data.split("base64,")[1]
+
+        return {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": self.image_url.media_type,
+                "data": raw_data,
+            },
+        }
+
+
+@dataclass
+class Message:
+    """Represents a message in the conversation, system/user/assistant."""
+
+    role: str
+    content: Union[str, List[ContentItem]]
+
+
+@dataclass
+class Request:
+    """
+    Represents a request to Agentic Search API, supporting both OpenAI and Anthropic message formats.
+    """
+
+    messages: List[Message]
+    system: Optional[str] = "You are a helpful assistant."
+    message_format: Literal["openai", "anthropic"] = "openai"
+
+    def get_system(self) -> str:
+        """Get the system prompt."""
+        return self.system
+
+    def get_user_input(self) -> str:
+        """Extract the user query from the messages."""
+        for m in self.messages:
+            if m.role == "user":
+                if isinstance(m.content, str):
+                    return m.content
+                else:
+                    texts = [c.text for c in m.content if c.type == "text" and c.text]
+                    return " ".join(texts)
+        return ""
+
+    def get_image_urls(self) -> List[str]:
+        """Extract image URLs from user messages."""
+        image_urls = []
+        for m in self.messages:
+            if m.role == "user":
+                if isinstance(m.content, list):
+                    for c in m.content:
+                        if c.type == "image_url" and c.image_url:
+                            image_urls.append(c.image_url.url)
+        return image_urls
+
+    def to_payload(
+        self, prompt_template: Optional[str] = None
+    ) -> Union[List[Dict], Dict]:
+        """Convert messages to the appropriate API payload format based on message_format."""
+        if self.message_format == "openai":
+            return self._to_openai_payload(prompt_template=prompt_template)
+        elif self.message_format == "anthropic":
+            return self._to_anthropic_payload(prompt_template=prompt_template)
+        else:
+            raise ValueError(
+                f"Unsupported message format: {self.message_format}, must be 'openai' or 'anthropic'."
+            )
+
+    def _to_openai_payload(self, prompt_template: Optional[str] = None) -> List[Dict]:
+        """Convert messages to OpenAI API payload format."""
+        formatted_msgs = []
+        system_msg: Message = Message(role="system", content=self.system)
+        self.messages.insert(0, system_msg)
+
+        for m in self.messages:
+            if m.role == "user" and prompt_template:
+                # Apply prompt template if provided
+                if isinstance(m.content, str):
+                    content = prompt_template.format(user_input=m.content)
+                else:
+                    content = []
+                    for c in m.content:
+                        if c.type == "text":
+                            formatted_text = prompt_template.format(user_input=c.text)
+                            content.append({"type": "text", "text": formatted_text})
+                        else:
+                            content.append(c.to_openai())
+            else:
+                content = (
+                    m.content
+                    if isinstance(m.content, str)
+                    else [c.to_openai() for c in m.content]
+                )
+            formatted_msgs.append({"role": m.role, "content": content})
+
+        return formatted_msgs
+
+    def _to_anthropic_payload(self, prompt_template: Optional[str] = None) -> Dict:
+        """Convert messages to Anthropic API payload format."""
+        formatted_msgs = []
+
+        for m in self.messages:
+            if m.role == "user" and prompt_template:
+                # Apply prompt template if provided
+                if isinstance(m.content, str):
+                    content = prompt_template.format(user_input=m.content)
+                else:
+                    content = []
+                    for c in m.content:
+                        if c.type == "text":
+                            formatted_text = prompt_template.format(user_input=c.text)
+                            content.append({"type": "text", "text": formatted_text})
+                        else:
+                            content.append(c.to_anthropic())
+            else:
+                # Anthropic expects 'system' as a top-level parameter, not in messages
+                content = (
+                    m.content
+                    if isinstance(m.content, str)
+                    else [c.to_anthropic() for c in m.content]
+                )
+
+            formatted_msgs.append({"role": m.role, "content": content})
+
+        payload = {"system": self.system, "messages": formatted_msgs}
+
+        return payload
+
+
+if __name__ == "__main__":
+    import json
+
+    prompt_template: str = (
+        "Please answer the following question carefully based on the given information: {user_input}"
+    )
+
+    # Usage for Anthropic
+    req_anthropic = Request(
+        message_format="anthropic",
+        system="Analyze the video frames carefully.",
+        messages=[
+            Message(
+                role="user",
+                content=[
+                    ContentItem(type="text", text="What is happening here?"),
+                    ContentItem(
+                        type="image_url",
+                        image_url=ImageURL(url="base64_string_here..."),
+                    ),
+                ],
+            ),
+        ],
+    )
+    print(
+        f"Anthropic Payload:\n{json.dumps(req_anthropic.to_payload(prompt_template=prompt_template), ensure_ascii=False, indent=2)}"
+    )
+
+    # Usage for OpenAI
+    req_openai = Request(
+        message_format="openai",
+        system="You are a helpful assistant.",
+        messages=[
+            Message(
+                role="user",
+                content=[
+                    ContentItem(type="text", text="What is unusual about this image?"),
+                    ContentItem(
+                        type="image_url",
+                        image_url=ImageURL(
+                            url="https://example.com/strange-building.jpg"
+                        ),
+                    ),
+                ],
+            ),
+        ],
+    )
+    print(
+        f"\nOpenAI Payload:\n{json.dumps(req_openai.to_payload(prompt_template=prompt_template), ensure_ascii=False, indent=2)}"
+    )
+
+    print(f"\nUser Query (OpenAI format): {req_openai.get_user_input()}")
+
+    print(f"\nImage URLs (OpenAI format): {req_openai.get_image_urls()}")

sirchmunk/schema/response.py

@@ -0,0 +1,20 @@
+# Copyright (c) ModelScope Contributors. All rights reserved.
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@dataclass
+class Response:
+    """
+    Represents a response generated by the agentic search system.
+    """
+
+    # The main content of the response
+    content: str
+
+    # Additional data or metadata associated with the response
+    metadata: Dict[str, Any] = None
+
+    def __post_init__(self):
+        if self.metadata is None:
+            self.metadata = {}

sirchmunk/schema/snapshot.py

@@ -0,0 +1,346 @@
+# Copyright (c) ModelScope Contributors. All rights reserved.
+import random
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, List, Optional, Union
+
+from loguru import logger
+
+from sirchmunk.llm.openai_chat import OpenAIChat
+from sirchmunk.utils.tokenizer_util import TokenizerUtil
+
+
+@dataclass
+class SnapshotInfo:
+    """
+    Data class to hold snapshot information of the specified file.
+    """
+
+    title: str = field(default="")
+
+    description: str = field(default="")
+
+    keywords: List[str] = field(default_factory=list)
+
+    contents: List[str] = field(default_factory=list)
+
+    # Additional resources (e.g., images, tables, or others associated with current file)
+    resources: List[Any] = field(default_factory=list)
+
+    def to_dict(self):
+        """Convert SnapshotInfo to a dictionary."""
+        return {
+            "title": self.title,
+            "description": self.description,
+            "keywords": self.keywords,
+            "contents": self.contents,
+            "resources": self.resources,
+        }
+
+
+class Snapshot(ABC):
+    """
+    Base class for file snapshotting strategies.
+    """
+
+    def __init__(
+        self,
+        llm: Optional[OpenAIChat] = None,
+        **kwargs,
+    ):
+
+        self.llm: Optional[OpenAIChat] = llm
+        self.kwargs = kwargs
+
+    @abstractmethod
+    def sampling(self, **kwargs) -> List[str]:
+        """
+        Abstract method to perform sampling on a file.
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
+
+class TextSnapshot(Snapshot):
+    """
+    Text file sampling strategies for snapshotting large text files.
+    """
+
+    # TODO: sampling支持多次采样，尤其是针对中间的chunks；后续LLM可以自适应动态调用sampling来做内容增强；
+    # Staring mode（凝视模式，参考Radar中的概念）：该过程在search阶段由LLM启发式调度；越复杂的文档，中间chunks采样越多；同时需要多次迭代summary，并回写metadata的snapshot
+    # 对于contents，采用多阶段summary
+    # def resampling(): ...
+
+    MAX_SNAPSHOT_TOKENS = 2048  # Can be adaptive based on file size
+
+    MAX_FILE_SIZE = 500 * 1024 * 1024  # 500 MB
+
+    def __init__(self, llm: Optional[OpenAIChat] = None, **kwargs):
+
+        from sirchmunk.insight.text_insights import TextInsights
+
+        super().__init__(llm=llm, **kwargs)
+
+        self.text_insights = TextInsights(llm=llm)
+        self.tokenizer_util = TokenizerUtil()
+
+    @staticmethod
+    def filter_line(line: str) -> Optional[str]:
+        """Filter out lines with low information content or noise.
+
+        Filters out:
+        - Empty lines or whitespace-only lines
+        - Markdown formatting noise (horizontal rules, excessive headings, etc.)
+        - Lines consisting mostly of symbols/punctuation
+        - URLs, email addresses, and common noise patterns
+        - Very short lines (typically < 3 characters after cleaning)
+        - Lines with excessive repeated characters
+        - Common boilerplate/footer patterns
+
+        Args:
+            line: Input line string.
+
+        Returns:
+            Cleaned line string if it passes filters, None otherwise.
+        """
+        if not line:
+            return None
+
+        # Strip whitespace and check for empty lines
+        stripped = line.strip()
+        if not stripped:
+            return None
+
+        # Remove leading/trailing whitespace but preserve internal structure
+        cleaned = line.rstrip(
+            "\n\r"
+        )  # Keep original indentation, only remove line endings
+
+        # Check line length (after stripping)
+        if len(stripped) < 10:
+            return None
+
+        # Markdown-specific noise patterns
+        markdown_noise_patterns = [
+            r"^\s*-{3,}\s*$",  # Horizontal rules (---, --- , etc.)
+            r"^\s*\*{3,}\s*$",  # Horizontal rules (***)
+            r"^\s*_{3,}\s*$",  # Horizontal rules (___)
+            r"^\s*#{6,}.*$",  # Excessive headings (6+ #)
+            r"^\s*>+\s*$",  # Empty blockquotes
+            r"^\s*[-*+]\s*$",  # Empty list items
+            r"^\s*\d+\.\s*$",  # Empty numbered list items
+            r"^\s*!\[.*\]\(.*\)\s*$",  # Standalone images without context
+            r"^\s*\[.*\]:\s*https?://\S+\s*$",  # Reference-style link definitions
+            r"^\s*```\s*\w*\s*$",  # Code block delimiters (``` or ```python)
+            r"^\s*~~~\s*\w*\s*$",  # Alternative code block delimiters
+            r"^\s*\|\s*[-:]+\s*\|\s*$",  # Table separator rows
+            r"^\s*\|(\s*:?-+:?\s*\|)+\s*$",  # Alternative table separator format
+        ]
+
+        # Check for Markdown noise patterns
+        for pattern in markdown_noise_patterns:
+            if re.match(pattern, stripped):
+                return None
+
+        # Remove common noise patterns and check if line becomes empty
+        noise_patterns = [
+            r"^https?://\S+",  # URLs at start of line
+            r"\bhttps?://\S+\b",  # URLs anywhere
+            r"\bwww\.\S+\b",  # www URLs
+            r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b",  # emails
+            r"^[\s\*\-\_\=\#\+]+$",  # lines with only symbols
+        ]
+
+        # Check for excessive symbols ratio
+        alphanumeric_chars = sum(c.isalnum() for c in stripped)
+        if len(stripped) > 0 and alphanumeric_chars / len(stripped) < 0.3:
+            return None
+
+        # Check for excessive repeated characters (e.g., "..........." or "----------")
+        if TextSnapshot._has_excessive_repetition(stripped):
+            return None
+
+        # Check for common boilerplate patterns
+        boilerplate_patterns = [
+            r"^(copyright|©|\(c\))",
+            r"^all rights reserved",
+            r"^confidential",
+            r"^page \d+",
+            r"^\d+\s+of\s+\d+$",
+            r"^file:|^path:",
+            r"^created:|^modified:",
+            r"^author:",
+            r"^version:",
+            r"^build:",
+            r"^generated by",
+            r"^this document",
+            r"^last updated",
+            r"^table of contents",
+            r"^toc:",
+            r"^contents",
+            r"^index",
+        ]
+
+        stripped_lower = stripped.lower()
+        for pattern in boilerplate_patterns:
+            if re.search(pattern, stripped_lower):
+                return None
+
+        # Apply noise pattern removal and check if meaningful content remains
+        temp_line = stripped
+        for pattern in noise_patterns + markdown_noise_patterns:
+            temp_line = re.sub(pattern, "", temp_line)
+
+        # After removing noise, check if we still have meaningful content
+        temp_stripped = temp_line.strip()
+        if (
+            len(temp_stripped) < 3
+            or (
+                sum(c.isalnum() for c in temp_stripped) / len(temp_stripped)
+                if len(temp_stripped) > 0
+                else 0
+            )
+            < 0.4
+        ):
+            return None
+
+        # Additional check: reject lines that are mostly Markdown syntax characters
+        markdown_chars = sum(1 for c in stripped if c in "#*_-~`>![](){}|:")
+        if len(stripped) > 0 and markdown_chars / len(stripped) > 0.6:
+            return None
+
+        return cleaned
+
+    @staticmethod
+    def _has_excessive_repetition(text: str) -> bool:
+        """Check if text has excessive character repetition.
+
+        Args:
+            text: Input text string.
+
+        Returns:
+            True if excessive repetition detected.
+        """
+        if len(text) < 10:
+            return False
+
+        # Check for sequences of same character (e.g., "------", "......")
+        for i in range(len(text) - 4):
+            if text[i] == text[i + 1] == text[i + 2] == text[i + 3] == text[i + 4]:
+                # Allow some legitimate cases like "hello....." but not full line
+                if text.count(text[i]) / len(text) > 0.6:
+                    return True
+
+        # Check for alternating patterns (e.g., "- - - -", ". . . .")
+        if re.search(r"([^\w\s])\s*\1\s*\1\s*\1", text):
+            return True
+
+        return False
+
+    def sampling(
+        self,
+        file_path: Union[str, Path],
+        max_snapshot_tokens: int = MAX_SNAPSHOT_TOKENS,
+        max_file_size: int = MAX_FILE_SIZE,
+    ) -> Union[SnapshotInfo, None]:
+
+        file_path = Path(file_path)
+        file_size = file_path.stat().st_size
+        if file_size > max_file_size:  # TODO: add more strategies for large files
+            logger.warning(
+                f"File size {file_size} exceeds maximum allowed size of {max_file_size} bytes, skipping snapshot."
+            )
+            return None
+
+        snapshot_info = SnapshotInfo()
+
+        selected_lines = []
+        accumulated_tokens = 0
+        line_count = 0
+
+        # Stream through file once
+        with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = self.filter_line(line)
+                if not line:
+                    continue
+
+                line_count += 1
+                line_tokens = self.tokenizer_util.count_tokens(contents=line.strip())
+
+                # Adaptive sampling strategy:
+                # - Early in file: higher acceptance probability
+                # - Near token limit: lower probability
+                # - Always accept if budget allows and line is small
+
+                # Calculate acceptance probability
+                token_fill_ratio = (
+                    accumulated_tokens / max_snapshot_tokens
+                    if max_snapshot_tokens > 0
+                    else 0
+                )
+                line_token_ratio = (
+                    line_tokens / max_snapshot_tokens if max_snapshot_tokens > 0 else 0
+                )
+
+                # Base probability decreases as we fill token budget
+                base_prob = max(0.2, 1.0 - token_fill_ratio * 2.0)
+
+                # Adjust for line size (prefer smaller lines when budget is tight)
+                size_penalty = (
+                    min(1.0, 0.8 + (1.0 - line_token_ratio) * 0.4)
+                    if token_fill_ratio > 0.5
+                    else 1.0
+                )
+
+                # Add some randomness to avoid deterministic patterns
+                noise = random.uniform(0.8, 1.2)
+                acceptance_prob = min(1.0, base_prob * size_penalty * noise)
+
+                # Force accept conditions
+                if (accumulated_tokens == 0 and line_tokens > 0) or (
+                    accumulated_tokens + line_tokens <= max_snapshot_tokens * 0.7
+                ):
+                    acceptance_prob = 1.0
+
+                # Sampling decision
+                if random.random() < acceptance_prob:
+                    # Check if adding this line keeps us within reasonable bounds
+                    if (
+                        accumulated_tokens + line_tokens <= max_snapshot_tokens * 1.5
+                    ):  # Allow 50% overflow max
+                        selected_lines.append((line, line_count))
+                        accumulated_tokens += line_tokens
+
+                        # Early termination if we've significantly exceeded target
+                        if accumulated_tokens >= max_snapshot_tokens * 1.2:
+                            break
+
+        # Sort by original line number to preserve document structure
+        selected_lines.sort(key=lambda x: x[1])
+        logger.info(
+            f"Got {len(selected_lines)} selected lines, total tokens: {accumulated_tokens}"
+        )
+
+        snapshot_info.contents = [line for line, _ in selected_lines]
+
+        # Get keywords/key phrase
+        try:
+            snapshot_info.keywords = self.text_insights.extract_phrase(
+                contents=snapshot_info.contents
+            )
+        except Exception as e:
+            logger.error(f"Error extracting keywords: {e}")
+            snapshot_info.keywords = []
+
+        try:
+            # TODO: 与phrase一起放到同一个llm calling中
+            snapshot_info.description = self.text_insights.extract_toc(
+                contents=snapshot_info.contents
+            )
+        except Exception as e:
+            logger.error(f"Error extracting description: {e}")
+            snapshot_info.description = ""
+
+        return snapshot_info