aws-simple 0.1.0b0__py3-none-any.whl

aws_simple/__init__.py

@@ -0,0 +1,54 @@
+"""
+aws-simple: A clean, simple wrapper around AWS services.
+
+Simplifies usage of AWS S3, Textract, and Bedrock through a clean API.
+Configuration is done entirely via environment variables.
+
+Example usage:
+    from aws_simple import s3, textract, bedrock
+
+    # S3 operations
+    s3.upload_file("doc.pdf", "docs/doc.pdf")
+    content = s3.read_object("docs/doc.pdf")
+
+    # Textract extraction
+    doc = textract.extract_text_from_s3("docs/doc.pdf")
+    print(doc.full_text)
+    print(doc.to_dict())  # Serialize to JSON
+
+    # Bedrock LLM
+    summary = bedrock.invoke("Summarize this document")
+    data = bedrock.invoke_json("Extract key points as JSON")
+"""
+
+from . import bedrock, s3, textract
+from .exceptions import (
+    AWSSimpleError,
+    BedrockError,
+    ClientInitializationError,
+    ConfigurationError,
+    S3Error,
+    TextractError,
+)
+from .models import TextractDocument, TextractLine, TextractPage, TextractTable
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Modules
+    "s3",
+    "textract",
+    "bedrock",
+    # Exceptions
+    "AWSSimpleError",
+    "BedrockError",
+    "ClientInitializationError",
+    "ConfigurationError",
+    "S3Error",
+    "TextractError",
+    # Models
+    "TextractDocument",
+    "TextractLine",
+    "TextractPage",
+    "TextractTable",
+]

aws_simple/_clients.py

@@ -0,0 +1,69 @@
+"""Internal AWS clients factory (not exposed in public API)."""
+
+from typing import Any
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError, NoCredentialsError
+
+from .config import config
+from .exceptions import ClientInitializationError
+
+
+class AWSClients:
+    """Factory for creating and caching AWS service clients."""
+
+    _s3_client: Any | None = None
+    _textract_client: Any | None = None
+    _bedrock_runtime_client: Any | None = None
+
+    @classmethod
+    def _get_session_kwargs(cls) -> dict[str, str]:
+        """Get boto3 session configuration."""
+        kwargs: dict[str, str] = {"region_name": config.aws_region}
+        if config.aws_profile:
+            kwargs["profile_name"] = config.aws_profile
+        return kwargs
+
+    @classmethod
+    def get_s3_client(cls) -> Any:
+        """Get or create S3 client."""
+        if cls._s3_client is None:
+            try:
+                session = boto3.Session(**cls._get_session_kwargs())
+                cls._s3_client = session.client("s3")
+            except (BotoCoreError, ClientError, NoCredentialsError) as e:
+                raise ClientInitializationError(f"Failed to initialize S3 client: {e}") from e
+        return cls._s3_client
+
+    @classmethod
+    def get_textract_client(cls) -> Any:
+        """Get or create Textract client."""
+        if cls._textract_client is None:
+            try:
+                kwargs = cls._get_session_kwargs()
+                kwargs["region_name"] = config.textract_region
+                session = boto3.Session(**kwargs)
+                cls._textract_client = session.client("textract")
+            except (BotoCoreError, ClientError, NoCredentialsError) as e:
+                raise ClientInitializationError(f"Failed to initialize Textract client: {e}") from e
+        return cls._textract_client
+
+    @classmethod
+    def get_bedrock_runtime_client(cls) -> Any:
+        """Get or create Bedrock Runtime client."""
+        if cls._bedrock_runtime_client is None:
+            try:
+                kwargs = cls._get_session_kwargs()
+                kwargs["region_name"] = config.bedrock_region
+                session = boto3.Session(**kwargs)
+                cls._bedrock_runtime_client = session.client("bedrock-runtime")
+            except (BotoCoreError, ClientError, NoCredentialsError) as e:
+                raise ClientInitializationError(f"Failed to initialize Bedrock client: {e}") from e
+        return cls._bedrock_runtime_client
+
+    @classmethod
+    def reset_clients(cls) -> None:
+        """Reset all cached clients (useful for testing)."""
+        cls._s3_client = None
+        cls._textract_client = None
+        cls._bedrock_runtime_client = None

aws_simple/_parsers/__init__.py

@@ -0,0 +1,5 @@
+"""Internal parsers for AWS service responses."""
+
+from .textract_parser import TextractParser
+
+__all__ = ["TextractParser"]

aws_simple/_parsers/textract_parser.py

@@ -0,0 +1,192 @@
+"""Parser to transform AWS Textract Blocks into clean JSON structure."""
+
+from typing import Any
+
+from ..models.textract import (
+    TextractDocument,
+    TextractLine,
+    TextractPage,
+    TextractTable,
+)
+
+
+class TextractParser:
+    """Transforms AWS Textract response into clean, structured format."""
+
+    @staticmethod
+    def parse_response(response: dict[str, Any]) -> TextractDocument:
+        """
+        Parse Textract API response into TextractDocument.
+
+        Args:
+            response: Raw AWS Textract response with Blocks
+
+        Returns:
+            TextractDocument with structured data
+        """
+        blocks = response.get("Blocks", [])
+
+        # Build block lookup
+        block_map = {block["Id"]: block for block in blocks}
+
+        # Group blocks by page
+        pages_data: dict[int, dict[str, Any]] = {}
+
+        for block in blocks:
+            block_type = block.get("BlockType")
+            page_num = block.get("Page", 1)
+
+            if page_num not in pages_data:
+                pages_data[page_num] = {
+                    "lines": [],
+                    "tables": [],
+                    "page_geometry": block.get("Geometry", {}),
+                }
+
+            if block_type == "LINE":
+                pages_data[page_num]["lines"].append(block)
+            elif block_type == "TABLE":
+                pages_data[page_num]["tables"].append(block)
+
+        # Build pages
+        pages: list[TextractPage] = []
+        all_text_parts: list[str] = []
+
+        for page_num in sorted(pages_data.keys()):
+            page_info = pages_data[page_num]
+
+            # Parse lines
+            lines = TextractParser._parse_lines(page_info["lines"])
+
+            # Parse tables
+            tables = TextractParser._parse_tables(page_info["tables"], block_map)
+
+            # Get page dimensions
+            geometry = page_info["page_geometry"]
+            bbox = geometry.get("BoundingBox", {})
+            width = bbox.get("Width", 1.0)
+            height = bbox.get("Height", 1.0)
+
+            # Concatenate text for this page
+            page_text = "\n".join(line.text for line in lines)
+            all_text_parts.append(page_text)
+
+            page = TextractPage(
+                page_number=page_num,
+                width=width,
+                height=height,
+                lines=lines,
+                tables=tables,
+                raw_text=page_text,
+            )
+            pages.append(page)
+
+        full_text = "\n\n".join(all_text_parts)
+
+        return TextractDocument(
+            pages=pages,
+            full_text=full_text,
+            metadata={
+                "document_metadata": response.get("DocumentMetadata", {}),
+                "total_pages": len(pages),
+            },
+        )
+
+    @staticmethod
+    def _parse_lines(line_blocks: list[dict[str, Any]]) -> list[TextractLine]:
+        """Parse LINE blocks into TextractLine objects."""
+        lines = []
+        for block in line_blocks:
+            text = block.get("Text", "")
+            confidence = block.get("Confidence", 0.0)
+            geometry = block.get("Geometry", {})
+            bbox = geometry.get("BoundingBox", {})
+
+            bounding_box = {
+                "top": bbox.get("Top", 0.0),
+                "left": bbox.get("Left", 0.0),
+                "width": bbox.get("Width", 0.0),
+                "height": bbox.get("Height", 0.0),
+            }
+
+            lines.append(
+                TextractLine(
+                    text=text,
+                    confidence=confidence,
+                    bounding_box=bounding_box,
+                )
+            )
+        return lines
+
+    @staticmethod
+    def _parse_tables(
+        table_blocks: list[dict[str, Any]], block_map: dict[str, dict[str, Any]]
+    ) -> list[TextractTable]:
+        """Parse TABLE blocks into TextractTable objects."""
+        tables = []
+
+        for table_block in table_blocks:
+            # Get table dimensions
+            relationships = table_block.get("Relationships", [])
+            cell_ids = []
+            for rel in relationships:
+                if rel.get("Type") == "CHILD":
+                    cell_ids = rel.get("Ids", [])
+                    break
+
+            # Build cell matrix
+            cells_data: dict[tuple[int, int], str] = {}
+            max_row = 0
+            max_col = 0
+
+            for cell_id in cell_ids:
+                cell_block = block_map.get(cell_id)
+                if not cell_block or cell_block.get("BlockType") != "CELL":
+                    continue
+
+                row_index = cell_block.get("RowIndex", 1) - 1
+                col_index = cell_block.get("ColumnIndex", 1) - 1
+                max_row = max(max_row, row_index)
+                max_col = max(max_col, col_index)
+
+                # Get cell text from WORD children
+                cell_text = TextractParser._get_cell_text(cell_block, block_map)
+                cells_data[(row_index, col_index)] = cell_text
+
+            # Build matrix
+            rows = max_row + 1
+            cols = max_col + 1
+            cell_matrix = [["" for _ in range(cols)] for _ in range(rows)]
+
+            for (row_idx, col_idx), text in cells_data.items():
+                cell_matrix[row_idx][col_idx] = text
+
+            tables.append(
+                TextractTable(
+                    rows=rows,
+                    columns=cols,
+                    cells=cell_matrix,
+                    confidence=table_block.get("Confidence", 0.0),
+                )
+            )
+
+        return tables
+
+    @staticmethod
+    def _get_cell_text(cell_block: dict[str, Any], block_map: dict[str, dict[str, Any]]) -> str:
+        """Extract text from a CELL block by following relationships."""
+        relationships = cell_block.get("Relationships", [])
+        word_ids = []
+
+        for rel in relationships:
+            if rel.get("Type") == "CHILD":
+                word_ids = rel.get("Ids", [])
+                break
+
+        words = []
+        for word_id in word_ids:
+            word_block = block_map.get(word_id)
+            if word_block and word_block.get("BlockType") == "WORD":
+                words.append(word_block.get("Text", ""))
+
+        return " ".join(words)

aws_simple/bedrock.py

@@ -0,0 +1,169 @@
+"""Bedrock operations module."""
+
+import json
+from typing import Any
+
+from botocore.exceptions import ClientError
+
+from ._clients import AWSClients
+from .config import config
+from .exceptions import BedrockError
+
+
+def invoke(
+    prompt: str,
+    model_id: str | None = None,
+    max_tokens: int = 4096,
+    temperature: float = 1.0,
+    system_prompt: str | None = None,
+) -> str:
+    """
+    Invoke Bedrock LLM and return text response.
+
+    Args:
+        prompt: User prompt/question
+        model_id: Model ID (uses AWS_BEDROCK_MODEL_ID env var if not specified)
+        max_tokens: Maximum tokens to generate
+        temperature: Sampling temperature (0.0 to 1.0)
+        system_prompt: Optional system prompt
+
+    Returns:
+        Generated text response
+
+    Raises:
+        BedrockError: If invocation fails
+    """
+    model_id = model_id or config.bedrock_model_id
+
+    try:
+        client = AWSClients.get_bedrock_runtime_client()
+
+        # Build request based on model family
+        if "anthropic.claude" in model_id:
+            body = _build_anthropic_request(
+                prompt=prompt,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                system_prompt=system_prompt,
+            )
+        else:
+            raise BedrockError(
+                f"Unsupported model family: {model_id}. Currently only Claude models are supported."
+            )
+
+        response = client.invoke_model(
+            modelId=model_id,
+            body=json.dumps(body),
+            contentType="application/json",
+            accept="application/json",
+        )
+
+        response_body = json.loads(response["body"].read())
+
+        # Extract text based on model family
+        if "anthropic.claude" in model_id:
+            return _extract_anthropic_text(response_body)
+        else:
+            raise BedrockError(f"Cannot extract response from model: {model_id}")
+
+    except ClientError as e:
+        raise BedrockError(f"Failed to invoke Bedrock model {model_id}: {e}") from e
+    except Exception as e:
+        raise BedrockError(f"Unexpected error invoking Bedrock: {e}") from e
+
+
+def invoke_json(
+    prompt: str,
+    model_id: str | None = None,
+    max_tokens: int = 4096,
+    temperature: float = 1.0,
+    system_prompt: str | None = None,
+) -> dict[str, Any]:
+    """
+    Invoke Bedrock LLM and return parsed JSON response.
+
+    The prompt should explicitly ask for JSON output.
+
+    Args:
+        prompt: User prompt (should request JSON output)
+        model_id: Model ID (uses AWS_BEDROCK_MODEL_ID env var if not specified)
+        max_tokens: Maximum tokens to generate
+        temperature: Sampling temperature (0.0 to 1.0)
+        system_prompt: Optional system prompt
+
+    Returns:
+        Parsed JSON response as dictionary
+
+    Raises:
+        BedrockError: If invocation fails or response is not valid JSON
+    """
+    # Add JSON instruction if not present
+    json_prompt = prompt
+    if "json" not in prompt.lower():
+        json_prompt = f"{prompt}\n\nPlease respond with valid JSON only."
+
+    text_response = invoke(
+        prompt=json_prompt,
+        model_id=model_id,
+        max_tokens=max_tokens,
+        temperature=temperature,
+        system_prompt=system_prompt,
+    )
+
+    try:
+        # Try to parse the response as JSON
+        # Handle cases where model wraps JSON in markdown code blocks
+        cleaned = text_response.strip()
+        if cleaned.startswith("```json"):
+            cleaned = cleaned[7:]
+        if cleaned.startswith("```"):
+            cleaned = cleaned[3:]
+        if cleaned.endswith("```"):
+            cleaned = cleaned[:-3]
+        cleaned = cleaned.strip()
+
+        return json.loads(cleaned)
+    except json.JSONDecodeError as e:
+        raise BedrockError(
+            f"Model response is not valid JSON. Response: {text_response[:200]}..."
+        ) from e
+
+
+def _build_anthropic_request(
+    prompt: str,
+    max_tokens: int,
+    temperature: float,
+    system_prompt: str | None = None,
+) -> dict[str, Any]:
+    """Build request body for Anthropic Claude models."""
+    body: dict[str, Any] = {
+        "anthropic_version": "bedrock-2023-05-31",
+        "max_tokens": max_tokens,
+        "temperature": temperature,
+        "messages": [
+            {
+                "role": "user",
+                "content": prompt,
+            }
+        ],
+    }
+
+    if system_prompt:
+        body["system"] = system_prompt
+
+    return body
+
+
+def _extract_anthropic_text(response_body: dict[str, Any]) -> str:
+    """Extract text from Anthropic Claude response."""
+    content = response_body.get("content", [])
+    if not content:
+        raise BedrockError("Empty response from model")
+
+    # Claude returns content as list of content blocks
+    text_parts = []
+    for block in content:
+        if block.get("type") == "text":
+            text_parts.append(block.get("text", ""))
+
+    return "".join(text_parts)

aws_simple/config.py

@@ -0,0 +1,71 @@
+"""Configuration management via environment variables."""
+
+import os
+
+from dotenv import load_dotenv
+
+from .exceptions import ConfigurationError
+
+# Load .env file if present
+load_dotenv()
+
+
+class Config:
+    """Centralized configuration for AWS services."""
+
+    @staticmethod
+    def _get_required(key: str) -> str:
+        """Get required environment variable or raise error."""
+        value = os.getenv(key)
+        if not value:
+            raise ConfigurationError(
+                f"Missing required environment variable: {key}. "
+                f"Please set it in your environment or .env file."
+            )
+        return value
+
+    @staticmethod
+    def _get_optional(key: str, default: str | None = None) -> str | None:
+        """Get optional environment variable with default."""
+        return os.getenv(key, default)
+
+    # AWS General
+    @property
+    def aws_region(self) -> str:
+        """AWS region (default: us-east-1)."""
+        return self._get_optional("AWS_REGION", "us-east-1") or "us-east-1"
+
+    @property
+    def aws_profile(self) -> str | None:
+        """AWS profile name (optional, for local development)."""
+        return self._get_optional("AWS_PROFILE")
+
+    # S3
+    @property
+    def s3_bucket(self) -> str:
+        """Default S3 bucket name."""
+        return self._get_required("AWS_S3_BUCKET")
+
+    # Textract
+    @property
+    def textract_region(self) -> str:
+        """Textract region (defaults to aws_region)."""
+        return self._get_optional("AWS_TEXTRACT_REGION") or self.aws_region
+
+    # Bedrock
+    @property
+    def bedrock_model_id(self) -> str:
+        """Default Bedrock model ID."""
+        return (
+            self._get_optional("AWS_BEDROCK_MODEL_ID", "anthropic.claude-3-5-sonnet-20241022-v2:0")
+            or "anthropic.claude-3-5-sonnet-20241022-v2:0"
+        )
+
+    @property
+    def bedrock_region(self) -> str:
+        """Bedrock region (defaults to aws_region)."""
+        return self._get_optional("AWS_BEDROCK_REGION") or self.aws_region
+
+
+# Singleton instance
+config = Config()

aws_simple/exceptions.py

@@ -0,0 +1,37 @@
+"""Custom exceptions for aws-simple library."""
+
+
+class AWSSimpleError(Exception):
+    """Base exception for all aws-simple errors."""
+
+    pass
+
+
+class ConfigurationError(AWSSimpleError):
+    """Raised when required environment variables are missing or invalid."""
+
+    pass
+
+
+class S3Error(AWSSimpleError):
+    """Raised when S3 operations fail."""
+
+    pass
+
+
+class TextractError(AWSSimpleError):
+    """Raised when Textract operations fail."""
+
+    pass
+
+
+class BedrockError(AWSSimpleError):
+    """Raised when Bedrock operations fail."""
+
+    pass
+
+
+class ClientInitializationError(AWSSimpleError):
+    """Raised when AWS client initialization fails."""
+
+    pass

aws_simple/models/__init__.py

@@ -0,0 +1,10 @@
+"""Data models for aws-simple."""
+
+from .textract import TextractDocument, TextractLine, TextractPage, TextractTable
+
+__all__ = [
+    "TextractDocument",
+    "TextractLine",
+    "TextractPage",
+    "TextractTable",
+]

aws_simple/models/textract.py

@@ -0,0 +1,82 @@
+"""Data models for Textract results."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class TextractLine:
+    """Represents a line of text extracted from a document."""
+
+    text: str
+    confidence: float
+    bounding_box: dict[str, float]  # {top, left, width, height}
+
+
+@dataclass
+class TextractTable:
+    """Represents a table extracted from a document."""
+
+    rows: int
+    columns: int
+    cells: list[list[str]]  # Matrix: rows x columns
+    confidence: float
+
+
+@dataclass
+class TextractPage:
+    """Represents a page in the extracted document."""
+
+    page_number: int
+    width: float
+    height: float
+    lines: list[TextractLine]
+    tables: list[TextractTable]
+    raw_text: str  # All text from this page concatenated
+
+
+@dataclass
+class TextractDocument:
+    """
+    Structured document result from Textract.
+
+    This is the main output format - clean, serializable JSON structure.
+    No AWS Blocks exposed.
+    """
+
+    pages: list[TextractPage]
+    full_text: str  # All text concatenated across all pages
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "pages": [
+                {
+                    "page_number": page.page_number,
+                    "width": page.width,
+                    "height": page.height,
+                    "lines": [
+                        {
+                            "text": line.text,
+                            "confidence": line.confidence,
+                            "bounding_box": line.bounding_box,
+                        }
+                        for line in page.lines
+                    ],
+                    "tables": [
+                        {
+                            "rows": table.rows,
+                            "columns": table.columns,
+                            "cells": table.cells,
+                            "confidence": table.confidence,
+                        }
+                        for table in page.tables
+                    ],
+                    "raw_text": page.raw_text,
+                }
+                for page in self.pages
+            ],
+            "full_text": self.full_text,
+            "metadata": self.metadata,
+        }