intuned-browser 0.1.0__tar.gz

intuned_browser-0.1.0/LICENSE

@@ -0,0 +1,42 @@
+Acceptance
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+Limitations
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+Patents
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+Notices
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+No Other Rights
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+Termination
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+No Liability
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+Definitions
+The licensor is the entity offering these terms, and the software is the software the licensor makes available under these terms, including any portion of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

intuned_browser-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: intuned-browser
+Version: 0.1.0
+Summary: Intuned Browser SDK
+License: Elastic-2.0
+License-File: LICENSE
+Keywords: sdk,intuned
+Author: Intuned Developers
+Author-email: engineering@intunedhq.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: Levenshtein (==0.26.0)
+Requires-Dist: aioboto3 (>=15.2.0,<16.0.0)
+Requires-Dist: aiofiles (>=24.1.0)
+Requires-Dist: anthropic (>=0.47.1,<0.48.0)
+Requires-Dist: beautifulsoup4 (>=4.12.3)
+Requires-Dist: botocore (>=1.34.70)
+Requires-Dist: diskcache (>=5.6.3)
+Requires-Dist: fuzzysearch (>=0.7.3)
+Requires-Dist: google-generativeai (>=0.8.2)
+Requires-Dist: httpx (==0.27.2)
+Requires-Dist: jsonschema (>=4.23.0,<5.0.0)
+Requires-Dist: litellm (==1.67.2)
+Requires-Dist: mdformat (>=0.7.18,<0.8.0)
+Requires-Dist: openai (>=1.42.0)
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Requires-Dist: python-dotenv (>=1.0.1)
+Requires-Dist: ruff (>=0.7.2,<0.8.0)
+Requires-Dist: tenacity (==8.5.0)
+Requires-Dist: termcolor (>=2.5.0,<3.0.0)
+Requires-Dist: validators (>=0.34.0)
+Description-Content-Type: text/markdown
+
+# Intuned Browser
+
+A set of common utilities for Intuned services, useful for web scraping with Playwright and for integration into Intuned platform projects.
+

intuned_browser-0.1.0/README.md

@@ -0,0 +1,3 @@
+# Intuned Browser
+
+A set of common utilities for Intuned services, useful for web scraping with Playwright and for integration into Intuned platform projects.

intuned_browser-0.1.0/intuned_browser/__init__.py

@@ -0,0 +1,35 @@
+from intuned_browser.helpers.download_file import download_file
+from intuned_browser.helpers.extract_markdown import extract_markdown
+from intuned_browser.helpers.filter_empty_values import filter_empty_values
+from intuned_browser.helpers.go_to_url import go_to_url
+from intuned_browser.helpers.process_dates import process_date
+from intuned_browser.helpers.resolve_url import resolve_url
+from intuned_browser.helpers.sanitize_html import sanitize_html
+from intuned_browser.helpers.save_file_to_s3 import save_file_to_s3
+from intuned_browser.helpers.scroll_to_load_content import scroll_to_load_content
+from intuned_browser.helpers.types import Attachment
+from intuned_browser.helpers.types import S3Configs
+from intuned_browser.helpers.types import ValidationError
+from intuned_browser.helpers.upload_file import upload_file_to_s3
+from intuned_browser.helpers.validate_data_using_schema import validate_data_using_schema
+from intuned_browser.helpers.wait_for_dom_settled import wait_for_dom_settled
+from intuned_browser.helpers.wait_for_network_settled import wait_for_network_settled
+
+__all__ = [
+    "extract_markdown",
+    "sanitize_html",
+    "resolve_url",
+    "download_file",
+    "filter_empty_values",
+    "go_to_url",
+    "scroll_to_load_content",
+    "process_date",
+    "save_file_to_s3",
+    "upload_file_to_s3",
+    "validate_data_using_schema",
+    "wait_for_network_settled",
+    "wait_for_dom_settled",
+    "Attachment",
+    "S3Configs",
+    "ValidationError",
+]

intuned_browser-0.1.0/intuned_browser/ai/__init__.py

@@ -0,0 +1,19 @@
+from intuned_browser.ai.extract_structured_data import extract_structured_data
+from intuned_browser.ai.is_page_loaded import is_page_loaded
+from intuned_browser.ai.types import ContentItem
+from intuned_browser.ai.types import DataExtractionError
+from intuned_browser.ai.types import ImageBufferContentItem
+from intuned_browser.ai.types import ImageObject
+from intuned_browser.ai.types import ImageUrlContentItem
+from intuned_browser.ai.types import TextContentItem
+
+__all__ = [
+    "extract_structured_data",
+    "is_page_loaded",
+    "TextContentItem",
+    "ContentItem",
+    "ImageBufferContentItem",
+    "ImageObject",
+    "ImageUrlContentItem",
+    "DataExtractionError",
+]

intuned_browser-0.1.0/intuned_browser/ai/extract_structured_data.py

@@ -0,0 +1,409 @@
+import logging
+from typing import Any
+from typing import Literal
+from typing import overload
+
+from playwright.async_api import Locator
+from playwright.async_api import Page
+
+from intuned_browser.ai.extract_structured_data_using_ai import extract_structured_data_using_ai
+from intuned_browser.ai.types import ContentItem
+from intuned_browser.ai.types import ImageObject
+from intuned_browser.ai.types import JsonSchema  # Import TypedDict for autocomplete
+from intuned_browser.ai.types import SUPPORTED_MODELS
+from intuned_browser.ai.utils import compress_string_spaces
+from intuned_browser.ai.utils.build_images import build_images_from_page_or_handle
+from intuned_browser.ai.utils.matching.matching import create_xpath_mapping
+from intuned_browser.ai.utils.matching.matching import validate_xpath_mapping
+from intuned_browser.ai.utils.validate_schema import check_all_types_are_strings
+from intuned_browser.ai.utils.validate_schema import validate_schema
+from intuned_browser.common.hash_object import hash_object
+from intuned_browser.helpers.extract_markdown import extract_markdown
+from intuned_browser.helpers.utils.get_simplified_html import get_simplified_html
+from intuned_browser.intuned_services import cache
+
+logger = logging.getLogger(__name__)
+
+
+# Overload for page/locator-based extraction
+@overload
+async def extract_structured_data(
+    source: Page | Locator,
+    data_schema: JsonSchema,
+    *,
+    prompt: str | None = None,
+    strategy: Literal["IMAGE", "MARKDOWN", "HTML"] = "HTML",
+    model: SUPPORTED_MODELS = "claude-3-5-haiku-latest",
+    api_key: str | None = None,
+    enable_dom_matching: bool | None = False,
+    enable_cache: bool | None = True,
+    max_retires: int | None = 3,
+) -> Any: ...
+
+
+# Overload for content-based extraction
+@overload
+async def extract_structured_data(
+    content: list[ContentItem] | ContentItem,
+    data_schema: JsonSchema,
+    *,
+    prompt: str | None = None,
+    max_retires: int | None = 3,
+    enable_cache: bool | None = True,
+    model: SUPPORTED_MODELS = "claude-3-5-haiku-latest",
+    api_key: str | None = None,
+) -> Any: ...
+
+
+async def extract_structured_data(
+    source: Page | Locator | None = None,
+    data_schema: JsonSchema | None = None,
+    *,
+    content: list[ContentItem] | ContentItem | None = None,
+    prompt: str | None = None,
+    strategy: Literal["IMAGE", "MARKDOWN", "HTML"] = "HTML",
+    enable_dom_matching: bool | None = False,
+    enable_cache: bool | None = True,
+    max_retires: int | None = 3,
+    model: SUPPORTED_MODELS = "claude-3-5-haiku-latest",
+    api_key: str | None = None,
+) -> Any:
+    # Handle content-based extraction
+    if content is not None and source is None:
+        if data_schema is None:
+            raise ValueError("data_schema is required for content-based extraction")
+        return await _extract_structured_data_from_content(
+            content=content,
+            data_schema=data_schema,
+            prompt=prompt,
+            model=model,
+            api_key=api_key,
+            max_retires=max_retires,
+            enable_cache=enable_cache,
+        )
+
+    # Handle page/locator-based extraction
+    if source is None or data_schema is None:
+        raise ValueError("source and data_schema are required for page/locator-based extraction")
+
+    page_or_locator = source
+
+    # Validate input using pydantic models
+    try:
+        # Convert TypedDict to Pydantic for validation
+        parsed_schema = validate_schema(data_schema)
+        if not parsed_schema:
+            raise ValueError("Invalid data schema provided.")
+    except Exception as e:
+        raise ValueError(f"Invalid extract data input: {str(e)}") from e
+
+    page_object = page_or_locator if isinstance(page_or_locator, Page) else page_or_locator.page
+
+    # deny DOM matching if the schema is not valid
+    if enable_dom_matching and not check_all_types_are_strings(parsed_schema):
+        raise ValueError("For DOM matching, all types of the extraction fields must be STRINGS, to match with the DOM.")
+
+    # We have 3 kind of extractions: image, html and markdown. These 3 strategies will call the same model, the only difference is what we pass to it.
+    if strategy == "HTML":
+        if not isinstance(page_or_locator, Page):
+            container_handle = await page_or_locator.element_handle()
+        else:
+            container_handle = await page_or_locator.locator("html").element_handle()
+
+        # Get simplified HTML
+        simplified_html = await get_simplified_html(container_handle)
+        cache_key = None
+        # Create cache key
+        if enable_cache:
+            cache_key = hash_object(
+                {
+                    "pageUrl": page_object.url,
+                    "data_schema": parsed_schema.model_dump()
+                    if hasattr(parsed_schema, "model_dump")
+                    else parsed_schema,
+                    "model": model,
+                    "strategy": strategy,
+                    "prompt": prompt,
+                    "search_region": str(page_or_locator) if isinstance(page_or_locator, Locator) else "",
+                    **({"html": compress_string_spaces(simplified_html)} if not enable_dom_matching else {}),
+                },
+                treat_arrays_as_unsorted_lists=True,
+            )
+
+            # Check cache
+            cached_result = await cache.get(cache_key)
+            if cached_result:
+                # dom matching is enabled and the result is cached, check if xpaths still have the matched text
+                if enable_dom_matching and isinstance(cached_result, dict) and "matchesMapping" in cached_result:
+                    # Validate DOM matches using XPath mapping
+                    is_valid = await validate_xpath_mapping(page_object, cached_result["matchesMapping"])
+                    if is_valid:
+                        logger.info("Returning cached result with valid DOM matching")
+                        return cached_result["result"]
+                elif not enable_dom_matching:
+                    logger.info("Returning cached result")
+                    return cached_result
+
+        # Extract using AI
+        result = await extract_structured_data_using_ai(
+            page=page_object,
+            api_key=api_key,
+            enable_dom_matching=enable_dom_matching,
+            json_schema=data_schema,
+            model=model,
+            content=simplified_html,
+            prompt=prompt,
+            images=[],
+            max_retries=max_retires,
+        )
+        if not result:
+            raise Exception(result["error"]["context"])
+
+        if enable_cache:
+            # Cache result
+            if not enable_dom_matching:
+                await cache.set(cache_key, result.extracted_data)
+            else:
+                # Create XPath mapping for DOM validation
+                dom_validation_hash = await create_xpath_mapping(page_object, result.extracted_data)
+                results_to_cache = {"result": result.extracted_data, "matchesMapping": dom_validation_hash}
+                await cache.set(cache_key, results_to_cache)
+
+        return result.extracted_data
+
+    elif strategy == "IMAGE":
+        # Get container handle
+        container_handle = None
+        if isinstance(page_or_locator, Locator):
+            container_handle = await page_or_locator.element_handle()
+
+        # Build images
+        images = await build_images_from_page_or_handle(page_object, container_handle)
+
+        # Create cache key
+        cache_key = hash_object(
+            {
+                "pageUrl": page_object.url,
+                "data_schema": parsed_schema.model_dump() if hasattr(parsed_schema, "model_dump") else parsed_schema,
+                "model": model,
+                "strategy": strategy,
+                "prompt": prompt,
+                "search_region": str(page_or_locator) if isinstance(page_or_locator, Locator) else "",
+                **({"html": await page_object.locator("html").inner_html()} if not enable_dom_matching else {}),
+            },
+            treat_arrays_as_unsorted_lists=True,
+        )
+
+        # Check cache
+        if enable_cache:
+            cached_result = await cache.get(cache_key)
+            if cached_result:
+                if enable_dom_matching and isinstance(cached_result, dict) and "matchesMapping" in cached_result:
+                    # Validate DOM matches using XPath mapping
+                    is_valid = await validate_xpath_mapping(page_object, cached_result["matchesMapping"])
+                    if is_valid:
+                        logger.info("Returning cached result with valid DOM matching")
+                        return cached_result["result"]
+                elif not enable_dom_matching:
+                    logger.info("Returning cached result")
+                    return cached_result
+
+        # Extract using AI
+        result = await extract_structured_data_using_ai(
+            page=page_object,
+            api_key=api_key,
+            enable_dom_matching=enable_dom_matching,
+            json_schema=data_schema,
+            model=model,
+            content="Extract structured data from the following images.",
+            prompt=prompt,
+            images=images,
+            max_retries=max_retires,
+        )
+
+        if not result:
+            raise Exception(result["error"]["context"])
+
+        # Cache result
+        if enable_cache:
+            if not enable_dom_matching:
+                await cache.set(cache_key, result.extracted_data)
+            else:
+                # Create XPath mapping for DOM validation
+                dom_validation_hash = await create_xpath_mapping(page_object, result.extracted_data)
+                results_to_cache = {"result": result.extracted_data, "matchesMapping": dom_validation_hash}
+                await cache.set(cache_key, results_to_cache)
+
+        return result.extracted_data
+
+    elif strategy == "MARKDOWN":
+        # Get container handle
+        container_handle = None
+        if isinstance(page_or_locator, Locator):
+            container_handle = await page_or_locator.element_handle()
+        else:
+            container_handle = await page_or_locator.locator("html").element_handle()
+
+        # Get page metadata
+        page_title = await page_object.title()
+        page_url = page_object.url
+
+        # Convert HTML to markdown
+        markdown_content = await extract_markdown(page_object)
+
+        cache_key = hash_object(
+            {
+                "pageUrl": page_object.url,
+                "data_schema": parsed_schema.model_dump() if hasattr(parsed_schema, "model_dump") else parsed_schema,
+                "model": model,
+                "strategy": strategy,
+                "prompt": prompt,
+                "search_region": str(page_or_locator) if isinstance(page_or_locator, Locator) else "",
+                **(
+                    {"html": await page_object.locator("html").inner_html(), "markdown": markdown_content}
+                    if not enable_dom_matching
+                    else {}
+                ),
+            },
+            treat_arrays_as_unsorted_lists=True,
+        )
+
+        # Check cache
+        if enable_cache:
+            cached_result = await cache.get(cache_key)
+            if cached_result:
+                if enable_dom_matching and isinstance(cached_result, dict) and "matchesMapping" in cached_result:
+                    # Validate DOM matches using XPath mapping
+                    is_valid = await validate_xpath_mapping(page_object, cached_result["matchesMapping"])
+                    if is_valid:
+                        logger.info("Returning cached result with valid DOM matching")
+                        return cached_result["result"]
+                elif not enable_dom_matching:
+                    logger.info("Returning cached result")
+                    return cached_result
+
+        # Extract using AI
+        result = await extract_structured_data_using_ai(
+            page=page_object,
+            api_key=api_key,
+            enable_dom_matching=enable_dom_matching,
+            json_schema=data_schema,
+            model=model,
+            content=markdown_content,
+            prompt=prompt,
+            images=[],
+            max_retries=max_retires,
+        )
+        if not result:
+            raise Exception(result["error"]["context"])
+
+        # Cache result
+        if enable_cache:
+            if not enable_dom_matching:
+                await cache.set(cache_key, result.extracted_data)
+            else:
+                # Create XPath mapping for DOM validation
+                dom_validation_hash = await create_xpath_mapping(page_object, result.extracted_data)
+                results_to_cache = {"result": result.extracted_data, "matchesMapping": dom_validation_hash}
+                await cache.set(cache_key, results_to_cache)
+
+        return result.extracted_data
+
+
+import aiohttp
+
+
+async def _extract_structured_data_from_content(
+    content: list[ContentItem] | ContentItem,
+    data_schema: JsonSchema,
+    prompt: str | None = None,
+    model: SUPPORTED_MODELS = "claude-3-5-haiku-latest",
+    api_key: str | None = None,
+    max_retires: int | None = 3,
+    enable_cache: bool | None = True,
+) -> Any:
+    # Validate schema
+    try:
+        parsed_schema = validate_schema(data_schema)
+        if not parsed_schema:
+            raise ValueError("Invalid data schema provided.")
+    except Exception as e:
+        raise ValueError(f"Invalid extract data input: {str(e)}") from e
+
+    # Normalize content to list
+    content_list = content if isinstance(content, list) else [content]
+
+    # Process images from buffers - create ImageObject format
+    images_from_buffers: list[ImageObject] = [
+        {
+            "image_type": item["image_type"],
+            "data": item["data"],
+        }
+        for item in content_list
+        if item["type"] == "image-buffer"
+    ]
+
+    # Process images from URLs - create ImageObject format
+    images_from_urls: list[ImageObject] = []
+    for item in content_list:
+        if item["type"] == "image-url":
+            try:
+                async with aiohttp.ClientSession() as session:
+                    async with session.get(item["data"], ssl=False) as response:
+                        if response.status == 200:
+                            buffer = await response.read()
+                            images_from_urls.append(
+                                {
+                                    "image_type": item["image_type"],
+                                    "data": buffer,
+                                }
+                            )
+                        else:
+                            raise Exception(f"HTTP {response.status}")
+            except Exception as e:
+                raise ValueError(f"Fetching image from URL {item['data']} failed: {e}") from e
+
+    # Combine all images as list[ImageObject]
+    images = images_from_urls + images_from_buffers
+
+    # Extract text content
+    texts = [item["data"] for item in content_list if item["type"] == "text"]
+
+    # Create cache key if caching is enabled
+    cache_key = None
+    if enable_cache:
+        cache_key = hash_object(
+            {
+                "system_message": prompt,
+                "images": [{"image_type": img["image_type"], "data": img["data"].hex()} for img in images],
+                "json_schema": parsed_schema.model_dump() if hasattr(parsed_schema, "model_dump") else parsed_schema,
+                "model": model,
+                "text": texts,
+            },
+            treat_arrays_as_unsorted_lists=False,
+        )
+
+        # Check cache
+        cached_result = await cache.get(cache_key)
+        if cached_result:
+            logger.info("Returning cached result")
+            return cached_result
+
+    # Extract using AI
+    result = await extract_structured_data_using_ai(
+        api_key=api_key,
+        enable_dom_matching=False,
+        json_schema=data_schema,
+        model=model,
+        content="\n".join(texts),
+        prompt=prompt,
+        images=images,
+        max_retries=max_retires,
+    )
+
+    # Cache result if caching is enabled
+    if enable_cache and cache_key:
+        await cache.set(cache_key, result.extracted_data)
+    if not result.extracted_data:
+        logger.warning("No extracted data found, returning None")
+    return result.extracted_data