Nova Act research preview simple tutorial

nova-act/tutorials/research/00-setup/README.md

@@ -0,0 +1,181 @@
+# Amazon Nova Act Tutorials - Setup Guide
+
+## Overview
+This setup guide prepares your environment for all Amazon Nova Act tutorials (01-04). Complete this setup once to run any tutorial script.
+
+## What This Setup Includes
+- Python virtual environment creation
+- All required dependencies installation
+- Nova Act SDK installation and verification
+- API key configuration guidance
+- Optional Chrome browser installation
+- Environment validation
+
+## Prerequisites
+- **Operating System:** macOS Sierra+, Ubuntu 22.04+, WSL2, or Windows 10+
+- **Python:** 3.10 or higher
+- **Internet connection:** Required for package installation
+- **Terminal access:** Command line interface
+
+## Quick Setup
+
+### Automated Setup (Recommended)
+```bash
+cd tutorials/research-preview/00-setup
+./setup.sh
+```
+
+This script will:
+1. ✓ Check Python version (3.10+ required)
+2. ✓ Create virtual environment at `./venv`
+3. ✓ Install all dependencies
+4. ✓ Verify Nova Act installation
+5. ✓ Guide you through API key setup
+6. ✓ Optionally install Chrome browser
+
+### Manual Setup
+```bash
+# 1. Navigate to setup directory
+cd tutorials/research-preview/00-setup
+
+# 2. Create and activate virtual environment
+python3 -m venv venv
+source venv/bin/activate  # macOS/Linux
+# OR venv\Scripts\activate  # Windows
+
+# 3. Install dependencies
+pip install --upgrade pip
+pip install -r requirements.txt
+
+# 4. Verify installation
+python3 -c "import nova_act; print(f'Nova Act version: {nova_act.__version__}')"
+```
+
+## API Key Setup
+
+### Step 1: Get Your API Key
+1. Visit [https://nova.amazon.com/act](https://nova.amazon.com/act)
+2. Sign up or log in
+3. Generate an API key
+
+### Step 2: Set Environment Variable
+**Current session:**
+```bash
+export NOVA_ACT_API_KEY="your_api_key_here"
+```
+
+**Persistent (recommended):**
+```bash
+# For bash
+echo 'export NOVA_ACT_API_KEY="your_api_key_here"' >> ~/.bashrc
+source ~/.bashrc
+
+# For zsh
+echo 'export NOVA_ACT_API_KEY="your_api_key_here"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### Step 3: Verify
+```bash
+echo $NOVA_ACT_API_KEY  # Should print your API key
+```
+
+## Dependencies Installed
+- **nova-act** (>=1.0.0) - Amazon Nova Act SDK
+- **playwright** (>=1.30.0) - Browser automation
+- **pydantic** (>=2.0.0) - Data validation
+- **pandas** (>=2.0.0) - Data analysis (Tutorial 03)
+- **requests** (>=2.31.0) - HTTP library (Tutorial 03)
+- **boto3** (>=1.28.0) - AWS SDK (Tutorial 04, optional)
+
+## Verifying Setup
+```bash
+# Activate environment
+source venv/bin/activate
+
+# Check installations
+python3 --version  # Should be 3.10+
+python3 -c "import nova_act; print(nova_act.__version__)"
+echo $NOVA_ACT_API_KEY  # Should print your key
+```
+
+## Running Tutorials
+Once setup is complete:
+
+```bash
+# Tutorial 01 - Getting Started
+cd ../01-getting-started && python 1_getting_started.py
+
+# Tutorial 02 - Human in the Loop
+cd ../02-human-in-loop && python 1_captcha_handling.py
+
+# Tutorial 03 - Tool Use
+cd ../03-tool-use && python 1_page_object_usage.py
+
+# Tutorial 04 - Observability
+cd ../04-observability && python 1_observability.py
+```
+
+**Note:** Always activate the virtual environment first:
+```bash
+source tutorials/research-preview/00-setup/venv/bin/activate
+```
+
+## Troubleshooting
+
+### Python Version Issues
+Install Python 3.10+ from [python.org](https://www.python.org/downloads/) or use pyenv.
+
+### Virtual Environment Issues
+```bash
+# Install venv module (Ubuntu/Debian)
+sudo apt-get install python3-venv
+```
+
+### Permission Issues
+```bash
+chmod +x setup.sh
+./setup.sh
+```
+
+### Import Errors
+1. Ensure virtual environment is activated
+2. Reinstall dependencies: `pip install -r requirements.txt`
+
+### API Key Issues
+1. Verify it's set: `echo $NOVA_ACT_API_KEY`
+2. Check for typos or extra spaces
+3. Re-export if needed
+
+### Browser Issues
+```bash
+# Install Chrome
+playwright install chrome
+# Or use default Chromium
+playwright install
+```
+
+## Security Notes
+- Never commit your API key - use environment variables
+- Protect your virtual environment
+- Follow security best practices in tutorials
+- Be cautious with sensitive data
+
+## What's Next
+After setup completion:
+1. Start with Tutorial 01 - Getting Started
+2. Progress through tutorials in order (01-04)
+3. Explore Nova Act samples
+4. Build your own automations
+
+## Additional Resources
+- [Nova Act Documentation](https://nova.amazon.com/act)
+- [Nova Act GitHub Repository](https://github.com/aws/nova-act)
+- [Playwright Documentation](https://playwright.dev/python/)
+
+## Getting Help
+1. Check this README for common issues
+2. Review tutorial-specific READMEs
+3. Check Nova Act documentation
+4. Report issues on GitHub
+5. Email: nova-act@amazon.com

nova-act/tutorials/research/00-setup/requirements.txt

@@ -0,0 +1,21 @@
+# Amazon Nova Act Tutorials - Complete Dependencies
+# This file includes all dependencies needed for tutorials 01-04
+
+# Core dependencies
+nova-act>=1.0.0
+playwright>=1.30.0
+
+# Data processing (Tutorial 03)
+pandas>=2.0.0
+
+# API integration (Tutorial 03)
+requests>=2.31.0
+
+# Data validation (all tutorials)
+pydantic>=2.0.0
+
+# Optional: Excel export support (Tutorial 03)
+openpyxl>=3.1.0
+
+# Optional: AWS S3 integration (Tutorial 04)
+boto3>=1.28.0

nova-act/tutorials/research/00-setup/setup.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+# Amazon Nova Act Tutorials - Setup Script
+# This script sets up your environment for all Nova Act tutorials (01-04)
+
+set -e  # Exit on error
+
+echo "======================================================================"
+echo "Amazon Nova Act Tutorials - Environment Setup"
+echo "======================================================================"
+
+# Check Python version
+echo ""
+echo "Checking Python version..."
+python_version=$(python3 --version 2>&1 | awk '{print $2}')
+echo "✓ Found Python $python_version"
+
+# Check if Python 3.10+
+required_version="3.10"
+if ! python3 -c "import sys; exit(0 if sys.version_info >= (3, 10) else 1)"; then
+    echo "✗ Python 3.10 or higher is required"
+    echo "  Current version: $python_version"
+    exit 1
+fi
+
+# Create virtual environment
+echo ""
+echo "Creating virtual environment..."
+if [ -d "venv" ]; then
+    echo "⚠️  Virtual environment already exists at ./venv"
+    read -p "Do you want to recreate it? (y/N): " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        rm -rf venv
+        python3 -m venv venv
+        echo "✓ Virtual environment recreated"
+    else
+        echo "✓ Using existing virtual environment"
+    fi
+else
+    python3 -m venv venv
+    echo "✓ Virtual environment created at ./venv"
+fi
+
+# Activate virtual environment
+echo ""
+echo "Activating virtual environment..."
+source venv/bin/activate
+echo "✓ Virtual environment activated"
+
+# Upgrade pip
+echo ""
+echo "Upgrading pip..."
+pip install --upgrade pip --quiet
+echo "✓ pip upgraded"
+
+# Install dependencies
+echo ""
+echo "Installing dependencies..."
+pip install -r requirements.txt
+echo "✓ All dependencies installed"
+
+# Verify Nova Act installation
+echo ""
+echo "Verifying Nova Act installation..."
+python3 -c "import nova_act; print(f'✓ Nova Act version: {nova_act.__version__}')"
+
+# Check for API key
+echo ""
+echo "======================================================================"
+echo "API Key Setup"
+echo "======================================================================"
+if [ -z "$NOVA_ACT_API_KEY" ]; then
+    echo "⚠️  NOVA_ACT_API_KEY environment variable is not set"
+    echo ""
+    echo "To get an API key:"
+    echo "  1. Visit https://nova.amazon.com/act"
+    echo "  2. Sign up and generate an API key"
+    echo "  3. Set it as an environment variable:"
+    echo ""
+    echo "     export NOVA_ACT_API_KEY=\"your_api_key_here\""
+    echo ""
+    echo "  4. Add to your shell profile (~/.bashrc or ~/.zshrc) to persist:"
+    echo ""
+    echo "     echo 'export NOVA_ACT_API_KEY=\"your_api_key_here\"' >> ~/.zshrc"
+    echo ""
+else
+    echo "✓ NOVA_ACT_API_KEY is set"
+fi
+
+# Optional: Install Chrome
+echo ""
+echo "======================================================================"
+echo "Browser Setup (Optional)"
+echo "======================================================================"
+echo "Nova Act works best with Google Chrome."
+echo "Playwright will use Chromium by default, but you can install Chrome:"
+echo ""
+echo "  playwright install chrome"
+echo ""
+read -p "Install Chrome now? (y/N): " -n 1 -r
+echo
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+    playwright install chrome
+    echo "✓ Chrome installed"
+else
+    echo "✓ Skipping Chrome installation (will use Chromium)"
+fi
+
+# Summary
+echo ""
+echo "======================================================================"
+echo "Setup Complete!"
+echo "======================================================================"
+echo ""
+echo "✓ Virtual environment created at: ./venv"
+echo "✓ All dependencies installed"
+echo "✓ Nova Act verified"
+echo ""
+echo "Next steps:"
+echo "  1. Set your API key (if not already set):"
+echo "     export NOVA_ACT_API_KEY=\"your_api_key_here\""
+echo ""
+echo "  2. Activate the virtual environment:"
+echo "     source venv/bin/activate"
+echo ""
+echo "  3. Run any tutorial script:"
+echo "     python ../01-getting-started/getting_started.py"
+echo "     python ../02-human-in-loop/captcha_handling.py"
+echo "     python ../03-tool-use/page_object_usage.py"
+echo "     python ../04-observability/observability.py"
+echo ""
+echo "  4. Read the README in each tutorial directory for details"
+echo ""
+echo "Happy automating with Nova Act!"
+echo "======================================================================"