feat: enable agents to analyze S3 datasets with comprehensive data loader

.pre-commit-config.yaml

@@ -1,36 +1,36 @@
-repos:
-  - repo: local
-    hooks:
-      - id: hatch-format
-        name: Format code
-        entry: hatch fmt --formatter
-        language: system
-        pass_filenames: false
-        types: [python]
-        stages: [pre-commit]
-      - id: hatch-lint
-        name: Lint code
-        entry: hatch fmt --linter
-        language: system
-        pass_filenames: false
-        types: [python]
-        stages: [pre-commit]
-      - id: hatch-test-lint
-        name: Type linting
-        entry: hatch run test-lint
-        language: system
-        pass_filenames: false
-        types: [ python ]
-        stages: [ pre-commit ]
-      - id: hatch-test
-        name: Unit tests
-        entry: hatch test --cover
-        language: system
-        pass_filenames: false
-        types: [python]
-        stages: [pre-commit]
-      - id: commitizen-check
-        name: Check commit message
-        entry: hatch run cz check --commit-msg-file
-        language: system
+repos:
+  - repo: local
+    hooks:
+      - id: hatch-format
+        name: Format code
+        entry: hatch fmt --formatter
+        language: system
+        pass_filenames: false
+        types: [python]
+        stages: [pre-commit]
+      - id: hatch-lint
+        name: Lint code
+        entry: hatch fmt --linter
+        language: system
+        pass_filenames: false
+        types: [python]
+        stages: [pre-commit]
+      - id: hatch-test-lint
+        name: Type linting
+        entry: hatch run test-lint
+        language: system
+        pass_filenames: false
+        types: [ python ]
+        stages: [ pre-commit ]
+      - id: hatch-test
+        name: Unit tests
+        entry: hatch test --cover
+        language: system
+        pass_filenames: false
+        types: [python]
+        stages: [pre-commit]
+      - id: commitizen-check
+        name: Check commit message
+        entry: hatch run cz check --commit-msg-file
+        language: system
         stages: [commit-msg]

README.md

@@ -114,6 +114,7 @@ Below is a comprehensive table of all available tools, how to use them with an a
 | calculator | `agent.tool.calculator(expression="2 * sin(pi/4) + log(e**2)")` | Performing mathematical operations, symbolic math, equation solving |
 | code_interpreter | `code_interpreter = AgentCoreCodeInterpreter(region="us-west-2"); agent = Agent(tools=[code_interpreter.code_interpreter])` | Execute code in isolated sandbox environments with multi-language support (Python, JavaScript, TypeScript), persistent sessions, and file operations |
 | use_aws | `agent.tool.use_aws(service_name="s3", operation_name="list_buckets", parameters={}, region="us-west-2")` | Interacting with AWS services, cloud resource management |
+| s3_data_loader | `agent.tool.s3_data_loader(bucket="my-bucket", key="data.csv", operation="describe")` | Load CSV/Parquet/JSON/Excel files from S3 into pandas DataFrames for quick data analysis and statistics |
 | retrieve | `agent.tool.retrieve(text="What is STRANDS?")` | Retrieving information from Amazon Bedrock Knowledge Bases with optional metadata |
 | nova_reels | `agent.tool.nova_reels(action="create", text="A cinematic shot of mountains", s3_bucket="my-bucket")` | Create high-quality videos using Amazon Bedrock Nova Reel with configurable parameters via environment variables |
 | agent_core_memory | `agent.tool.agent_core_memory(action="record", content="Hello, I like vegetarian food")` | Store and retrieve memories with Amazon Bedrock Agent Core Memory service |
@@ -469,6 +470,147 @@ result = agent.tool.swarm(
 )
 ```
 
+### S3 Data Loader
+
+```python
+from strands import Agent
+from strands_tools import s3_data_loader
+
+agent = Agent(tools=[s3_data_loader])
+
+# Load CSV file and get basic statistics
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv",
+    operation="describe"
+)
+
+# Get file shape (rows and columns)
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket", 
+    key="datasets/sales_data.csv",
+    operation="shape"
+)
+
+# Get column information
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv", 
+    operation="columns"
+)
+
+# Preview first 10 rows
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv",
+    operation="head",
+    rows=10
+)
+
+# Load Parquet file
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/analytics.parquet",
+    operation="describe"
+)
+
+# Load JSON file
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/data.json",
+    operation="shape"
+)
+
+# Load Excel file
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/report.xlsx",
+    operation="columns"
+)
+
+# Load TSV file
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/data.tsv",
+    operation="head"
+)
+
+# Use custom AWS region
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv",
+    operation="shape",
+    region="us-west-2"
+)
+
+# Advanced Operations (Phase 2B)
+
+# Query data with pandas syntax
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv",
+    operation="query",
+    query="age > 25 and city == 'NYC'",
+    rows=10
+)
+
+# Get random sample of data
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv",
+    operation="sample",
+    rows=5
+)
+
+# Get detailed file and data information
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv",
+    operation="info"
+)
+
+# Get unique values for all columns
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv",
+    operation="unique"
+)
+
+# Get unique values for specific column
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="datasets/sales_data.csv",
+    operation="unique",
+    column="category"
+)
+
+# Batch Operations (Phase 2C)
+
+# List files in S3 bucket with prefix
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    operation="list_files",
+    prefix="datasets/",
+    pattern="*.csv"
+)
+
+# Load multiple files at once
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    operation="batch_load",
+    keys=["file1.csv", "file2.csv", "file3.csv"],
+    rows=5
+)
+
+# Compare two datasets
+result = agent.tool.s3_data_loader(
+    bucket="my-data-bucket",
+    key="current_data.csv",
+    operation="compare",
+    compare_key="previous_data.csv"
+)
+```
+
 ### Use AWS
 
 ```python

pyproject.toml

@@ -43,6 +43,10 @@ dependencies = [
     # Note: Always want the latest tzdata
     "tzdata ; platform_system == 'Windows'",
     "botocore>=1.39.7,<2.0.0",
+    "boto3>=1.26.0,<2.0.0",
+    "pandas>=2.0.0,<3.0.0",
+    "pyarrow>=10.0.0,<23.0.0",
+    "openpyxl>=3.0.0,<4.0.0",
 ]
 
 [tool.hatch.build.targets.wheel]

src/strands_tools/retrieve.py

@@ -176,8 +176,8 @@
                         "lessThanOrEquals, in (value in list), notIn, listContains (list contains value), "
                         "stringContains (substring match), startsWith (OpenSearch Serverless only), "
                         "andAll (all conditions must match, min 2 items), orAll (at least one condition must match, "
-                        "min 2 items). Example: {\"andAll\": [{\"equals\": {\"key\": \"category\", "
-                        "\"value\": \"security\"}}, {\"greaterThan\": {\"key\": \"year\", \"value\": \"2022\"}}]}"
+                        'min 2 items). Example: {"andAll": [{"equals": {"key": "category", '
+                        '"value": "security"}}, {"greaterThan": {"key": "year", "value": "2022"}}]}'
                     ),
                 },
             },