# 🎨 Strands Fun Tools
**Creative and interactive tools for Strands AI agents** - Build agents with unique capabilities for Bluetooth, vision, cursor control, screen reading, chess, and more!
[](LICENSE)
[](https://www.python.org/downloads/)
---
## ✨ Features
- **🔵 Bluetooth Monitoring** - Background device scanning, proximity detection, GATT operations
- **♟️ Chess Engine** - Stockfish integration for playing and analyzing chess
- **📋 Clipboard Management** - Monitor and control system clipboard with history
- **🖱️ Cursor Control** - Mouse automation with PyAutoGUI
- **👁️ Screen Reading** - OCR-based screen monitoring for autonomous control
- **📸 Computer Vision** - YOLO object detection, face recognition, photo capture
- **🎤 Audio Transcription** - Whisper-based continuous audio listening
- **🎨 Display Tools** - Human-like typing, custom spinners, templates
- **🔧 Utilities** - Cryptography, encoding, hashing, JSON/YAML processing
- **📦 Dynamic Packages** - Execute any Python package function at runtime
---
## 📦 Installation
### Basic Installation
```bash
pip install strands-fun-tools
```
This installs core dependencies: `strands-agents`, `pyautogui`, `pyperclip`, `pillow`
### Full Installation (All Features)
```bash
pip install "strands-fun-tools[all]"
```
### Selective Installation
Install only the features you need:
```bash
# Chess
pip install "strands-fun-tools[chess]"
# Vision (YOLO, face recognition, screen reader)
pip install "strands-fun-tools[vision]"
# Bluetooth
pip install "strands-fun-tools[bluetooth]"
# Audio transcription
pip install "strands-fun-tools[audio]"
# Templates & display
pip install "strands-fun-tools[template,display]"
# Utilities (crypto, YAML)
pip install "strands-fun-tools[utility]"
```
---
## 🚀 Quick Start
### Simple Agent Example
```python
from strands import Agent
from strands_fun_tools import clipboard, cursor, screen_reader
agent = Agent(
tools=[clipboard, cursor, screen_reader],
system_prompt="You can read screens and control the cursor!"
)
# Agent autonomously reads screen and clicks elements
response = agent("""
1. Read what's on my screen
2. Find the 'Submit' button
3. Click it
""")
```
### Background Monitoring Example
```python
from strands import Agent
from strands_fun_tools import bluetooth, clipboard, yolo_vision
agent = Agent(
tools=[bluetooth, clipboard, yolo_vision],
system_prompt="You have background monitoring capabilities!"
)
# Start background monitoring
agent("""
1. Start monitoring Bluetooth devices nearby
2. Start monitoring my clipboard
3. Start YOLO vision to detect objects from camera
4. Tell me when you detect my iPhone nearby or see a person
""")
```
---
## 🛠️ Available Tools
### 📡 Connectivity Tools
#### **bluetooth** - BLE Device Monitoring & Control
```python
# Start background scanning
agent.tool.bluetooth(action="start", scan_interval=5)
# Scan once
agent.tool.bluetooth(action="scan_once", duration=5)
# List discovered devices
agent.tool.bluetooth(action="list_devices")
# Get specific device
agent.tool.bluetooth(action="get_device", address="AA:BB:CC:DD:EE:FF")
# GATT operations
agent.tool.bluetooth(action="list_services", address="AA:BB:CC:DD:EE:FF")
agent.tool.bluetooth(action="read_characteristic", address="...", characteristic_uuid="...")
```
**Features:**
- Background BLE scanning
- Proximity detection (very_close/near/medium/far)
- GATT read/write/subscribe operations
- Device discovery logging
- RSSI-based proximity zones
---
### 🎮 Interactive Tools
#### **chess** - Stockfish Chess Engine
```python
# New game
agent.tool.chess(action="new_game", fen="startpos")
# Get best move
agent.tool.chess(action="get_best_move", depth=15, time=1000)
# Make move
agent.tool.chess(action="make_move", move="e2e4")
# Analyze position
agent.tool.chess(action="analyze", depth=20)
```
**Features:**
- Stockfish 16+ integration
- Position analysis with depth control
- Move validation
- Visual board display
- FEN notation support
---
#### **clipboard** - Clipboard Monitoring & Control
```python
# Start monitoring
agent.tool.clipboard(action="start", check_interval=1)
# Read clipboard
agent.tool.clipboard(action="read")
# Write to clipboard
agent.tool.clipboard(action="write", content="Hello World!")
# Get history
agent.tool.clipboard(action="get_history", limit=10)
```
**Features:**
- Background clipboard monitoring
- Content classification (url, code, email, text, number, file_path)
- Deduplication (only logs changes)
- Timestamped history logging
- Content preview
---
#### **cursor** - Mouse & Keyboard Control
```python
# Get position
agent.tool.cursor(action="position")
# Move cursor
agent.tool.cursor(action="move", x=100, y=100)
agent.tool.cursor(action="smooth_move", x=500, y=500, duration=1.0)
# Click
agent.tool.cursor(action="click", button="left")
agent.tool.cursor(action="double_click")
# Type text
agent.tool.cursor(action="type_text", text="Hello!")
# Keyboard shortcuts
agent.tool.cursor(action="hotkey", keys=["cmd", "c"]) # Copy
```
**Features:**
- Absolute and relative movement
- Smooth animated movement
- Left/right/middle click, drag
- Keyboard input and hotkeys
- Screen size detection
---
### 👁️ Vision Tools
#### **screen_reader** - OCR-Based Screen Monitoring
```python
# Start background monitoring
agent.tool.screen_reader(action="start", interval=2)
# Single capture
agent.tool.screen_reader(action="capture_once")
# Find element by text
agent.tool.screen_reader(action="find_element", search_text="Submit")
# List all detected elements
agent.tool.screen_reader(action="list_elements")
```
**Features:**
- Background OCR scanning with pytesseract
- Text detection with bounding boxes
- Element coordinates for clicking
- Content deduplication
- Timestamped element history
---
#### **yolo_vision** - Object Detection
```python
# Start background detection
agent.tool.yolo_vision(action="start", interval=2, model="yolov8n")
# Single detection
agent.tool.yolo_vision(action="detect_once")
# Get recent detections
agent.tool.yolo_vision(action="get_recent_detections", limit=10)
# Query objects
agent.tool.yolo_vision(action="query_objects", object_class="person")
```
**Features:**
- Background YOLOv8 object detection
- Real-time camera monitoring
- Object counting and tracking
- Confidence scoring
- Timestamped detection logging
---
#### **face_recognition** - AWS Rekognition
```python
# Detect faces in image
agent.tool.face_recognition(
action="detect_faces",
image_path="photo.jpg"
)
# Compare faces
agent.tool.face_recognition(
action="compare_faces",
source_image="face1.jpg",
target_image="face2.jpg",
similarity_threshold=80
)
```
**Features:**
- Face detection with AWS Rekognition
- Face comparison and similarity scoring
- Emotion detection
- Age range estimation
- Gender classification
---
#### **take_photo** - Camera Capture
```python
# Single photo
agent.tool.take_photo(action="capture", save_path="photo.jpg")
# Burst mode
agent.tool.take_photo(
action="burst",
count=5,
interval=1.0,
save_path="burst"
)
# List available cameras
agent.tool.take_photo(action="list_cameras")
```
**Features:**
- Single and burst capture modes
- Multiple camera support
- Configurable resolution
- Parallel burst capture
- Auto-timestamped filenames
---
### 🎤 Audio Tools
#### **listen** - Whisper Audio Transcription
```python
# Start listening
agent.tool.listen(action="start")
# Get recent transcripts
agent.tool.listen(action="get_transcripts", limit=10)
# Stop listening
agent.tool.listen(action="stop")
```
**Features:**
- Background audio monitoring
- OpenAI Whisper transcription
- Voice activity detection (VAD)
- Timestamped transcription logging
- Configurable language support
---
### 🎨 Display & UI Tools
#### **human_typer** - Human-Like Typing Simulation
```python
agent.tool.human_typer(
text="Hello World!",
emotion="excited", # calm, excited, thoughtful, rushed, nervous
typo_rate=2, # 0-10 percentage
thinking_pauses=True
)
```
**Features:**
- 5 emotion-based typing speeds
- Random typo generation
- Thinking pauses at punctuation
- Backspace corrections
- Variable typing rhythm
---
#### **spinner_generator** - Custom Loading Spinners
```python
agent.tool.spinner_generator(
spinner_type="dots12",
text="Loading...",
color="cyan",
duration=3
)
```
**Available spinners:** dots, line, pipe, star, moon, clock, arrow, bounce, and 50+ more!
---
#### **template** - Jinja2 Template Rendering
```python
# Create template
agent.tool.template(
action="create",
name="report",
content="# Report for {{ name }}\n\nScore: {{ score }}"
)
# Render template
agent.tool.template(
action="render",
name="report",
data={"name": "User", "score": 95}
)
```
**Features:**
- Jinja2 template engine
- Template creation and storage
- Variable substitution
- File and string rendering
---
### 🔧 Utility Tools
#### **utility** - Cryptography & Encoding
```python
# Encoding
agent.tool.utility(action="base64_encode", text="secret")
agent.tool.utility(action="url_encode", text="hello world")
# Hashing
agent.tool.utility(action="hash", text="password", algorithm="sha256")
# Encryption
agent.tool.utility(action="encrypt", text="secret", key="encryption-key")
# JSON/YAML formatting
agent.tool.utility(action="format_json", text='{"a":1}', indent=2)
```
**Features:**
- Base64, URL, HTML encoding/decoding
- SHA256, MD5, Blake2b hashing
- Fernet encryption/decryption
- UUID generation
- JSON/YAML formatting
---
#### **dynamic_package** - Runtime Package Executor
```python
# Execute any Python function
agent.tool.dynamic_package(
action="execute",
package="math",
function="sqrt",
args=[16]
)
# List available functions
agent.tool.dynamic_package(
action="list_functions",
package="random"
)
```
**Features:**
- Execute any installed package function
- Dynamic function discovery
- Arguments and kwargs support
- Function listing
---
#### **npm** - NPM Package Executor
```python
# Execute npm package
agent.tool.npm(
action="execute",
package="cowsay",
args=["Hello from NPM!"]
)
# Install and execute
agent.tool.npm(
action="execute",
package="figlet",
args=["Cool Text"],
install=True
)
```
**Features:**
- Execute any npm package
- Auto-installation support
- Arguments passing
- Stdout/stderr capture
---
## 🎯 Complete Example Agent
```python
"""Complete example agent with all fun tools."""
from strands import Agent
from strands_fun_tools import (
bluetooth,
chess,
clipboard,
cursor,
screen_reader,
yolo_vision,
human_typer,
spinner_generator,
template,
utility,
)
agent = Agent(
tools=[
bluetooth,
chess,
clipboard,
cursor,
screen_reader,
yolo_vision,
human_typer,
spinner_generator,
template,
utility,
],
system_prompt="""You are a creative AI agent with unique interactive capabilities.
You can:
- Monitor Bluetooth devices and detect proximity
- Play chess using the Stockfish engine
- Monitor and control the system clipboard
- Control the mouse cursor and automate tasks
- Read the screen using OCR
- Detect objects using YOLO vision
- Type with human-like characteristics
- Display custom loading spinners
- Render Jinja2 templates
- Perform cryptography and encoding operations
Be creative and explore these capabilities!""",
)
if __name__ == "__main__":
# Example usage
response = agent(
"""Show me what you can do! Start by:
1. Scanning for Bluetooth devices nearby
2. Getting my clipboard content
3. Detecting what's on my screen
4. Playing a move in chess"""
)
print(response)
```
---
## 🔥 Advanced Use Cases
### Autonomous Computer Control
Combine `screen_reader` + `cursor` for autonomous GUI interaction:
```python
from strands import Agent
from strands_fun_tools import screen_reader, cursor
agent = Agent(
tools=[screen_reader, cursor],
system_prompt="You can see and control the computer screen."
)
# Agent autonomously finds and clicks UI elements
agent("""
1. Find the 'File' menu on screen
2. Click it
3. Find 'Save' option
4. Click it
""")
```
### Proximity-Based Automation
Use `bluetooth` proximity detection:
```python
from strands import Agent
from strands_fun_tools import bluetooth
agent = Agent(
tools=[bluetooth],
system_prompt="Monitor my iPhone proximity and alert when I leave."
)
# Start monitoring
agent("""
Start monitoring my iPhone's Bluetooth signal.
Alert me when the signal drops below -70 dBm (I'm walking away).
""")
```
### Multi-Modal Monitoring
Combine multiple background monitors:
```python
from strands import Agent
from strands_fun_tools import bluetooth, clipboard, yolo_vision, listen
agent = Agent(
tools=[bluetooth, clipboard, yolo_vision, listen],
system_prompt="You have multi-modal awareness!"
)
# Start all monitors
agent("""
1. Start Bluetooth monitoring (detect devices)
2. Start clipboard monitoring (track copies)
3. Start YOLO vision (detect objects)
4. Start audio listening (transcribe speech)
5. Report any interesting events
""")
```
---
## 📚 Tool Reference
| Tool | Purpose | Key Actions |
|------|---------|-------------|
| **bluetooth** | BLE device monitoring & GATT | start, scan_once, list_devices, list_services, read_characteristic, subscribe |
| **chess** | Stockfish chess engine | new_game, get_best_move, make_move, analyze |
| **clipboard** | Clipboard management | start, read, write, get_history, clear_history |
| **cursor** | Mouse & keyboard control | move, click, drag, type_text, hotkey |
| **screen_reader** | OCR screen monitoring | start, capture_once, find_element, list_elements |
| **yolo_vision** | Object detection | start, detect_once, query_objects, get_recent_detections |
| **face_recognition** | Face detection (AWS) | detect_faces, compare_faces |
| **take_photo** | Camera capture | capture, burst, list_cameras |
| **listen** | Audio transcription | start, stop, get_transcripts |
| **human_typer** | Human-like typing | type with emotion and typos |
| **spinner_generator** | Loading animations | display custom spinners |
| **template** | Jinja2 templates | create, render, list |
| **utility** | Crypto & encoding | encode, decode, hash, encrypt |
| **dynamic_package** | Python packages | execute, list_functions |
| **npm** | NPM packages | execute (with auto-install) |
---
## 📋 Background Monitoring Tools
Several tools support **background monitoring mode**:
| Tool | Monitors | Interval | Logs To |
|------|----------|----------|---------|
| **bluetooth** | BLE devices | 2-60s | `.bluetooth_monitor/devices.jsonl` |
| **clipboard** | Clipboard content | 0.5-5s | `.clipboard_monitor/clipboard.jsonl` |
| **screen_reader** | Screen OCR | 1-10s | `.screen_monitor/elements.jsonl` |
| **yolo_vision** | Camera objects | 1-10s | `.yolo_detections/detections.jsonl` |
| **listen** | Audio speech | Continuous | `.audio_transcripts/transcripts.jsonl` |
**Pattern:**
```python
# Start monitoring
tool(action="start", interval=2)
# Query recent events
tool(action="get_history", limit=10)
# Stop monitoring
tool(action="stop")
```
---
## 🧪 Testing Tools
```python
from strands import Agent
from strands_fun_tools import chess, utility, template
agent = Agent(tools=[chess, utility, template])
# Test chess
agent("Start a new chess game and suggest the best opening move")
# Test utility
agent("Encode 'secret message' in base64 and then hash it with SHA256")
# Test template
agent("Create a template for a greeting card and render it with name='Alice'")
```
---
## 🔐 Security & Privacy
**Tools that access hardware:**
- `take_photo`, `yolo_vision`, `listen` - **Camera/microphone access**
- `bluetooth` - **Network scanning**
- `cursor`, `screen_reader` - **Screen access and control**
**Best practices:**
- Run agents in trusted environments only
- Review agent system prompts carefully
- Monitor background logging directories
- Clear history logs periodically
- Use firewall rules for network tools
---
## 🐛 Troubleshooting
### **Bluetooth not finding devices**
- Ensure Bluetooth is enabled
- Run with sudo on Linux: `sudo python agent.py`
- Grant Bluetooth permissions on macOS
### **YOLO not detecting objects**
- First run downloads YOLOv8 model (~6MB)
- Ensure camera permissions granted
- Check camera index (default: 0)
### **Screen reader finding no text**
- Install Tesseract: `brew install tesseract` (macOS)
- Ensure pytesseract can find tesseract binary
- Try higher resolution screenshots
### **Cursor control not working in container**
- PyAutoGUI requires GUI environment
- Not available in Docker containers
- Run on host machine with display
---
## 📖 Dependencies
**Core:**
- `strands-agents` - Strands AI framework
- `pyautogui` - Cursor control
- `pyperclip` - Clipboard access
- `pillow` - Image processing
**Optional (by feature):**
- **Chess:** `stockfish`, `rich`
- **Vision:** `opencv-python`, `ultralytics`, `pytesseract`
- **Bluetooth:** `bleak`
- **Audio:** `openai-whisper`, `sounddevice`, `webrtcvad`
- **Display:** `rich`, `halo`, `colorama`
- **Templates:** `jinja2`
- **Utilities:** `pyyaml`, `cryptography`, `boto3`
- **Dialog:** `prompt_toolkit`
---
## 🤝 Contributing
Issues and PRs welcome at [github.com/cagataycali/strands-fun-tools](https://github.com/cagataycali/strands-fun-tools)
**Development setup:**
```bash
git clone https://github.com/cagataycali/strands-fun-tools.git
cd strands-fun-tools
pip install -e ".[all,dev]"
```
---
## 📜 License
Apache-2.0 License - see [LICENSE](LICENSE) for details.
---
## 🙏 Acknowledgments
Built with:
- [Strands Agents](https://github.com/strands-agents/sdk-python) - AI agent framework
- [Stockfish](https://stockfishchess.org/) - Chess engine
- [YOLOv8](https://github.com/ultralytics/ultralytics) - Object detection
- [Whisper](https://github.com/openai/whisper) - Audio transcription
- [Bleak](https://github.com/hbldh/bleak) - Bluetooth Low Energy
- [PyAutoGUI](https://github.com/asweigart/pyautogui) - GUI automation
- [Pytesseract](https://github.com/madmaze/pytesseract) - OCR
---
<div align="center">
<p><strong>🎨 Make your AI agents fun and interactive! 🚀</strong></p>
<p>Built with ❤️ for the Strands community</p>
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/cagataycali/strands-fun-tools",
"name": "strands-fun-tools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "strands, ai, agents, tools, bluetooth, chess, clipboard, cursor, vision, audio, fun, creative",
"author": "Cagatay Cali",
"author_email": "Cagatay Cali <cagataycali@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/47/41/3c8a547d31a1ec34aa0b06def1be6c0ed08f8633ed5f23b2c007140fa7c8/strands_fun_tools-0.1.0.tar.gz",
"platform": null,
"description": "# \ud83c\udfa8 Strands Fun Tools\n\n**Creative and interactive tools for Strands AI agents** - Build agents with unique capabilities for Bluetooth, vision, cursor control, screen reading, chess, and more!\n\n[](LICENSE)\n[](https://www.python.org/downloads/)\n\n---\n\n## \u2728 Features\n\n- **\ud83d\udd35 Bluetooth Monitoring** - Background device scanning, proximity detection, GATT operations\n- **\u265f\ufe0f Chess Engine** - Stockfish integration for playing and analyzing chess\n- **\ud83d\udccb Clipboard Management** - Monitor and control system clipboard with history\n- **\ud83d\uddb1\ufe0f Cursor Control** - Mouse automation with PyAutoGUI\n- **\ud83d\udc41\ufe0f Screen Reading** - OCR-based screen monitoring for autonomous control\n- **\ud83d\udcf8 Computer Vision** - YOLO object detection, face recognition, photo capture\n- **\ud83c\udfa4 Audio Transcription** - Whisper-based continuous audio listening\n- **\ud83c\udfa8 Display Tools** - Human-like typing, custom spinners, templates\n- **\ud83d\udd27 Utilities** - Cryptography, encoding, hashing, JSON/YAML processing\n- **\ud83d\udce6 Dynamic Packages** - Execute any Python package function at runtime\n\n---\n\n## \ud83d\udce6 Installation\n\n### Basic Installation\n\n```bash\npip install strands-fun-tools\n```\n\nThis installs core dependencies: `strands-agents`, `pyautogui`, `pyperclip`, `pillow`\n\n### Full Installation (All Features)\n\n```bash\npip install \"strands-fun-tools[all]\"\n```\n\n### Selective Installation\n\nInstall only the features you need:\n\n```bash\n# Chess\npip install \"strands-fun-tools[chess]\"\n\n# Vision (YOLO, face recognition, screen reader)\npip install \"strands-fun-tools[vision]\"\n\n# Bluetooth\npip install \"strands-fun-tools[bluetooth]\"\n\n# Audio transcription\npip install \"strands-fun-tools[audio]\"\n\n# Templates & display\npip install \"strands-fun-tools[template,display]\"\n\n# Utilities (crypto, YAML)\npip install \"strands-fun-tools[utility]\"\n```\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Simple Agent Example\n\n```python\nfrom strands import Agent\nfrom strands_fun_tools import clipboard, cursor, screen_reader\n\nagent = Agent(\n tools=[clipboard, cursor, screen_reader],\n system_prompt=\"You can read screens and control the cursor!\"\n)\n\n# Agent autonomously reads screen and clicks elements\nresponse = agent(\"\"\"\n1. Read what's on my screen\n2. Find the 'Submit' button\n3. Click it\n\"\"\")\n```\n\n### Background Monitoring Example\n\n```python\nfrom strands import Agent\nfrom strands_fun_tools import bluetooth, clipboard, yolo_vision\n\nagent = Agent(\n tools=[bluetooth, clipboard, yolo_vision],\n system_prompt=\"You have background monitoring capabilities!\"\n)\n\n# Start background monitoring\nagent(\"\"\"\n1. Start monitoring Bluetooth devices nearby\n2. Start monitoring my clipboard\n3. Start YOLO vision to detect objects from camera\n4. Tell me when you detect my iPhone nearby or see a person\n\"\"\")\n```\n\n---\n\n## \ud83d\udee0\ufe0f Available Tools\n\n### \ud83d\udce1 Connectivity Tools\n\n#### **bluetooth** - BLE Device Monitoring & Control\n\n```python\n# Start background scanning\nagent.tool.bluetooth(action=\"start\", scan_interval=5)\n\n# Scan once\nagent.tool.bluetooth(action=\"scan_once\", duration=5)\n\n# List discovered devices\nagent.tool.bluetooth(action=\"list_devices\")\n\n# Get specific device\nagent.tool.bluetooth(action=\"get_device\", address=\"AA:BB:CC:DD:EE:FF\")\n\n# GATT operations\nagent.tool.bluetooth(action=\"list_services\", address=\"AA:BB:CC:DD:EE:FF\")\nagent.tool.bluetooth(action=\"read_characteristic\", address=\"...\", characteristic_uuid=\"...\")\n```\n\n**Features:**\n- Background BLE scanning\n- Proximity detection (very_close/near/medium/far)\n- GATT read/write/subscribe operations\n- Device discovery logging\n- RSSI-based proximity zones\n\n---\n\n### \ud83c\udfae Interactive Tools\n\n#### **chess** - Stockfish Chess Engine\n\n```python\n# New game\nagent.tool.chess(action=\"new_game\", fen=\"startpos\")\n\n# Get best move\nagent.tool.chess(action=\"get_best_move\", depth=15, time=1000)\n\n# Make move\nagent.tool.chess(action=\"make_move\", move=\"e2e4\")\n\n# Analyze position\nagent.tool.chess(action=\"analyze\", depth=20)\n```\n\n**Features:**\n- Stockfish 16+ integration\n- Position analysis with depth control\n- Move validation\n- Visual board display\n- FEN notation support\n\n---\n\n#### **clipboard** - Clipboard Monitoring & Control\n\n```python\n# Start monitoring\nagent.tool.clipboard(action=\"start\", check_interval=1)\n\n# Read clipboard\nagent.tool.clipboard(action=\"read\")\n\n# Write to clipboard\nagent.tool.clipboard(action=\"write\", content=\"Hello World!\")\n\n# Get history\nagent.tool.clipboard(action=\"get_history\", limit=10)\n```\n\n**Features:**\n- Background clipboard monitoring\n- Content classification (url, code, email, text, number, file_path)\n- Deduplication (only logs changes)\n- Timestamped history logging\n- Content preview\n\n---\n\n#### **cursor** - Mouse & Keyboard Control\n\n```python\n# Get position\nagent.tool.cursor(action=\"position\")\n\n# Move cursor\nagent.tool.cursor(action=\"move\", x=100, y=100)\nagent.tool.cursor(action=\"smooth_move\", x=500, y=500, duration=1.0)\n\n# Click\nagent.tool.cursor(action=\"click\", button=\"left\")\nagent.tool.cursor(action=\"double_click\")\n\n# Type text\nagent.tool.cursor(action=\"type_text\", text=\"Hello!\")\n\n# Keyboard shortcuts\nagent.tool.cursor(action=\"hotkey\", keys=[\"cmd\", \"c\"]) # Copy\n```\n\n**Features:**\n- Absolute and relative movement\n- Smooth animated movement\n- Left/right/middle click, drag\n- Keyboard input and hotkeys\n- Screen size detection\n\n---\n\n### \ud83d\udc41\ufe0f Vision Tools\n\n#### **screen_reader** - OCR-Based Screen Monitoring\n\n```python\n# Start background monitoring\nagent.tool.screen_reader(action=\"start\", interval=2)\n\n# Single capture\nagent.tool.screen_reader(action=\"capture_once\")\n\n# Find element by text\nagent.tool.screen_reader(action=\"find_element\", search_text=\"Submit\")\n\n# List all detected elements\nagent.tool.screen_reader(action=\"list_elements\")\n```\n\n**Features:**\n- Background OCR scanning with pytesseract\n- Text detection with bounding boxes\n- Element coordinates for clicking\n- Content deduplication\n- Timestamped element history\n\n---\n\n#### **yolo_vision** - Object Detection\n\n```python\n# Start background detection\nagent.tool.yolo_vision(action=\"start\", interval=2, model=\"yolov8n\")\n\n# Single detection\nagent.tool.yolo_vision(action=\"detect_once\")\n\n# Get recent detections\nagent.tool.yolo_vision(action=\"get_recent_detections\", limit=10)\n\n# Query objects\nagent.tool.yolo_vision(action=\"query_objects\", object_class=\"person\")\n```\n\n**Features:**\n- Background YOLOv8 object detection\n- Real-time camera monitoring\n- Object counting and tracking\n- Confidence scoring\n- Timestamped detection logging\n\n---\n\n#### **face_recognition** - AWS Rekognition\n\n```python\n# Detect faces in image\nagent.tool.face_recognition(\n action=\"detect_faces\",\n image_path=\"photo.jpg\"\n)\n\n# Compare faces\nagent.tool.face_recognition(\n action=\"compare_faces\",\n source_image=\"face1.jpg\",\n target_image=\"face2.jpg\",\n similarity_threshold=80\n)\n```\n\n**Features:**\n- Face detection with AWS Rekognition\n- Face comparison and similarity scoring\n- Emotion detection\n- Age range estimation\n- Gender classification\n\n---\n\n#### **take_photo** - Camera Capture\n\n```python\n# Single photo\nagent.tool.take_photo(action=\"capture\", save_path=\"photo.jpg\")\n\n# Burst mode\nagent.tool.take_photo(\n action=\"burst\",\n count=5,\n interval=1.0,\n save_path=\"burst\"\n)\n\n# List available cameras\nagent.tool.take_photo(action=\"list_cameras\")\n```\n\n**Features:**\n- Single and burst capture modes\n- Multiple camera support\n- Configurable resolution\n- Parallel burst capture\n- Auto-timestamped filenames\n\n---\n\n### \ud83c\udfa4 Audio Tools\n\n#### **listen** - Whisper Audio Transcription\n\n```python\n# Start listening\nagent.tool.listen(action=\"start\")\n\n# Get recent transcripts\nagent.tool.listen(action=\"get_transcripts\", limit=10)\n\n# Stop listening\nagent.tool.listen(action=\"stop\")\n```\n\n**Features:**\n- Background audio monitoring\n- OpenAI Whisper transcription\n- Voice activity detection (VAD)\n- Timestamped transcription logging\n- Configurable language support\n\n---\n\n### \ud83c\udfa8 Display & UI Tools\n\n#### **human_typer** - Human-Like Typing Simulation\n\n```python\nagent.tool.human_typer(\n text=\"Hello World!\",\n emotion=\"excited\", # calm, excited, thoughtful, rushed, nervous\n typo_rate=2, # 0-10 percentage\n thinking_pauses=True\n)\n```\n\n**Features:**\n- 5 emotion-based typing speeds\n- Random typo generation\n- Thinking pauses at punctuation\n- Backspace corrections\n- Variable typing rhythm\n\n---\n\n#### **spinner_generator** - Custom Loading Spinners\n\n```python\nagent.tool.spinner_generator(\n spinner_type=\"dots12\",\n text=\"Loading...\",\n color=\"cyan\",\n duration=3\n)\n```\n\n**Available spinners:** dots, line, pipe, star, moon, clock, arrow, bounce, and 50+ more!\n\n---\n\n#### **template** - Jinja2 Template Rendering\n\n```python\n# Create template\nagent.tool.template(\n action=\"create\",\n name=\"report\",\n content=\"# Report for {{ name }}\\n\\nScore: {{ score }}\"\n)\n\n# Render template\nagent.tool.template(\n action=\"render\",\n name=\"report\",\n data={\"name\": \"User\", \"score\": 95}\n)\n```\n\n**Features:**\n- Jinja2 template engine\n- Template creation and storage\n- Variable substitution\n- File and string rendering\n\n---\n\n### \ud83d\udd27 Utility Tools\n\n#### **utility** - Cryptography & Encoding\n\n```python\n# Encoding\nagent.tool.utility(action=\"base64_encode\", text=\"secret\")\nagent.tool.utility(action=\"url_encode\", text=\"hello world\")\n\n# Hashing\nagent.tool.utility(action=\"hash\", text=\"password\", algorithm=\"sha256\")\n\n# Encryption\nagent.tool.utility(action=\"encrypt\", text=\"secret\", key=\"encryption-key\")\n\n# JSON/YAML formatting\nagent.tool.utility(action=\"format_json\", text='{\"a\":1}', indent=2)\n```\n\n**Features:**\n- Base64, URL, HTML encoding/decoding\n- SHA256, MD5, Blake2b hashing\n- Fernet encryption/decryption\n- UUID generation\n- JSON/YAML formatting\n\n---\n\n#### **dynamic_package** - Runtime Package Executor\n\n```python\n# Execute any Python function\nagent.tool.dynamic_package(\n action=\"execute\",\n package=\"math\",\n function=\"sqrt\",\n args=[16]\n)\n\n# List available functions\nagent.tool.dynamic_package(\n action=\"list_functions\",\n package=\"random\"\n)\n```\n\n**Features:**\n- Execute any installed package function\n- Dynamic function discovery\n- Arguments and kwargs support\n- Function listing\n\n---\n\n#### **npm** - NPM Package Executor\n\n```python\n# Execute npm package\nagent.tool.npm(\n action=\"execute\",\n package=\"cowsay\",\n args=[\"Hello from NPM!\"]\n)\n\n# Install and execute\nagent.tool.npm(\n action=\"execute\",\n package=\"figlet\",\n args=[\"Cool Text\"],\n install=True\n)\n```\n\n**Features:**\n- Execute any npm package\n- Auto-installation support\n- Arguments passing\n- Stdout/stderr capture\n\n---\n\n## \ud83c\udfaf Complete Example Agent\n\n```python\n\"\"\"Complete example agent with all fun tools.\"\"\"\n\nfrom strands import Agent\nfrom strands_fun_tools import (\n bluetooth,\n chess,\n clipboard,\n cursor,\n screen_reader,\n yolo_vision,\n human_typer,\n spinner_generator,\n template,\n utility,\n)\n\nagent = Agent(\n tools=[\n bluetooth,\n chess,\n clipboard,\n cursor,\n screen_reader,\n yolo_vision,\n human_typer,\n spinner_generator,\n template,\n utility,\n ],\n system_prompt=\"\"\"You are a creative AI agent with unique interactive capabilities.\n\nYou can:\n- Monitor Bluetooth devices and detect proximity\n- Play chess using the Stockfish engine\n- Monitor and control the system clipboard\n- Control the mouse cursor and automate tasks\n- Read the screen using OCR\n- Detect objects using YOLO vision\n- Type with human-like characteristics\n- Display custom loading spinners\n- Render Jinja2 templates\n- Perform cryptography and encoding operations\n\nBe creative and explore these capabilities!\"\"\",\n)\n\nif __name__ == \"__main__\":\n # Example usage\n response = agent(\n \"\"\"Show me what you can do! Start by:\n1. Scanning for Bluetooth devices nearby\n2. Getting my clipboard content\n3. Detecting what's on my screen\n4. Playing a move in chess\"\"\"\n )\n print(response)\n```\n\n---\n\n## \ud83d\udd25 Advanced Use Cases\n\n### Autonomous Computer Control\n\nCombine `screen_reader` + `cursor` for autonomous GUI interaction:\n\n```python\nfrom strands import Agent\nfrom strands_fun_tools import screen_reader, cursor\n\nagent = Agent(\n tools=[screen_reader, cursor],\n system_prompt=\"You can see and control the computer screen.\"\n)\n\n# Agent autonomously finds and clicks UI elements\nagent(\"\"\"\n1. Find the 'File' menu on screen\n2. Click it\n3. Find 'Save' option\n4. Click it\n\"\"\")\n```\n\n### Proximity-Based Automation\n\nUse `bluetooth` proximity detection:\n\n```python\nfrom strands import Agent\nfrom strands_fun_tools import bluetooth\n\nagent = Agent(\n tools=[bluetooth],\n system_prompt=\"Monitor my iPhone proximity and alert when I leave.\"\n)\n\n# Start monitoring\nagent(\"\"\"\nStart monitoring my iPhone's Bluetooth signal.\nAlert me when the signal drops below -70 dBm (I'm walking away).\n\"\"\")\n```\n\n### Multi-Modal Monitoring\n\nCombine multiple background monitors:\n\n```python\nfrom strands import Agent\nfrom strands_fun_tools import bluetooth, clipboard, yolo_vision, listen\n\nagent = Agent(\n tools=[bluetooth, clipboard, yolo_vision, listen],\n system_prompt=\"You have multi-modal awareness!\"\n)\n\n# Start all monitors\nagent(\"\"\"\n1. Start Bluetooth monitoring (detect devices)\n2. Start clipboard monitoring (track copies)\n3. Start YOLO vision (detect objects)\n4. Start audio listening (transcribe speech)\n5. Report any interesting events\n\"\"\")\n```\n\n---\n\n## \ud83d\udcda Tool Reference\n\n| Tool | Purpose | Key Actions |\n|------|---------|-------------|\n| **bluetooth** | BLE device monitoring & GATT | start, scan_once, list_devices, list_services, read_characteristic, subscribe |\n| **chess** | Stockfish chess engine | new_game, get_best_move, make_move, analyze |\n| **clipboard** | Clipboard management | start, read, write, get_history, clear_history |\n| **cursor** | Mouse & keyboard control | move, click, drag, type_text, hotkey |\n| **screen_reader** | OCR screen monitoring | start, capture_once, find_element, list_elements |\n| **yolo_vision** | Object detection | start, detect_once, query_objects, get_recent_detections |\n| **face_recognition** | Face detection (AWS) | detect_faces, compare_faces |\n| **take_photo** | Camera capture | capture, burst, list_cameras |\n| **listen** | Audio transcription | start, stop, get_transcripts |\n| **human_typer** | Human-like typing | type with emotion and typos |\n| **spinner_generator** | Loading animations | display custom spinners |\n| **template** | Jinja2 templates | create, render, list |\n| **utility** | Crypto & encoding | encode, decode, hash, encrypt |\n| **dynamic_package** | Python packages | execute, list_functions |\n| **npm** | NPM packages | execute (with auto-install) |\n\n---\n\n## \ud83d\udccb Background Monitoring Tools\n\nSeveral tools support **background monitoring mode**:\n\n| Tool | Monitors | Interval | Logs To |\n|------|----------|----------|---------|\n| **bluetooth** | BLE devices | 2-60s | `.bluetooth_monitor/devices.jsonl` |\n| **clipboard** | Clipboard content | 0.5-5s | `.clipboard_monitor/clipboard.jsonl` |\n| **screen_reader** | Screen OCR | 1-10s | `.screen_monitor/elements.jsonl` |\n| **yolo_vision** | Camera objects | 1-10s | `.yolo_detections/detections.jsonl` |\n| **listen** | Audio speech | Continuous | `.audio_transcripts/transcripts.jsonl` |\n\n**Pattern:**\n```python\n# Start monitoring\ntool(action=\"start\", interval=2)\n\n# Query recent events\ntool(action=\"get_history\", limit=10)\n\n# Stop monitoring\ntool(action=\"stop\")\n```\n\n---\n\n## \ud83e\uddea Testing Tools\n\n```python\nfrom strands import Agent\nfrom strands_fun_tools import chess, utility, template\n\nagent = Agent(tools=[chess, utility, template])\n\n# Test chess\nagent(\"Start a new chess game and suggest the best opening move\")\n\n# Test utility\nagent(\"Encode 'secret message' in base64 and then hash it with SHA256\")\n\n# Test template\nagent(\"Create a template for a greeting card and render it with name='Alice'\")\n```\n\n---\n\n## \ud83d\udd10 Security & Privacy\n\n**Tools that access hardware:**\n- `take_photo`, `yolo_vision`, `listen` - **Camera/microphone access**\n- `bluetooth` - **Network scanning**\n- `cursor`, `screen_reader` - **Screen access and control**\n\n**Best practices:**\n- Run agents in trusted environments only\n- Review agent system prompts carefully\n- Monitor background logging directories\n- Clear history logs periodically\n- Use firewall rules for network tools\n\n---\n\n## \ud83d\udc1b Troubleshooting\n\n### **Bluetooth not finding devices**\n- Ensure Bluetooth is enabled\n- Run with sudo on Linux: `sudo python agent.py`\n- Grant Bluetooth permissions on macOS\n\n### **YOLO not detecting objects**\n- First run downloads YOLOv8 model (~6MB)\n- Ensure camera permissions granted\n- Check camera index (default: 0)\n\n### **Screen reader finding no text**\n- Install Tesseract: `brew install tesseract` (macOS)\n- Ensure pytesseract can find tesseract binary\n- Try higher resolution screenshots\n\n### **Cursor control not working in container**\n- PyAutoGUI requires GUI environment\n- Not available in Docker containers\n- Run on host machine with display\n\n---\n\n## \ud83d\udcd6 Dependencies\n\n**Core:**\n- `strands-agents` - Strands AI framework\n- `pyautogui` - Cursor control\n- `pyperclip` - Clipboard access\n- `pillow` - Image processing\n\n**Optional (by feature):**\n- **Chess:** `stockfish`, `rich`\n- **Vision:** `opencv-python`, `ultralytics`, `pytesseract`\n- **Bluetooth:** `bleak`\n- **Audio:** `openai-whisper`, `sounddevice`, `webrtcvad`\n- **Display:** `rich`, `halo`, `colorama`\n- **Templates:** `jinja2`\n- **Utilities:** `pyyaml`, `cryptography`, `boto3`\n- **Dialog:** `prompt_toolkit`\n\n---\n\n## \ud83e\udd1d Contributing\n\nIssues and PRs welcome at [github.com/cagataycali/strands-fun-tools](https://github.com/cagataycali/strands-fun-tools)\n\n**Development setup:**\n```bash\ngit clone https://github.com/cagataycali/strands-fun-tools.git\ncd strands-fun-tools\npip install -e \".[all,dev]\"\n```\n\n---\n\n## \ud83d\udcdc License\n\nApache-2.0 License - see [LICENSE](LICENSE) for details.\n\n---\n\n## \ud83d\ude4f Acknowledgments\n\nBuilt with:\n- [Strands Agents](https://github.com/strands-agents/sdk-python) - AI agent framework\n- [Stockfish](https://stockfishchess.org/) - Chess engine\n- [YOLOv8](https://github.com/ultralytics/ultralytics) - Object detection\n- [Whisper](https://github.com/openai/whisper) - Audio transcription\n- [Bleak](https://github.com/hbldh/bleak) - Bluetooth Low Energy\n- [PyAutoGUI](https://github.com/asweigart/pyautogui) - GUI automation\n- [Pytesseract](https://github.com/madmaze/pytesseract) - OCR\n\n---\n\n<div align=\"center\">\n <p><strong>\ud83c\udfa8 Make your AI agents fun and interactive! \ud83d\ude80</strong></p>\n <p>Built with \u2764\ufe0f for the Strands community</p>\n</div>\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Creative and utility tools for Strands AI agents - interactive experiences",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/cagataycali/strands-fun-tools/issues",
"Documentation": "https://github.com/cagataycali/strands-fun-tools",
"Homepage": "https://github.com/cagataycali/strands-fun-tools",
"Repository": "https://github.com/cagataycali/strands-fun-tools"
},
"split_keywords": [
"strands",
" ai",
" agents",
" tools",
" bluetooth",
" chess",
" clipboard",
" cursor",
" vision",
" audio",
" fun",
" creative"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3ecb137e0b9be26abad28d8b949c06e0d7edd94429369ab675e34f06097f52f4",
"md5": "3742a59f0af906cc3f7bb1bf2cd1b911",
"sha256": "fdea49226924f357ec0bc5f46ef52d33ebc80d9c6b748f19ec040fbcc0946070"
},
"downloads": -1,
"filename": "strands_fun_tools-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3742a59f0af906cc3f7bb1bf2cd1b911",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 65314,
"upload_time": "2025-10-26T01:05:23",
"upload_time_iso_8601": "2025-10-26T01:05:23.195228Z",
"url": "https://files.pythonhosted.org/packages/3e/cb/137e0b9be26abad28d8b949c06e0d7edd94429369ab675e34f06097f52f4/strands_fun_tools-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "47413c8a547d31a1ec34aa0b06def1be6c0ed08f8633ed5f23b2c007140fa7c8",
"md5": "d376943e7f46b5aa4957f28d06d0ccf4",
"sha256": "98cda2795cbcadd38f3bd59c9a2530d6305f6159312292d95a036d238cb89df5"
},
"downloads": -1,
"filename": "strands_fun_tools-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d376943e7f46b5aa4957f28d06d0ccf4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 65493,
"upload_time": "2025-10-26T01:05:25",
"upload_time_iso_8601": "2025-10-26T01:05:25.124396Z",
"url": "https://files.pythonhosted.org/packages/47/41/3c8a547d31a1ec34aa0b06def1be6c0ed08f8633ed5f23b2c007140fa7c8/strands_fun_tools-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 01:05:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cagataycali",
"github_project": "strands-fun-tools",
"github_not_found": true,
"lcname": "strands-fun-tools"
}
JSON
