recipe-clipper 0.1.0a0__py3-none-any.whl

recipe_clipper/__init__.py

@@ -0,0 +1,7 @@
+"""Recipe clipper library for extracting recipes from websites."""
+
+__version__ = "0.1.0a0"
+
+from recipe_clipper.clipper import clip_recipe
+
+__all__ = ["clip_recipe"]

recipe_clipper/cli.py

@@ -0,0 +1,268 @@
+"""Command-line interface for recipe clipper."""
+
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from dotenv import load_dotenv
+
+from recipe_clipper.clipper import clip_recipe
+from recipe_clipper.parsers.llm_parser import (
+    parse_recipe_from_image,
+    parse_recipe_from_document,
+)
+from recipe_clipper.formatters import (
+    format_recipe_text,
+    format_recipe_json,
+    format_recipe_markdown,
+)
+from recipe_clipper.exceptions import RecipeClipperError
+
+load_dotenv()
+
+
+app = typer.Typer(
+    name="recipe-clipper",
+    help="Extract recipes from websites with ease",
+    add_completion=False,
+)
+console = Console()
+
+
+class OutputFormat(str, Enum):
+    """Supported output formats."""
+
+    text = "text"
+    json = "json"
+    markdown = "markdown"
+
+
+# Helper functions for common CLI operations
+
+
+def _format_recipe(recipe, format: OutputFormat) -> str:
+    """Format recipe based on output format."""
+    if format == OutputFormat.json:
+        return format_recipe_json(recipe)
+    elif format == OutputFormat.markdown:
+        return format_recipe_markdown(recipe)
+    else:
+        return format_recipe_text(recipe)
+
+
+def _write_output(output_text: str, output: Optional[Path]) -> None:
+    """Write output to file or stdout."""
+    if output:
+        output.write_text(output_text)
+        console.print(f"[green]✓[/green] Recipe saved to {output}")
+    else:
+        console.print(output_text)
+
+
+def _handle_recipe_extraction(
+    extract_func, source_description: str, format: OutputFormat, output: Optional[Path]
+) -> None:
+    """Common handler for all recipe extraction commands."""
+    try:
+        with console.status(f"[bold blue]{source_description}..."):
+            recipe = extract_func()
+
+        output_text = _format_recipe(recipe, format)
+        _write_output(output_text, output)
+
+    except RecipeClipperError as e:
+        console.print(f"[red]Error:[/red] {e}", file=sys.stderr)
+        raise typer.Exit(code=1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error:[/red] {e}", file=sys.stderr)
+        raise typer.Exit(code=1)
+
+
+def _validate_file_exists(path: Path, file_type: str) -> None:
+    """Validate that a file exists."""
+    if not path.exists():
+        console.print(f"[red]Error:[/red] {file_type} file not found: {path}", file=sys.stderr)
+        raise typer.Exit(code=1)
+
+
+def _require_api_key(api_key: Optional[str], operation: str) -> str:
+    """Ensure API key is provided, exit if not."""
+    if not api_key:
+        console.print(
+            f"[red]Error:[/red] API key is required for {operation}. "
+            "Set ANTHROPIC_API_KEY environment variable or use --api-key option.",
+            file=sys.stderr,
+        )
+        raise typer.Exit(code=1)
+    return api_key
+
+
+@app.command()
+def clip_webpage(
+    url: str = typer.Argument(..., help="URL of the recipe to extract"),
+    format: OutputFormat = typer.Option(
+        OutputFormat.text,
+        "--format",
+        "-f",
+        help="Output format (text, json, or markdown)",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file path (prints to stdout if not specified)",
+    ),
+    timeout: int = typer.Option(
+        10,
+        "--timeout",
+        "-t",
+        help="HTTP request timeout in seconds",
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="ANTHROPIC_API_KEY",
+        help="Anthropic API key for LLM fallback (can also use ANTHROPIC_API_KEY env var)",
+    ),
+    use_llm_fallback: bool = typer.Option(
+        True,
+        "--use-llm-fallback/--no-llm-fallback",
+        help="Use LLM fallback if recipe-scrapers fails",
+    ),
+):
+    """
+    Extract a recipe from a URL.
+
+    Examples:
+
+        recipe-clipper clip-webpage https://www.allrecipes.com/recipe/10813/best-chocolate-chip-cookies/
+
+        recipe-clipper clip-webpage https://example.com/recipe --format json --output recipe.json
+
+        recipe-clipper clip-webpage https://example.com/recipe --format markdown --output recipe.md
+
+        recipe-clipper clip-webpage https://unsupported-site.com/recipe --api-key sk-ant-... --use-llm-fallback
+    """
+    _handle_recipe_extraction(
+        extract_func=lambda: clip_recipe(
+            url, api_key=api_key, use_llm_fallback=use_llm_fallback, timeout=timeout
+        ),
+        source_description=f"Fetching recipe from {url}",
+        format=format,
+        output=output,
+    )
+
+
+@app.command()
+def clip_image(
+    image_path: Path = typer.Argument(..., help="Path to the recipe image file"),
+    format: OutputFormat = typer.Option(
+        OutputFormat.text,
+        "--format",
+        "-f",
+        help="Output format (text, json, or markdown)",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file path (prints to stdout if not specified)",
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="ANTHROPIC_API_KEY",
+        help="Anthropic API key (required, can also use ANTHROPIC_API_KEY env var)",
+    ),
+    model: str = typer.Option(
+        "claude-sonnet-4-5",
+        "--model",
+        "-m",
+        help="Claude model to use",
+    ),
+):
+    """
+    Extract a recipe from an image (e.g., cookbook photo, recipe card).
+
+    This command uses Claude's vision API to extract recipe text from images.
+    Requires an Anthropic API key.
+
+    Examples:
+
+        recipe-clipper clip-image recipe.jpg
+
+        recipe-clipper clip-image cookbook-page.png --format json --output recipe.json
+
+        recipe-clipper clip-image recipe-card.jpg --api-key sk-ant-... --format markdown
+    """
+    api_key = _require_api_key(api_key, "image parsing")
+    _validate_file_exists(image_path, "Image")
+
+    _handle_recipe_extraction(
+        extract_func=lambda: parse_recipe_from_image(image_path, api_key, model=model),
+        source_description=f"Extracting recipe from {image_path}",
+        format=format,
+        output=output,
+    )
+
+
+@app.command()
+def clip_document(
+    document_path: Path = typer.Argument(..., help="Path to the recipe document file"),
+    format: OutputFormat = typer.Option(
+        OutputFormat.text,
+        "--format",
+        "-f",
+        help="Output format (text, json, or markdown)",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file path (prints to stdout if not specified)",
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="ANTHROPIC_API_KEY",
+        help="Anthropic API key (required, can also use ANTHROPIC_API_KEY env var)",
+    ),
+    model: str = typer.Option(
+        "claude-sonnet-4-5",
+        "--model",
+        "-m",
+        help="Claude model to use",
+    ),
+):
+    """
+    Extract a recipe from a document (PDF, Word, text, markdown).
+
+    This command uses Claude's document API to extract recipe text from various
+    document formats. Requires an Anthropic API key.
+
+    Supported formats: .pdf, .docx, .txt, .md
+
+    Examples:
+
+        recipe-clipper clip-document recipe.pdf
+
+        recipe-clipper clip-document cookbook.docx --format json --output recipe.json
+
+        recipe-clipper clip-document recipe.txt --api-key sk-ant-... --format markdown
+    """
+    api_key = _require_api_key(api_key, "document parsing")
+    _validate_file_exists(document_path, "Document")
+
+    _handle_recipe_extraction(
+        extract_func=lambda: parse_recipe_from_document(document_path, api_key, model=model),
+        source_description=f"Extracting recipe from {document_path}",
+        format=format,
+        output=output,
+    )
+
+
+if __name__ == "__main__":
+    app()

recipe_clipper/clipper.py

@@ -0,0 +1,50 @@
+"""Main clipper orchestration for extracting recipes from URLs."""
+
+from typing import Optional
+
+from recipe_clipper.models import Recipe
+from recipe_clipper.http import fetch_url
+from recipe_clipper.parsers.recipe_scrapers_parser import parse_with_recipe_scrapers
+from recipe_clipper.exceptions import RecipeParsingError
+
+
+def clip_recipe(
+    url: str,
+    api_key: Optional[str] = None,
+    use_llm_fallback: bool = True,
+    timeout: int = 10,
+) -> Recipe:
+    """
+    Extract a recipe from a URL.
+
+    Tries recipe-scrapers library first. If that fails and LLM fallback is enabled,
+    falls back to Claude-based extraction.
+
+    Args:
+        url: The URL of the recipe page to extract
+        api_key: Anthropic API key for LLM fallback
+        use_llm_fallback: Whether to use LLM fallback if recipe-scrapers fails (default: True)
+        timeout: HTTP request timeout in seconds (default: 10)
+
+    Returns:
+        Parsed Recipe object
+
+    Raises:
+        ValueError: If use_llm_fallback is True but api_key is not provided
+        RecipeNotFoundError: If the recipe cannot be extracted
+        NetworkError: If the HTTP request fails
+        RecipeParsingError: If parsing fails unexpectedly
+        LLMError: If LLM API call fails
+    """
+    if use_llm_fallback and not api_key:
+        raise ValueError("api_key must be provided when use_llm_fallback is True")
+
+    try:
+        response = fetch_url(url, timeout=timeout)
+        return parse_with_recipe_scrapers(response)
+    except RecipeParsingError:
+        if use_llm_fallback:
+            from recipe_clipper.parsers.llm_parser import parse_with_claude
+
+            return parse_with_claude(url, api_key)
+        raise

recipe_clipper/exceptions.py

@@ -0,0 +1,31 @@
+"""Custom exceptions for recipe clipper."""
+
+
+class RecipeClipperError(Exception):
+    """Base exception for all recipe clipper errors."""
+
+    pass
+
+
+class RecipeNotFoundError(RecipeClipperError):
+    """Raised when no recipe can be extracted from the URL."""
+
+    pass
+
+
+class RecipeParsingError(RecipeClipperError):
+    """Raised when recipe parsing fails."""
+
+    pass
+
+
+class NetworkError(RecipeClipperError):
+    """Raised when HTTP request fails."""
+
+    pass
+
+
+class LLMError(RecipeClipperError):
+    """Raised when LLM API call fails."""
+
+    pass

recipe_clipper/formatters.py

@@ -0,0 +1,125 @@
+"""Recipe output formatters."""
+
+from recipe_clipper.models import Recipe, RecipeMetadata, Ingredient
+
+
+# Helper functions for formatting
+
+
+def _format_ingredient(ingredient: Ingredient) -> str:
+    """Get ingredient display text."""
+    return ingredient.display_text or ingredient.name
+
+
+def _format_metadata_lines(metadata: RecipeMetadata, style: str = "text") -> list[str]:
+    """Format all metadata fields as lines.
+
+    Args:
+        metadata: Recipe metadata to format
+        style: Format style ("text" or "markdown")
+
+    Returns:
+        List of formatted metadata lines
+    """
+    if not metadata:
+        return []
+
+    lines = []
+    field_map = {
+        "Author": metadata.author,
+        "Servings": metadata.servings,
+        "Prep Time": f"{metadata.prep_time} minutes" if metadata.prep_time else None,
+        "Cook Time": f"{metadata.cook_time} minutes" if metadata.cook_time else None,
+        "Total Time": f"{metadata.total_time} minutes" if metadata.total_time else None,
+        "Categories": ", ".join(metadata.categories) if metadata.categories else None,
+    }
+
+    for key, value in field_map.items():
+        if value:
+            if style == "markdown":
+                lines.append(f"- **{key}:** {value}")
+            else:
+                lines.append(f"{key}: {value}")
+
+    return lines
+
+
+def format_recipe_text(recipe: Recipe) -> str:
+    """Format recipe as human-readable text."""
+    lines = []
+
+    # Title
+    lines.append(f"\n{'=' * 80}")
+    lines.append(recipe.title.center(80))
+    lines.append("=" * 80)
+
+    # Metadata
+    metadata_lines = _format_metadata_lines(recipe.metadata, style="text")
+    if metadata_lines:
+        lines.append("\nMETADATA")
+        lines.append("-" * 80)
+        lines.extend(metadata_lines)
+
+    # Ingredients
+    lines.append("\nINGREDIENTS")
+    lines.append("-" * 80)
+    for ingredient in recipe.ingredients:
+        lines.append(f"  • {_format_ingredient(ingredient)}")
+
+    # Instructions
+    lines.append("\nINSTRUCTIONS")
+    lines.append("-" * 80)
+    for i, instruction in enumerate(recipe.instructions, 1):
+        lines.append(f"{i}. {instruction}")
+
+    # Source
+    if recipe.source_url:
+        lines.append(f"\nSource: {recipe.source_url}")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def format_recipe_json(recipe: Recipe) -> str:
+    """Format recipe as JSON."""
+    return recipe.model_dump_json(indent=2, exclude_none=True)
+
+
+def format_recipe_markdown(recipe: Recipe) -> str:
+    """Format recipe as Markdown."""
+    lines = []
+
+    # Title (big heading)
+    lines.append(f"# {recipe.title}")
+    lines.append("")
+
+    # Metadata
+    metadata_lines = _format_metadata_lines(recipe.metadata, style="markdown")
+    if metadata_lines:
+        lines.append("## Metadata")
+        lines.append("")
+        lines.extend(metadata_lines)
+        lines.append("")
+
+    # Ingredients
+    lines.append("## Ingredients")
+    lines.append("")
+    for ingredient in recipe.ingredients:
+        lines.append(f"- {_format_ingredient(ingredient)}")
+    lines.append("")
+
+    # Instructions
+    lines.append("## Instructions")
+    lines.append("")
+    for i, instruction in enumerate(recipe.instructions, 1):
+        lines.append(f"{i}. {instruction}")
+    lines.append("")
+
+    # Source
+    if recipe.source_url:
+        lines.append("## Source")
+        lines.append("")
+        lines.append(f"[{recipe.source_url}]({recipe.source_url})")
+        lines.append("")
+
+    return "\n".join(lines)

recipe_clipper/http.py

@@ -0,0 +1,61 @@
+"""HTTP client for fetching recipe pages."""
+
+import httpx
+from typing import Dict, Optional
+
+from recipe_clipper.exceptions import NetworkError
+from recipe_clipper.models import ImmutableBaseModel
+
+DEFAULT_USER_AGENT = "recipe-clipper/0.1.0 (https://github.com/recipe-clipper/recipe-clipper)"
+DEFAULT_TIMEOUT = 10
+
+
+class HttpResponse(ImmutableBaseModel):
+    """HTTP response data."""
+
+    content: str
+    status_code: int
+    url: str
+
+
+def fetch_url(
+    url: str,
+    timeout: int = DEFAULT_TIMEOUT,
+    headers: Optional[Dict[str, str]] = None,
+) -> HttpResponse:
+    """
+    Fetch HTML content from a URL.
+
+    Args:
+        url: The URL to fetch
+        timeout: Request timeout in seconds
+        headers: Optional custom headers
+
+    Returns:
+        HttpResponse with content, status_code, and final URL (after redirects)
+
+    Raises:
+        NetworkError: If the request fails
+    """
+    if headers is None:
+        headers = {}
+
+    # Set default user agent if not provided
+    if "User-Agent" not in headers:
+        headers["User-Agent"] = DEFAULT_USER_AGENT
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(url, headers=headers, follow_redirects=True)
+            response.raise_for_status()
+            return HttpResponse(
+                content=response.text,
+                status_code=response.status_code,
+                url=str(response.url),
+            )
+    except httpx.HTTPStatusError as e:
+        raise NetworkError(f"HTTP error {e.response.status_code} while fetching {url}") from e
+    except httpx.RequestError as e:
+        raise NetworkError(f"Network error while fetching {url}: {e}") from e
+    except Exception as e:
+        raise NetworkError(f"Unexpected error while fetching {url}: {e}") from e

recipe_clipper/models.py

@@ -0,0 +1,44 @@
+"""Data models for recipe clipper."""
+
+from typing import Optional
+from pydantic import BaseModel, Field, HttpUrl, AnyUrl, ConfigDict
+
+
+class ImmutableBaseModel(BaseModel):
+    """Base model with immutability enabled."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class Ingredient(ImmutableBaseModel):
+    """An ingredient in a recipe."""
+
+    name: str = Field(..., description="Ingredient name")
+    amount: Optional[str] = Field(None, description="Quantity (e.g., '2', '1/2')")
+    unit: Optional[str] = Field(None, description="Unit of measurement (e.g., 'cup', 'tsp')")
+    preparation: Optional[str] = Field(
+        None, description="Preparation method (e.g., 'chopped', 'diced', 'minced')"
+    )
+    display_text: Optional[str] = Field(None, description="How the ingredient should be displayed")
+
+
+class RecipeMetadata(ImmutableBaseModel):
+    """Metadata about a recipe."""
+
+    author: Optional[str] = Field(None, description="Recipe author or source")
+    servings: Optional[str] = Field(None, description="Number of servings")
+    prep_time: Optional[int] = Field(None, description="Prep time in minutes")
+    cook_time: Optional[int] = Field(None, description="Cook time in minutes")
+    total_time: Optional[int] = Field(None, description="Total time in minutes")
+    categories: Optional[list[str]] = Field(None, description="Recipe categories")
+
+
+class Recipe(ImmutableBaseModel):
+    """A complete recipe."""
+
+    title: str = Field(..., description="Recipe title")
+    ingredients: list[Ingredient] = Field(default_factory=list, description="List of ingredients")
+    instructions: list[str] = Field(default_factory=list, description="Step-by-step instructions")
+    source_url: Optional[AnyUrl] = Field(None, description="Source URL (http/https/file)")
+    image: Optional[HttpUrl] = Field(None, description="Recipe image URL")
+    metadata: Optional[RecipeMetadata] = Field(None, description="Recipe metadata")

recipe_clipper/parsers/__init__.py

@@ -0,0 +1 @@
+"""Recipe parsers."""

recipe_clipper/parsers/llm_parser.py

@@ -0,0 +1,356 @@
+"""LLM-based recipe parser using Claude API."""
+
+import base64
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional, Union
+
+from pydantic import AnyUrl
+
+from recipe_clipper.models import Recipe
+from recipe_clipper.exceptions import LLMError
+
+if TYPE_CHECKING:
+    from anthropic import Anthropic
+
+
+SUPPORTED_MODELS = {
+    "claude-sonnet-4-5",
+    "claude-sonnet-4",
+    "claude-opus-4",
+    "claude-3-5-sonnet-20241022",
+    "claude-3-5-sonnet-20240620",
+}
+
+IMAGE_MEDIA_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+
+DOCUMENT_MEDIA_TYPES = {
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+}
+
+
+# Helper functions for common LLM parsing operations
+
+
+def _validate_model(model: str) -> None:
+    """Validate that the model is supported."""
+    if model not in SUPPORTED_MODELS:
+        raise ValueError(
+            f"Unsupported model: {model}. Supported models: {', '.join(sorted(SUPPORTED_MODELS))}"
+        )
+
+
+def _validate_file_path(file_path: Path, file_description: str) -> None:
+    """Validate that a file exists."""
+    if not file_path.exists():
+        raise FileNotFoundError(f"{file_description} not found: {file_path}")
+
+
+def _read_and_encode_file(file_path: Path) -> str:
+    """Read a file and return base64-encoded data."""
+    with open(file_path, "rb") as f:
+        return base64.standard_b64encode(f.read()).decode("utf-8")
+
+
+def _get_recipe_extraction_prompt(source_type: str = "document") -> str:
+    """Get the standard recipe extraction prompt.
+
+    Args:
+        source_type: Type of source ("image", "document", or "webpage")
+
+    Returns:
+        Formatted prompt string
+    """
+    if source_type == "image":
+        visibility_note = (
+            "If any information is not visible in the image, omit it from the output.\n"
+            "Extract the text exactly as it appears, preserving the original wording and formatting."
+        )
+    else:
+        visibility_note = (
+            "If any information is not present in the document, omit it from the output.\n"
+            "Extract the text exactly as it appears, preserving the original wording."
+        )
+
+    return f"""Extract the recipe from this {source_type} into a structured output with the following elements:
+    - title
+    - ingredients
+        - amount
+        - units
+        - preparation method, if available
+        - original wording as the display_text
+    - instructions
+    - metadata
+        - author (if visible)
+        - number of servings (if visible)
+        - prep time (if visible)
+        - cook time (if visible)
+        - total time (if visible)
+        - categories (if visible)
+
+    {visibility_note}
+    """
+
+
+def _call_claude_api(
+    client: "Anthropic",
+    model: str,
+    messages: list,
+    betas: list[str],
+    source_description: str,
+    tools: Optional[list] = None,
+) -> Recipe:
+    """Make a Claude API call with error handling.
+
+    Args:
+        client: Anthropic client instance
+        model: Model name to use
+        messages: Messages to send
+        betas: Beta features to enable
+        source_description: Description of source for error messages
+        tools: Optional tools to provide
+
+    Returns:
+        Parsed Recipe object
+
+    Raises:
+        LLMError: If API call fails
+    """
+    try:
+        kwargs = {
+            "model": model,
+            "max_tokens": 4096,
+            "messages": messages,
+            "output_format": Recipe,
+            "betas": betas,
+        }
+        if tools:
+            kwargs["tools"] = tools
+
+        message = client.beta.messages.parse(**kwargs)
+        return message.parsed_output
+    except Exception as error:
+        raise LLMError(f"Claude API call failed for {source_description}: {error}") from error
+
+
+def _set_recipe_source_url(recipe: Recipe, source_path: Union[str, Path]) -> Recipe:
+    """Set the source URL for a recipe.
+
+    Args:
+        recipe: Recipe object to update
+        source_path: Source path (URL string or file path)
+
+    Returns:
+        Updated Recipe object with source_url set
+    """
+    if isinstance(source_path, str) and source_path.startswith("http"):
+        source_url = AnyUrl(source_path)
+    else:
+        source_url = AnyUrl(Path(source_path).absolute().as_uri())
+    return recipe.model_copy(update={"source_url": source_url})
+
+
+def _validate_file_format(
+    file_path: Path, media_type_map: dict[str, str], format_category: str
+) -> str:
+    """Validate file format and return media type.
+
+    Args:
+        file_path: Path to the file
+        media_type_map: Mapping of file extensions to media types
+        format_category: Category description for error message
+
+    Returns:
+        Media type string
+
+    Raises:
+        ValueError: If file format is not supported
+    """
+    extension = file_path.suffix.lower()
+
+    if extension not in media_type_map:
+        raise ValueError(
+            f"Unsupported {format_category} format: {extension}. "
+            f"Supported formats: {', '.join(media_type_map.keys())}"
+        )
+
+    return media_type_map[extension]
+
+
+def parse_with_claude(url: str, api_key: str, model: str = "claude-sonnet-4-5") -> Recipe:
+    """Parse a recipe using Claude's structured output API.
+
+    Args:
+        url: URL of the recipe page
+        api_key: Anthropic API key
+        model: Claude model to use (default: claude-sonnet-4-5)
+
+    Returns:
+        Parsed Recipe object
+
+    Raises:
+        ValueError: If an unsupported model is specified
+        LLMError: If Claude API call fails
+    """
+    from anthropic import Anthropic
+
+    _validate_model(model)
+
+    client = Anthropic(api_key=api_key)
+
+    prompt = f"{_get_recipe_extraction_prompt('webpage')}\n\nURL:\n\n{url}"
+    messages = [{"role": "user", "content": prompt}]
+
+    tools = [
+        {
+            "type": "web_fetch_20250910",
+            "name": "web_fetch",
+            "max_uses": 1,
+        }
+    ]
+
+    recipe = _call_claude_api(
+        client=client,
+        model=model,
+        messages=messages,
+        betas=["structured-outputs-2025-11-13", "web-fetch-2025-09-10"],
+        source_description=url,
+        tools=tools,
+    )
+
+    return _set_recipe_source_url(recipe, url)
+
+
+def parse_recipe_from_image(
+    image_path: Union[str, Path], api_key: str, model: str = "claude-sonnet-4-5"
+) -> Recipe:
+    """Parse a recipe from an image using Claude's vision API.
+
+    Useful for extracting recipes from cookbook photos, handwritten recipe cards,
+    or screenshots of recipes.
+
+    Args:
+        image_path: Path to the image file (jpg, png, gif, webp)
+        api_key: Anthropic API key
+        model: Claude model to use (default: claude-sonnet-4-5)
+
+    Returns:
+        Parsed Recipe object
+
+    Raises:
+        ValueError: If an unsupported model is specified or image format is invalid
+        FileNotFoundError: If the image file doesn't exist
+        LLMError: If Claude API call fails
+    """
+    from anthropic import Anthropic
+
+    _validate_model(model)
+
+    image_file = Path(image_path)
+    _validate_file_path(image_file, "Image file")
+
+    media_type = _validate_file_format(image_file, IMAGE_MEDIA_TYPES, "image")
+    image_data = _read_and_encode_file(image_file)
+
+    client = Anthropic(api_key=api_key)
+
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": media_type,
+                        "data": image_data,
+                    },
+                },
+                {"type": "text", "text": _get_recipe_extraction_prompt("image")},
+            ],
+        }
+    ]
+
+    recipe = _call_claude_api(
+        client=client,
+        model=model,
+        messages=messages,
+        betas=["structured-outputs-2025-11-13"],
+        source_description=f"image {image_path}",
+    )
+
+    return _set_recipe_source_url(recipe, image_file)
+
+
+def parse_recipe_from_document(
+    document_path: Union[str, Path], api_key: str, model: str = "claude-sonnet-4-5"
+) -> Recipe:
+    """Parse a recipe from a document using Claude's file API.
+
+    Supports PDF, Word documents (.docx), and text formats (.txt, .md).
+    Uses Claude's native document handling capabilities.
+
+    Args:
+        document_path: Path to the document file (pdf, docx, txt, md)
+        api_key: Anthropic API key
+        model: Claude model to use (default: claude-sonnet-4-5)
+
+    Returns:
+        Parsed Recipe object
+
+    Raises:
+        ValueError: If an unsupported model or document format is specified
+        FileNotFoundError: If the document file doesn't exist
+        LLMError: If Claude API call fails
+    """
+    from anthropic import Anthropic
+
+    _validate_model(model)
+
+    doc_file = Path(document_path)
+    _validate_file_path(doc_file, "Document file")
+
+    media_type = _validate_file_format(doc_file, DOCUMENT_MEDIA_TYPES, "document")
+    document_data = _read_and_encode_file(doc_file)
+
+    client = Anthropic(api_key=api_key)
+
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "document",
+                    "source": {
+                        "type": "base64",
+                        "media_type": media_type,
+                        "data": document_data,
+                    },
+                },
+                {"type": "text", "text": _get_recipe_extraction_prompt("document")},
+            ],
+        }
+    ]
+
+    # Add PDF beta if needed
+    betas = ["structured-outputs-2025-11-13"]
+    if doc_file.suffix.lower() == ".pdf":
+        betas.append("pdfs-2024-09-25")
+
+    recipe = _call_claude_api(
+        client=client,
+        model=model,
+        messages=messages,
+        betas=betas,
+        source_description=f"document {document_path}",
+    )
+
+    return _set_recipe_source_url(recipe, doc_file)

recipe_clipper/parsers/recipe_scrapers_parser.py

@@ -0,0 +1,50 @@
+"""Parser using the recipe-scrapers library."""
+
+from recipe_scrapers import scrape_html
+
+from recipe_clipper.models import Recipe, Ingredient, RecipeMetadata
+from recipe_clipper.http import HttpResponse
+from recipe_clipper.exceptions import RecipeParsingError
+
+
+def parse_with_recipe_scrapers(response: HttpResponse) -> Recipe:
+    """
+    Parse a recipe using the recipe-scrapers library.
+
+    Attempts to parse recipes from both supported and unsupported sites using
+    generic schema.org markup when site-specific scrapers are unavailable.
+
+    Args:
+        response: HttpResponse containing URL and HTML content
+
+    Returns:
+        Parsed Recipe object
+
+    Raises:
+        RecipeNotFoundError: If no recipe could be found in the page
+        RecipeParsingError: If parsing fails
+    """
+    try:
+        scraper = scrape_html(response.content, response.url, supported_only=False)
+    except Exception as error:
+        raise RecipeParsingError(f"Failed to create scraper for {response.url}: {error}") from error
+
+    ingredients = [Ingredient(name=ingredient) for ingredient in scraper.ingredients()]
+
+    metadata = RecipeMetadata(
+        author=scraper.author(),
+        servings=scraper.yields(),
+        prep_time=scraper.prep_time(),
+        cook_time=scraper.cook_time(),
+        total_time=scraper.total_time(),
+        categories=[scraper.category()] if scraper.category() else None,
+    )
+
+    return Recipe(
+        title=scraper.title(),
+        ingredients=ingredients,
+        instructions=scraper.instructions_list(),
+        source_url=response.url,
+        image=scraper.image(),
+        metadata=metadata,
+    )

recipe_clipper-0.1.0a0.dist-info/METADATA

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: recipe-clipper
+Version: 0.1.0a0
+Summary: Extract recipes from websites, images, and documents.
+Project-URL: Homepage, https://github.com/zduey/recipe-clipper
+Project-URL: Repository, https://github.com/zduey/recipe-clipper
+Project-URL: Issues, https://github.com/zduey/recipe-clipper/issues
+Author: Recipe Clipper Contributors
+License: MIT
+License-File: LICENSE
+Keywords: cooking,food,llm,ocr,parser,pdf,recipe,scraping,vision
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: recipe-scrapers>=15.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40.0; extra == 'llm'
+Requires-Dist: cohere>=5.0.0; extra == 'llm'
+Requires-Dist: google-generativeai>=0.3.0; extra == 'llm'
+Requires-Dist: openai>=1.0.0; extra == 'llm'
+Provides-Extra: llm-anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'llm-anthropic'
+Provides-Extra: llm-cohere
+Requires-Dist: cohere>=5.0.0; extra == 'llm-cohere'
+Provides-Extra: llm-google
+Requires-Dist: google-generativeai>=0.3.0; extra == 'llm-google'
+Provides-Extra: llm-openai
+Requires-Dist: openai>=1.0.0; extra == 'llm-openai'
+Description-Content-Type: text/markdown
+
+# Recipe Clipper
+
+[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
+[![codecov](https://codecov.io/gh/zduey/recipe-clipper/branch/master/graph/badge.svg)](https://codecov.io/gh/zduey/recipe-clipper)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/recipe-clipper.svg)](https://pypi.org/project/recipe-clipper/)
+
+Extract recipes from websites, images, and documents with ease. Recipe Clipper supports multiple input sources and uses both web scraping and Claude's vision capabilities to extract structured recipe data.
+
+## Features
+
+- 🌐 **Web Scraping**: Extract recipes from 100+ websites using [recipe-scrapers](https://github.com/hhursev/recipe-scrapers)
+- 📸 **Image OCR**: Extract recipes from cookbook photos, recipe cards, or screenshots using Claude's vision API
+- 📄 **Document Parsing**: Extract recipes from PDFs, Word documents, text files, and markdown
+- 🤖 **LLM Fallback**: Automatically falls back to Claude for unsupported websites
+- 🎨 **Multiple Output Formats**: Export as text, JSON, or markdown
+- 🔧 **CLI & Library**: Use as a command-line tool or import as a Python library
+- ⚡ **Type-Safe**: Full type hints with Pydantic models
+- 🔒 **Immutable**: Data models are frozen for safety
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install recipe-clipper
+```
+
+This includes:
+- Web scraping for 100+ recipe websites
+- CLI tool
+- All core functionality
+
+### With Claude Support
+
+For image/document parsing and LLM fallback:
+
+```bash
+pip install recipe-clipper[llm]
+```
+
+## Quick Start
+
+### CLI Usage
+
+#### Extract from a website
+
+```bash
+# Basic usage
+recipe-clipper clip-webpage https://www.allrecipes.com/recipe/10813/best-chocolate-chip-cookies/
+
+# Save as JSON
+recipe-clipper clip-webpage https://example.com/recipe --format json --output recipe.json
+
+# Save as markdown
+recipe-clipper clip-webpage https://example.com/recipe --format markdown --output recipe.md
+```
+
+#### Extract from an image
+
+```bash
+# Requires ANTHROPIC_API_KEY environment variable
+export ANTHROPIC_API_KEY=your-api-key
+
+recipe-clipper clip-image cookbook-photo.jpg
+
+# Save as JSON
+recipe-clipper clip-image recipe-card.png --format json --output recipe.json
+```
+
+#### Extract from a document
+
+```bash
+# Supports PDF, DOCX, TXT, MD
+recipe-clipper clip-document recipe.pdf
+
+# With custom model
+recipe-clipper clip-document cookbook.docx --model claude-opus-4 --format markdown
+```
+
+### Library Usage
+
+#### Extract from a website
+
+```python
+from recipe_clipper import clip_recipe
+
+# Without LLM fallback (uses recipe-scrapers only)
+recipe = clip_recipe(
+    url="https://www.allrecipes.com/recipe/10813/best-chocolate-chip-cookies/",
+    api_key=None,
+    use_llm_fallback=False
+)
+
+print(recipe.title)
+for ingredient in recipe.ingredients:
+    print(f"- {ingredient.name}")
+```
+
+#### With LLM fallback
+
+```python
+import os
+from recipe_clipper import clip_recipe
+
+api_key = os.getenv("ANTHROPIC_API_KEY")
+
+# Automatically falls back to Claude if recipe-scrapers doesn't support the site
+recipe = clip_recipe(
+    url="https://unsupported-site.com/recipe",
+    api_key=api_key,
+    use_llm_fallback=True
+)
+```
+
+#### Extract from an image
+
+```python
+import os
+from recipe_clipper.parsers.llm_parser import parse_recipe_from_image
+
+api_key = os.getenv("ANTHROPIC_API_KEY")
+
+recipe = parse_recipe_from_image(
+    image_path="cookbook-photo.jpg",
+    api_key=api_key,
+    model="claude-sonnet-4-5"
+)
+
+print(recipe.title)
+print(f"Servings: {recipe.metadata.servings}")
+```
+
+#### Extract from a document
+
+```python
+import os
+from recipe_clipper.parsers.llm_parser import parse_recipe_from_document
+
+api_key = os.getenv("ANTHROPIC_API_KEY")
+
+# Supports .pdf, .docx, .txt, .md
+recipe = parse_recipe_from_document(
+    document_path="recipe.pdf",
+    api_key=api_key
+)
+```
+
+#### Format output
+
+```python
+from recipe_clipper import clip_recipe
+from recipe_clipper.formatters import (
+    format_recipe_text,
+    format_recipe_json,
+    format_recipe_markdown
+)
+
+recipe = clip_recipe("https://example.com/recipe", use_llm_fallback=False)
+
+# Plain text
+print(format_recipe_text(recipe))
+
+# JSON
+json_str = format_recipe_json(recipe)
+
+# Markdown
+markdown_str = format_recipe_markdown(recipe)
+```
+
+## Configuration
+
+### API Keys
+
+For Claude features (image/document parsing, website fallback), set your API key:
+
+```bash
+export ANTHROPIC_API_KEY=your-api-key-here
+```
+
+Or create a `.env` file:
+
+```env
+ANTHROPIC_API_KEY=your-api-key-here
+```
+
+### Supported Models
+
+- `claude-sonnet-4-5` (default, recommended)
+- `claude-sonnet-4`
+- `claude-opus-4`
+- `claude-3-5-sonnet-20241022`
+- `claude-3-5-sonnet-20240620`
+
+## Recipe Data Model
+
+Extracted recipes use a structured Pydantic model:
+
+```python
+class Recipe:
+    title: str
+    ingredients: list[Ingredient]
+    instructions: list[str]
+    source_url: Optional[AnyUrl]
+    image: Optional[HttpUrl]
+    metadata: Optional[RecipeMetadata]
+
+class Ingredient:
+    name: str
+    amount: Optional[str]
+    unit: Optional[str]
+    preparation: Optional[str]
+    display_text: Optional[str]
+
+class RecipeMetadata:
+    author: Optional[str]
+    servings: Optional[str]
+    prep_time: Optional[int]  # minutes
+    cook_time: Optional[int]  # minutes
+    total_time: Optional[int]  # minutes
+    categories: Optional[list[str]]
+```
+
+## Supported Input Sources
+
+### 1. Websites (100+ sites)
+
+Uses [recipe-scrapers](https://github.com/hhursev/recipe-scrapers) which supports:
+- AllRecipes
+- Food Network
+- Serious Eats
+- NYT Cooking
+- And 100+ more sites
+
+For unsupported sites, enable LLM fallback.
+
+### 2. Images
+
+Extracts recipes from:
+- Cookbook photos
+- Handwritten recipe cards
+- Screenshots
+- Scanned documents
+
+Supported formats: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
+
+### 3. Documents
+
+Extracts recipes from:
+- PDFs (recipe PDFs, cookbook PDFs)
+- Word documents (`.docx`)
+- Text files (`.txt`)
+- Markdown files (`.md`)
+
+## Development
+
+### Run tests
+
+```bash
+# Unit tests only
+pytest
+
+# Include integration tests (requires ANTHROPIC_API_KEY)
+pytest -m integration
+```
+
+### Run linting
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Credits
+
+- Built with [recipe-scrapers](https://github.com/hhursev/recipe-scrapers)
+- LLM parsing powered by [Anthropic Claude](https://www.anthropic.com/)

recipe_clipper-0.1.0a0.dist-info/RECORD

@@ -0,0 +1,15 @@
+recipe_clipper/__init__.py,sha256=gXkDlSOvb2GvwDjUpQEC1w8jmxpahampu1GCtP39gAY,167
+recipe_clipper/cli.py,sha256=WgwW7CNEU1-h9NerH8i0ORXKXNPFQoPxN72F4u3Vd88,7842
+recipe_clipper/clipper.py,sha256=hvFqXmy0Fb-PcuWx0p1pHmRiyrYEspniW76JFP_x2OY,1690
+recipe_clipper/exceptions.py,sha256=gUPxVA0SRLOgH65EEcYU3ZfL61HpwF3xGzbIzdkGPlU,557
+recipe_clipper/formatters.py,sha256=BzJS0r4PLgczv9NgRgOESIlvJyzpJzm3CPt18gMr_GQ,3488
+recipe_clipper/http.py,sha256=p27Y0RgQSJhdtujA5Jk-VrSloJSQ5M4synQftk-ZjwM,1790
+recipe_clipper/models.py,sha256=0loKlbgNHfJ-rHiu8FYwOEcS3yxHUr-UapAMegf2eNs,1935
+recipe_clipper/parsers/__init__.py,sha256=0Cj9Udq6SJKyYHUfEYXlQCFc2hlfpfw8EonhRUIb2Zc,22
+recipe_clipper/parsers/llm_parser.py,sha256=CEOZxYldyGv6aO0J1FzJVI6b9Jo0vTVSVEcwx8FSNxg,10087
+recipe_clipper/parsers/recipe_scrapers_parser.py,sha256=lnmogMzXCBOnG5XrDxB2m9pkWTDUHY1nUHlWCagA0ac,1640
+recipe_clipper-0.1.0a0.dist-info/METADATA,sha256=P5LRPu_wsVbKm00LyW7r2SXXfupFlRLrgPH-oDs4FaQ,8805
+recipe_clipper-0.1.0a0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+recipe_clipper-0.1.0a0.dist-info/entry_points.txt,sha256=KsfF-9OWxxR7bhlrWBBOs-MM-yyNZV3bQ7XPHw6DOTM,58
+recipe_clipper-0.1.0a0.dist-info/licenses/LICENSE,sha256=ftq44Im9g7t_9sVoIBKknL-DdtaTskhAedC2zOQOp7o,1084
+recipe_clipper-0.1.0a0.dist-info/RECORD,,

recipe_clipper-0.1.0a0.dist-info/WHEEL

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

recipe_clipper-0.1.0a0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+recipe-clipper = recipe_clipper.cli:app

recipe_clipper-0.1.0a0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Recipe Clipper Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.