cat-web 0.1.0__py3-none-any.whl

cat_web-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: cat-web
+Version: 0.1.0
+Summary: LLM-powered classification and extraction for web content
+Project-URL: Documentation, https://github.com/chrissoria/cat-web#readme
+Project-URL: Issues, https://github.com/chrissoria/cat-web/issues
+Project-URL: Source, https://github.com/chrissoria/cat-web
+Author-email: Chris Soria <chrissoria@berkeley.edu>
+License-Expression: GPL-3.0-or-later
+Keywords: llm,structured output,text classification,url classification,web content
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+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 :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+Requires-Dist: cat-stack>=0.1.0
+Requires-Dist: pandas
+Requires-Dist: requests
+Requires-Dist: tqdm
+Provides-Extra: pdf
+Requires-Dist: cat-stack[pdf]; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# CatWeb
+
+LLM-powered classification, extraction, and summarization for web content.
+
+Part of the [CatLLM ecosystem](https://github.com/chrissoria/cat-llm). Thin wrapper around [cat-stack](https://github.com/chrissoria/cat-stack) that adds URL fetching and web-specific context injection.
+
+## Installation
+
+```bash
+pip install cat-web        # pulls in cat-stack automatically
+pip install cat-web[pdf]   # with PDF support
+```
+
+## Quick Start
+
+```python
+import catweb as cat
+
+# Classify web pages by topic
+results = cat.classify(
+    categories=["News", "Opinion", "Tutorial", "Reference"],
+    input_data=[
+        "https://example.com/article1",
+        "https://example.com/article2",
+    ],
+    api_key="your-api-key",
+)
+
+# Extract categories from web content
+extracted = cat.extract(
+    input_data=["https://example.com/page1", "https://example.com/page2"],
+    description="Blog posts about technology",
+    api_key="your-api-key",
+)
+
+# Summarize web pages
+summaries = cat.summarize(
+    input_data=["https://example.com/article1"],
+    description="News articles",
+    api_key="your-api-key",
+)
+```
+
+## How It Works
+
+CatWeb accepts URLs as input, fetches the web content, strips HTML to plain text, and passes the text through cat-stack's classification/extraction/summarization pipeline. Original URLs are preserved in the output DataFrame's `survey_input` column.
+
+You can also pass pre-fetched text directly — CatWeb auto-detects whether input is URLs or plain text.
+
+## API Reference
+
+### `classify(categories, input_data, api_key, ...)`
+
+Classify web content into predefined categories.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `categories` | list | Category names for classification |
+| `input_data` | list/Series | URLs or text strings to classify |
+| `api_key` | str | API key for the model provider |
+| `source_domain` | str | Source domain (injected as prompt context) |
+| `content_type` | str | Content type, e.g. "news article", "blog post" |
+| `web_metadata` | dict | Additional key-value context for the prompt |
+| `timeout` | int | URL fetch timeout in seconds (default 30) |
+| `**kwargs` | | All cat-stack classify() parameters (models, creativity, batch_mode, etc.) |
+
+### `extract(input_data, api_key, ...)`
+
+Discover categories from web content.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `input_data` | list/Series | URLs or text strings |
+| `api_key` | str | API key |
+| `source_domain` | str | Source domain context |
+| `content_type` | str | Content type context |
+| `web_metadata` | dict | Additional context |
+| `timeout` | int | URL fetch timeout (default 30) |
+| `**kwargs` | | All cat-stack extract() parameters |
+
+### `explore(input_data, api_key, ...)`
+
+Raw category extraction (with duplicates) for saturation analysis.
+
+Same parameters as `extract()`, plus all cat-stack `explore()` parameters.
+
+### `summarize(input_data, ...)`
+
+Summarize web content.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `input_data` | list/Series | URLs or text strings |
+| `source_domain` | str | Source domain context |
+| `content_type` | str | Content type context |
+| `web_metadata` | dict | Additional context |
+| `timeout` | int | URL fetch timeout (default 30) |
+| `**kwargs` | | All cat-stack summarize() parameters (api_key, description, models, etc.) |
+
+### Web Utilities
+
+```python
+from catweb import is_url, fetch_url_text, fetch_urls
+
+# Check if a string is a URL
+is_url("https://example.com")  # True
+is_url("just text")            # False
+
+# Fetch a single URL
+text, error = fetch_url_text("https://example.com")
+
+# Fetch multiple URLs
+results = fetch_urls(["https://a.com", "https://b.com"])
+# Returns: [(url, text, error), ...]
+```
+
+## Multi-Model Ensemble
+
+All cat-stack ensemble features work through `**kwargs`:
+
+```python
+results = cat.classify(
+    categories=["Positive", "Negative", "Neutral"],
+    input_data=urls,
+    models=[
+        ("gpt-4o", "openai", "sk-..."),
+        ("claude-sonnet-4-5-20250929", "anthropic", "sk-ant-..."),
+    ],
+    consensus_threshold="majority",
+)
+```
+
+## License
+
+GPL-3.0-or-later

cat_web-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+catweb/__about__.py,sha256=0QOx69kyMOxznoYuYoBJvqInc9Yo9mtwrFDC1PMYELg,368
+catweb/__init__.py,sha256=_EzIU2RoyRRejLj9kuIzmuaJd6u1ImIFqPFbi5N6C5g,3075
+catweb/_web_fetch.py,sha256=MSB9VUJm4A0sd089-lHQRIBUa7E3oY97trSfTZNIRQA,424
+catweb/classify.py,sha256=2VOF1yGSsoA9M-B0-MNDeT1AxoaFh9sLDprj1cFAC-Y,6730
+catweb/explore.py,sha256=7RBtUAWAmeA_a5tX8KaAU-A_TZ-8sG7bvnJmDd65_oQ,3880
+catweb/extract.py,sha256=T-7jST1OTKYPnyu70-dJJOvWLPAnZbZXrq_x9qW3YNI,3812
+catweb/summarize.py,sha256=jdlO5N5EdbV08ja0O2--IQIF154XafymOuNFtmdzdEI,3916
+cat_web-0.1.0.dist-info/METADATA,sha256=Nk3lVgu7clOqe-wre8-4-0CwVPPXCJsbMN8L87t9mXg,5345
+cat_web-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cat_web-0.1.0.dist-info/RECORD,,

cat_web-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

catweb/__about__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2025-present Christopher Soria <chrissoria@berkeley.edu>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+__version__ = "0.1.0"
+__author__ = "Christopher Soria"
+__description__ = "LLM-powered classification and extraction for web content"
+__title__ = "cat-web"
+__url__ = "https://github.com/chrissoria/cat-web"
+__license__ = "GPL-3.0-or-later"

catweb/__init__.py

@@ -0,0 +1,113 @@
+# SPDX-FileCopyrightText: 2025-present Christopher Soria <chrissoria@berkeley.edu>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from .__about__ import (
+    __version__,
+    __author__,
+    __description__,
+    __title__,
+    __url__,
+    __license__,
+)
+
+# =============================================================================
+# Public API — catweb entry points (thin wrappers around cat_stack)
+# =============================================================================
+from .classify import classify
+from .extract import extract
+from .explore import explore
+from .summarize import summarize
+
+# =============================================================================
+# Web fetching utilities (catweb-specific)
+# =============================================================================
+from ._web_fetch import (
+    is_url,
+    fetch_url_text,
+    fetch_urls,
+    detect_url_input,
+    strip_html_tags,
+)
+
+# =============================================================================
+# Re-exports from cat_stack (backward compatibility + provider utilities)
+# =============================================================================
+from cat_stack import (
+    # Category analysis
+    has_other_category,
+    check_category_verbosity,
+    # Batch exceptions
+    BatchJobExpiredError,
+    BatchJobFailedError,
+    # Provider utilities
+    UnifiedLLMClient,
+    detect_provider,
+    set_ollama_endpoint,
+    check_ollama_running,
+    list_ollama_models,
+    check_ollama_model,
+    pull_ollama_model,
+    PROVIDER_CONFIG,
+    # Deprecated backward-compat functions
+    explore_common_categories,
+    explore_corpus,
+    explore_image_categories,
+    explore_pdf_categories,
+    classify_ensemble,
+    multi_class,
+    image_multi_class,
+    pdf_multi_class,
+    summarize_ensemble,
+    # Utilities
+    build_json_schema,
+    extract_json,
+    validate_classification_json,
+    image_score_drawing,
+    image_features,
+)
+
+# Define public API
+__all__ = [
+    # Main entry points (catweb wrappers)
+    "classify",
+    "extract",
+    "explore",
+    "summarize",
+    # Web fetching utilities
+    "is_url",
+    "fetch_url_text",
+    "fetch_urls",
+    "detect_url_input",
+    "strip_html_tags",
+    # Category analysis (from cat_stack)
+    "has_other_category",
+    "check_category_verbosity",
+    # Batch exceptions (from cat_stack)
+    "BatchJobExpiredError",
+    "BatchJobFailedError",
+    # Provider utilities (from cat_stack)
+    "UnifiedLLMClient",
+    "detect_provider",
+    "set_ollama_endpoint",
+    "check_ollama_running",
+    "list_ollama_models",
+    "check_ollama_model",
+    "pull_ollama_model",
+    "PROVIDER_CONFIG",
+    # Deprecated backward-compat (from cat_stack)
+    "explore_common_categories",
+    "explore_corpus",
+    "explore_image_categories",
+    "explore_pdf_categories",
+    "classify_ensemble",
+    "summarize_ensemble",
+    "multi_class",
+    "image_multi_class",
+    "pdf_multi_class",
+    "image_score_drawing",
+    "image_features",
+    "build_json_schema",
+    "extract_json",
+    "validate_classification_json",
+]

catweb/_web_fetch.py

@@ -0,0 +1,22 @@
+"""
+Re-export web fetching utilities from cat_stack.
+
+These functions now live in cat_stack._web_fetch. This module re-exports
+them for backward compatibility within cat-web.
+"""
+
+from cat_stack._web_fetch import (
+    is_url,
+    fetch_url_text,
+    fetch_urls,
+    detect_url_input,
+    strip_html_tags,
+)
+
+__all__ = [
+    "is_url",
+    "fetch_url_text",
+    "fetch_urls",
+    "detect_url_input",
+    "strip_html_tags",
+]

catweb/classify.py

@@ -0,0 +1,184 @@
+"""
+Classification functions for CatWeb.
+
+Thin wrapper around cat_stack.classify() that adds web-specific features:
+- URL fetching (accepts list of URLs as input_data)
+- Web context injection (source_domain, content_type)
+- Post-classification URL preservation (original URLs in input_data column)
+"""
+
+import cat_stack
+
+from ._web_fetch import fetch_urls, is_url
+
+__all__ = [
+    "classify",
+]
+
+
+def _normalize_url_list(input_data):
+    """Normalize input_data to a list of URL strings."""
+    if isinstance(input_data, str):
+        return [input_data]
+    elif hasattr(input_data, 'tolist'):
+        return input_data.tolist()
+    else:
+        return list(input_data)
+
+
+def _build_web_context(source_domain, content_type, web_metadata):
+    """Build a context block string from web content metadata fields."""
+    parts = []
+    if source_domain:
+        parts.append(f"Source domain: {source_domain}")
+    if content_type:
+        parts.append(f"Content type: {content_type}")
+    if web_metadata:
+        for k, v in web_metadata.items():
+            parts.append(f"{k.capitalize()}: {v}")
+    return "\n".join(parts)
+
+
+def classify(
+    categories,
+    input_data=None,
+    api_key=None,
+    # Web context fields — injected into the classification prompt
+    source_domain: str = None,
+    content_type: str = None,
+    web_metadata: dict = None,
+    description="",
+    filename=None,
+    save_directory=None,
+    timeout: int = 30,
+    **kwargs,
+):
+    """
+    Classify web content (URLs) with web-specific features.
+
+    Wraps cat_stack.classify() and adds:
+    - Automatic URL fetching (pass a list of URLs as input_data)
+    - Web context injection into the classification prompt
+    - Original URLs preserved in the input_data column
+
+    Args:
+        categories (list): List of category names for classification.
+        input_data: The data to classify. Can be:
+            - List of URLs (auto-fetched and classified as text)
+            - List of text strings (classified directly, no fetching)
+            - pandas Series of URLs or text
+        api_key (str): API key for the model provider (single-model mode).
+        source_domain (str): Source domain — injected into the prompt as context.
+        content_type (str): Content type (e.g., "news article", "blog post").
+        web_metadata (dict): Additional context injected into the prompt.
+        description (str): Description of the input data context.
+        filename (str): Output filename for CSV.
+        save_directory (str): Directory to save results.
+        timeout (int): Timeout in seconds for URL fetching. Default 30.
+        **kwargs: All other parameters passed through to cat_stack.classify()
+            (e.g. user_model, models, creativity, batch_mode, consensus_threshold,
+            chain_of_thought, thinking_budget, embeddings, etc.)
+
+    Returns:
+        pd.DataFrame: Results with classification columns. When URLs are
+        provided, the input_data column contains the original URLs
+        (not the fetched content).
+
+    Examples:
+        >>> import catweb as cat
+        >>>
+        >>> # Classify web pages by topic
+        >>> results = cat.classify(
+        ...     categories=["News", "Opinion", "Tutorial", "Reference"],
+        ...     input_data=["https://example.com/article1", "https://example.com/article2"],
+        ...     api_key="your-api-key",
+        ... )
+        >>>
+        >>> # Classify with web context
+        >>> results = cat.classify(
+        ...     input_data=urls,
+        ...     categories=["Positive", "Negative", "Neutral"],
+        ...     source_domain="news.ycombinator.com",
+        ...     content_type="forum discussion",
+        ...     api_key="your-api-key",
+        ... )
+        >>>
+        >>> # Classify pre-fetched text (no URL fetching)
+        >>> results = cat.classify(
+        ...     input_data=["Some text content...", "More text..."],
+        ...     categories=["Tech", "Science", "Politics"],
+        ...     api_key="your-api-key",
+        ... )
+    """
+    # Early validation
+    if api_key is None and kwargs.get("models") is None:
+        raise ValueError(
+            "[CatWeb] api_key is required. Pass api_key='sk-...' or use the "
+            "models= parameter for multi-model mode."
+        )
+
+    if input_data is None:
+        raise ValueError("[CatWeb] input_data is required.")
+
+    # Check if input is URLs — fetch content if so
+    _url_originals = None
+    from ._web_fetch import detect_url_input
+    if detect_url_input(input_data):
+        url_list = _normalize_url_list(input_data)
+        print(f"[CatWeb] Fetching content from {len(url_list)} URLs...")
+        url_results = fetch_urls(url_list, timeout=timeout)
+
+        _url_originals = []
+        fetched_texts = []
+        success_count = 0
+        for url, text, error in url_results:
+            _url_originals.append(url)
+            if error:
+                print(f"  Warning: {error}")
+                fetched_texts.append("")
+            else:
+                fetched_texts.append(text)
+                success_count += 1
+
+        print(f"[CatWeb] Successfully fetched {success_count}/{len(url_list)} URLs")
+        input_data = fetched_texts
+
+    # Prepend web context to description if any fields provided
+    web_context = _build_web_context(source_domain, content_type, web_metadata)
+    if web_context:
+        description = f"{web_context}\n{description}".strip() if description else web_context
+
+    # Remove keys we set explicitly to avoid "multiple values" if caller also passes them
+    kwargs.pop("add_other", None)
+    kwargs.pop("check_verbosity", None)
+
+    result = cat_stack.classify(
+        input_data=input_data,
+        categories=categories,
+        api_key=api_key,
+        description=description,
+        add_other=False,
+        check_verbosity=False,
+        filename=None if _url_originals else filename,
+        save_directory=None if _url_originals else save_directory,
+        **kwargs,
+    )
+
+    # Replace fetched text with original URLs in input_data column
+    if _url_originals is not None:
+        result = result.reset_index(drop=True)
+        if "input_data" in result.columns:
+            result["input_data"] = _url_originals
+        # Save with URLs if filename was requested
+        if filename or save_directory:
+            import os as _os
+            out = filename
+            if save_directory and filename:
+                out = _os.path.join(save_directory, _os.path.basename(filename))
+            elif save_directory:
+                out = _os.path.join(save_directory, "results.csv")
+            if out:
+                result.to_csv(out, index=False)
+                print(f"Results saved to {out}")
+
+    return result

catweb/explore.py

@@ -0,0 +1,114 @@
+"""
+Category exploration functions for CatWeb.
+
+Thin wrapper around cat_stack.explore() that adds web-specific features:
+- URL fetching (accepts list of URLs as input_data)
+- Web context injection
+"""
+
+import cat_stack
+
+from ._web_fetch import fetch_urls, detect_url_input
+
+__all__ = [
+    "explore",
+]
+
+
+def explore(
+    input_data=None,
+    api_key=None,
+    # Web context fields
+    source_domain: str = None,
+    content_type: str = None,
+    web_metadata: dict = None,
+    description="",
+    timeout: int = 30,
+    **kwargs,
+):
+    """
+    Explore categories in web content, returning the raw extracted list.
+
+    Wraps cat_stack.explore() and adds:
+    - Automatic URL fetching (pass a list of URLs as input_data)
+    - Web context injection into the exploration prompt
+
+    Unlike extract(), which normalizes and merges categories, explore()
+    returns every category string from every chunk across every iteration
+    — with duplicates intact.
+
+    Args:
+        input_data: The data to explore. Can be:
+            - List of URLs (auto-fetched and processed as text)
+            - List of text strings (processed directly)
+            - pandas Series of URLs or text
+        api_key (str): API key for the model provider.
+        source_domain (str): Source domain — injected into the prompt as context.
+        content_type (str): Content type (e.g., "news article", "blog post").
+        web_metadata (dict): Additional context injected into the prompt.
+        description (str): Description of the input data context.
+        timeout (int): Timeout in seconds for URL fetching. Default 30.
+        **kwargs: All other parameters passed through to cat_stack.explore()
+            (e.g. max_categories, categories_per_chunk, divisions, user_model,
+            creativity, specificity, research_question, filename, model_source,
+            iterations, random_state, focus, etc.)
+
+    Returns:
+        list[str]: Every category string extracted from every chunk across
+        every iteration.
+
+    Examples:
+        >>> import catweb as cat
+        >>>
+        >>> raw_categories = cat.explore(
+        ...     input_data=["https://example.com/page1", "https://example.com/page2"],
+        ...     description="News articles",
+        ...     api_key="your-api-key",
+        ...     iterations=3,
+        ... )
+        >>> print(raw_categories[:5])
+    """
+    if api_key is None:
+        raise ValueError(
+            "[CatWeb] api_key is required. Pass api_key='sk-...'."
+        )
+
+    if input_data is None:
+        raise ValueError("[CatWeb] input_data is required.")
+
+    # Check if input is URLs — fetch content if so
+    if detect_url_input(input_data):
+        if isinstance(input_data, str):
+            url_list = [input_data]
+        elif hasattr(input_data, 'tolist'):
+            url_list = input_data.tolist()
+        else:
+            url_list = list(input_data)
+
+        print(f"[CatWeb] Fetching content from {len(url_list)} URLs for exploration...")
+        url_results = fetch_urls(url_list, timeout=timeout)
+
+        input_data = [text if text else "" for _, text, error in url_results]
+        success_count = sum(1 for _, _, e in url_results if not e)
+        print(f"[CatWeb] Successfully fetched {success_count}/{len(url_list)} URLs")
+
+    # Build web context
+    parts = []
+    if source_domain:
+        parts.append(f"Source domain: {source_domain}")
+    if content_type:
+        parts.append(f"Content type: {content_type}")
+    if web_metadata:
+        for k, v in web_metadata.items():
+            parts.append(f"{k.capitalize()}: {v}")
+    web_context = "\n".join(parts)
+
+    if web_context:
+        description = f"{web_context}\n{description}".strip() if description else web_context
+
+    return cat_stack.explore(
+        input_data=input_data,
+        api_key=api_key,
+        description=description,
+        **kwargs,
+    )

catweb/extract.py

@@ -0,0 +1,112 @@
+"""
+Category extraction functions for CatWeb.
+
+Thin wrapper around cat_stack.extract() that adds web-specific features:
+- URL fetching (accepts list of URLs as input_data)
+- Web context injection
+"""
+
+import cat_stack
+
+from ._web_fetch import fetch_urls, detect_url_input
+
+__all__ = [
+    "extract",
+]
+
+
+def extract(
+    input_data=None,
+    api_key=None,
+    # Web context fields
+    source_domain: str = None,
+    content_type: str = None,
+    web_metadata: dict = None,
+    description="",
+    timeout: int = 30,
+    **kwargs,
+):
+    """
+    Extract categories from web content (URLs or text).
+
+    Wraps cat_stack.extract() and adds:
+    - Automatic URL fetching (pass a list of URLs as input_data)
+    - Web context injection into the extraction prompt
+
+    Args:
+        input_data: The data to explore. Can be:
+            - List of URLs (auto-fetched and processed as text)
+            - List of text strings (processed directly)
+            - pandas Series of URLs or text
+        api_key (str): API key for the model provider.
+        source_domain (str): Source domain — injected into the prompt as context.
+        content_type (str): Content type (e.g., "news article", "blog post").
+        web_metadata (dict): Additional context injected into the prompt.
+        description (str): Description of the input data context.
+        timeout (int): Timeout in seconds for URL fetching. Default 30.
+        **kwargs: All other parameters passed through to cat_stack.extract()
+            (e.g. max_categories, categories_per_chunk, divisions, user_model,
+            creativity, specificity, research_question, filename, model_source,
+            iterations, random_state, focus, etc.)
+
+    Returns:
+        dict with keys:
+            - counts_df: DataFrame of categories with counts
+            - top_categories: List of top category names
+            - raw_top_text: Raw model output from final merge step
+
+    Examples:
+        >>> import catweb as cat
+        >>>
+        >>> # Extract categories from web pages
+        >>> results = cat.extract(
+        ...     input_data=["https://example.com/page1", "https://example.com/page2"],
+        ...     description="News articles",
+        ...     api_key="your-api-key",
+        ... )
+        >>> print(results['top_categories'])
+    """
+    if api_key is None:
+        raise ValueError(
+            "[CatWeb] api_key is required. Pass api_key='sk-...'."
+        )
+
+    if input_data is None:
+        raise ValueError("[CatWeb] input_data is required.")
+
+    # Check if input is URLs — fetch content if so
+    if detect_url_input(input_data):
+        if isinstance(input_data, str):
+            url_list = [input_data]
+        elif hasattr(input_data, 'tolist'):
+            url_list = input_data.tolist()
+        else:
+            url_list = list(input_data)
+
+        print(f"[CatWeb] Fetching content from {len(url_list)} URLs for extraction...")
+        url_results = fetch_urls(url_list, timeout=timeout)
+
+        input_data = [text if text else "" for _, text, error in url_results]
+        success_count = sum(1 for _, _, e in url_results if not e)
+        print(f"[CatWeb] Successfully fetched {success_count}/{len(url_list)} URLs")
+
+    # Build web context
+    parts = []
+    if source_domain:
+        parts.append(f"Source domain: {source_domain}")
+    if content_type:
+        parts.append(f"Content type: {content_type}")
+    if web_metadata:
+        for k, v in web_metadata.items():
+            parts.append(f"{k.capitalize()}: {v}")
+    web_context = "\n".join(parts)
+
+    if web_context:
+        description = f"{web_context}\n{description}".strip() if description else web_context
+
+    return cat_stack.extract(
+        input_data=input_data,
+        api_key=api_key,
+        survey_question=description,
+        **kwargs,
+    )

catweb/summarize.py

@@ -0,0 +1,118 @@
+"""
+Summarization functions for CatWeb.
+
+Thin wrapper around cat_stack.summarize() that adds web-specific features:
+- URL fetching (accepts list of URLs as input_data)
+- Web context injection
+- Original URLs preserved in output
+"""
+
+import cat_stack
+
+from ._web_fetch import fetch_urls, detect_url_input
+
+__all__ = [
+    "summarize",
+]
+
+
+def summarize(
+    input_data=None,
+    # Web context fields
+    source_domain: str = None,
+    content_type: str = None,
+    web_metadata: dict = None,
+    timeout: int = 30,
+    **kwargs,
+):
+    """
+    Summarize web content (URLs or text) using LLMs.
+
+    Wraps cat_stack.summarize() and adds:
+    - Automatic URL fetching (pass a list of URLs as input_data)
+    - Web context injection into the summarization prompt
+    - Original URLs preserved in the input_data column
+
+    Args:
+        input_data: Data to summarize. Can be:
+            - List of URLs (auto-fetched and summarized as text)
+            - List of text strings, pandas Series, or single string
+        source_domain (str): Source domain — injected into the prompt as context.
+        content_type (str): Content type (e.g., "news article", "blog post").
+        web_metadata (dict): Additional context injected into the prompt.
+        timeout (int): Timeout in seconds for URL fetching. Default 30.
+        **kwargs: All parameters passed through to cat_stack.summarize()
+            (e.g. api_key, description, instructions, max_length, focus,
+            user_model, models, mode, creativity, batch_mode, etc.)
+
+    Returns:
+        pd.DataFrame: Results with summary column(s). When URLs are
+        provided, the input_data column contains the original URLs.
+
+    Examples:
+        >>> import catweb as cat
+        >>>
+        >>> results = cat.summarize(
+        ...     input_data=["https://example.com/article1", "https://example.com/article2"],
+        ...     description="News articles",
+        ...     api_key="your-api-key",
+        ... )
+    """
+    if input_data is None:
+        raise ValueError("[CatWeb] input_data is required.")
+
+    # Check if input is URLs — fetch content if so
+    _url_originals = None
+    if detect_url_input(input_data):
+        if isinstance(input_data, str):
+            url_list = [input_data]
+        elif hasattr(input_data, 'tolist'):
+            url_list = input_data.tolist()
+        else:
+            url_list = list(input_data)
+
+        print(f"[CatWeb] Fetching content from {len(url_list)} URLs for summarization...")
+        url_results = fetch_urls(url_list, timeout=timeout)
+
+        _url_originals = []
+        fetched_texts = []
+        success_count = 0
+        for url, text, error in url_results:
+            _url_originals.append(url)
+            if error:
+                print(f"  Warning: {error}")
+                fetched_texts.append("")
+            else:
+                fetched_texts.append(text)
+                success_count += 1
+
+        print(f"[CatWeb] Successfully fetched {success_count}/{len(url_list)} URLs")
+        input_data = fetched_texts
+
+    # Build web context and inject into description
+    parts = []
+    if source_domain:
+        parts.append(f"Source domain: {source_domain}")
+    if content_type:
+        parts.append(f"Content type: {content_type}")
+    if web_metadata:
+        for k, v in web_metadata.items():
+            parts.append(f"{k.capitalize()}: {v}")
+    web_context = "\n".join(parts)
+
+    if web_context:
+        desc = kwargs.get("description", "")
+        kwargs["description"] = f"{web_context}\n{desc}".strip() if desc else web_context
+
+    result = cat_stack.summarize(
+        input_data=input_data,
+        **kwargs,
+    )
+
+    # Replace fetched text with original URLs in input_data column
+    if _url_originals is not None:
+        result = result.reset_index(drop=True)
+        if "input_data" in result.columns:
+            result["input_data"] = _url_originals
+
+    return result