machinaos 0.0.10 → 0.0.13

package/server/skills/task_agent/timer-skill/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: timer-skill
+description: Set one-time delayed timers. Execute actions after a specified duration (seconds, minutes, hours, days).
+allowed-tools: timer
+metadata:
+  author: machina
+  version: "1.0"
+  category: automation
+  icon: "⏱️"
+  color: "#10B981"
+---
+
+# Timer Tool
+
+Set one-time delayed execution timers.
+
+## How It Works
+
+This skill provides instructions for the **Timer** tool node. Connect the **Timer** node to Zeenie's `input-tools` handle to enable timed delays.
+
+## timer Tool
+
+Create a one-time timer that triggers after a specified duration.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| duration | number | Yes | Time value for the delay |
+| unit | string | Yes | Time unit: `"seconds"`, `"minutes"`, `"hours"`, `"days"` |
+
+### Time Units
+
+| Unit | Range | Use Case |
+|------|-------|----------|
+| `seconds` | 1-3600 | Short delays, testing |
+| `minutes` | 1-1440 | Task reminders, short waits |
+| `hours` | 1-168 | Scheduled checks, delayed notifications |
+| `days` | 1-30 | Long-term reminders, follow-ups |
+
+### Examples
+
+**30 second delay:**
+```json
+{
+  "duration": 30,
+  "unit": "seconds"
+}
+```
+
+**5 minute reminder:**
+```json
+{
+  "duration": 5,
+  "unit": "minutes"
+}
+```
+
+**1 hour delay:**
+```json
+{
+  "duration": 1,
+  "unit": "hours"
+}
+```
+
+**2 day follow-up:**
+```json
+{
+  "duration": 2,
+  "unit": "days"
+}
+```
+
+### Response Format
+
+**Timer set:**
+```json
+{
+  "success": true,
+  "message": "Timer set for 5 minutes",
+  "duration": 5,
+  "unit": "minutes",
+  "duration_seconds": 300,
+  "trigger_at": "2025-01-30T12:05:00Z"
+}
+```
+
+**Timer triggered:**
+```json
+{
+  "success": true,
+  "triggered": true,
+  "message": "Timer completed after 5 minutes",
+  "duration": 5,
+  "unit": "minutes"
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": "Duration must be a positive number"
+}
+```
+
+## Use Cases
+
+| Use Case | Duration | Unit | Description |
+|----------|----------|------|-------------|
+| Quick test | 10-30 | seconds | Testing workflow execution |
+| Reminder | 5-30 | minutes | Short-term reminders |
+| Rate limit | 60 | seconds | Wait between API calls |
+| Daily check | 24 | hours | Daily automation |
+| Follow-up | 2-7 | days | Long-term follow-ups |
+
+## Common Workflows
+
+### Delayed notification
+
+1. Receive user request for reminder
+2. Set timer with requested duration
+3. Timer triggers → send notification
+
+### Rate-limited API calls
+
+1. Make API call
+2. Set 60-second timer
+3. Timer triggers → make next call
+
+### Scheduled workflow
+
+1. Set timer for desired delay
+2. Timer triggers → execute workflow nodes
+
+## Integration with Workflow
+
+When used as a trigger node in a workflow:
+1. Deploy the workflow
+2. Timer countdown begins
+3. After duration, downstream nodes execute
+
+When used as AI tool:
+1. Agent decides to set timer
+2. Timer is scheduled
+3. Agent can proceed with other work
+4. Notification when timer triggers
+
+## Best Practices
+
+1. **Use appropriate units**: Don't use 3600 seconds when 1 hour is clearer
+2. **Consider time zones**: Timers use server time
+3. **Account for drift**: Long timers may have slight variance
+4. **Test short first**: Start with seconds before days
+5. **Chain timers carefully**: Avoid infinite loops
+
+## Limitations
+
+- Timers are not persistent across server restarts
+- Maximum practical delay depends on server uptime
+- Timers are one-time (use cron for recurring)
+
+## Setup Requirements
+
+1. Connect the **Timer** node to Zeenie's `input-tools` handle
+2. For workflow triggers, connect Timer as the first node
+3. Deploy workflow to activate timer

package/server/skills/travel_agent/geocoding-skill/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: geocoding-skill
+description: Convert addresses to coordinates (geocoding) or coordinates to addresses (reverse geocoding) using Google Maps API.
+allowed-tools: add_locations
+metadata:
+  author: machina
+  version: "1.0"
+  category: location
+  icon: "📍"
+  color: "#4285F4"
+---
+
+# Geocoding Tool
+
+Convert addresses to GPS coordinates or coordinates to addresses using Google Maps Geocoding API.
+
+## How It Works
+
+This skill provides instructions for the **Add Locations** (gmaps_locations) tool node. Connect the **Add Locations** node to Zeenie's `input-tools` handle to enable geocoding operations.
+
+## add_locations Tool
+
+Geocode addresses or reverse geocode coordinates.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| service_type | string | Yes | `"geocode"` (address to coordinates) or `"reverse_geocode"` (coordinates to address) |
+| address | string | If geocode | Address to convert to coordinates |
+| lat | float | If reverse_geocode | Latitude coordinate |
+| lng | float | If reverse_geocode | Longitude coordinate |
+
+### Operations
+
+| Service Type | Input | Output |
+|--------------|-------|--------|
+| `geocode` | Address string | Coordinates (lat, lng) |
+| `reverse_geocode` | Coordinates (lat, lng) | Formatted address |
+
+### Examples
+
+**Geocode an address:**
+```json
+{
+  "service_type": "geocode",
+  "address": "1600 Amphitheatre Parkway, Mountain View, CA"
+}
+```
+
+**Geocode a landmark:**
+```json
+{
+  "service_type": "geocode",
+  "address": "Eiffel Tower, Paris"
+}
+```
+
+**Geocode a city:**
+```json
+{
+  "service_type": "geocode",
+  "address": "New York City, USA"
+}
+```
+
+**Reverse geocode (coordinates to address):**
+```json
+{
+  "service_type": "reverse_geocode",
+  "lat": 48.8584,
+  "lng": 2.2945
+}
+```
+
+### Response Format
+
+**Geocode response:**
+```json
+{
+  "success": true,
+  "service_type": "geocoding",
+  "input": {"address": "Eiffel Tower, Paris"},
+  "results": [
+    {
+      "formatted_address": "Champ de Mars, 5 Av. Anatole France, 75007 Paris, France",
+      "geometry": {
+        "location": {"lat": 48.8583701, "lng": 2.2944813}
+      },
+      "address_components": [
+        {"long_name": "5", "short_name": "5", "types": ["street_number"]},
+        {"long_name": "Avenue Anatole France", "short_name": "Av. Anatole France", "types": ["route"]},
+        {"long_name": "Paris", "short_name": "Paris", "types": ["locality"]}
+      ]
+    }
+  ],
+  "status": "OK"
+}
+```
+
+**Reverse geocode response:**
+```json
+{
+  "success": true,
+  "service_type": "reverse_geocoding",
+  "input": {"lat": 48.8584, "lng": 2.2945},
+  "results": [
+    {
+      "formatted_address": "Champ de Mars, 5 Av. Anatole France, 75007 Paris, France",
+      "geometry": {
+        "location": {"lat": 48.8583701, "lng": 2.2944813}
+      },
+      "address_components": [...]
+    }
+  ],
+  "status": "OK"
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": "address is required for geocoding"
+}
+```
+
+```json
+{
+  "error": "Geocoding failed: ZERO_RESULTS"
+}
+```
+
+## Use Cases
+
+| Use Case | Service Type | Description |
+|----------|--------------|-------------|
+| Find location | geocode | Get coordinates for an address |
+| Validate address | geocode | Get standardized address format |
+| Get address | reverse_geocode | Find address from GPS coordinates |
+| Location lookup | geocode | Search for landmarks, POIs |
+
+## Common Workflows
+
+### Get coordinates for sending location via WhatsApp
+
+1. Use `geocode` to convert address to coordinates
+2. Extract `lat` and `lng` from response
+3. Use `whatsapp_send` with message_type="location"
+
+### Identify a GPS location
+
+1. Use `reverse_geocode` with lat/lng coordinates
+2. Get formatted address from response
+
+### Search for nearby places
+
+1. Use `geocode` to get coordinates from address
+2. Use `nearby_places` tool with those coordinates
+
+## Address Format Guidelines
+
+**Good address formats:**
+- `"123 Main Street, New York, NY 10001"`
+- `"Eiffel Tower, Paris, France"`
+- `"Times Square, NYC"`
+- `"Tokyo Station, Japan"`
+
+**Tips:**
+- Include city and country for better accuracy
+- Landmarks and POIs work well
+- Postal codes improve precision
+- Use local language or English
+
+## Coordinate Guidelines
+
+- Latitude range: -90 to 90
+- Longitude range: -180 to 180
+- More decimal places = higher precision
+- Standard precision: 6 decimal places
+
+## Setup Requirements
+
+1. Connect the **Add Locations** (gmaps_locations) node to Zeenie's `input-tools` handle
+2. Google Maps API key must be configured in Credentials
+3. Geocoding API must be enabled in Google Cloud Console

package/server/skills/travel_agent/nearby-places-skill/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: nearby-places-skill
+description: Search for nearby places like restaurants, cafes, stores, and services using Google Places API. Find places by type and location.
+allowed-tools: show_nearby_places
+metadata:
+  author: machina
+  version: "1.0"
+  category: location
+  icon: "🗺️"
+  color: "#34A853"
+---
+
+# Nearby Places Tool
+
+Search for places near a location using Google Places API.
+
+## How It Works
+
+This skill provides instructions for the **Show Nearby Places** (gmaps_nearby_places) tool node. Connect the **Show Nearby Places** node to Zeenie's `input-tools` handle to enable place search.
+
+## show_nearby_places Tool
+
+Search for places near GPS coordinates.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| lat | float | Yes | Center latitude for search |
+| lng | float | Yes | Center longitude for search |
+| radius | int | No | Search radius in meters (default: 500, max: 50000) |
+| type | string | No | Place type to search for (default: "restaurant") |
+| keyword | string | No | Keyword to filter results |
+
+### Place Types
+
+**Food & Drink:**
+- `restaurant` - Restaurants
+- `cafe` - Coffee shops
+- `bar` - Bars and pubs
+- `bakery` - Bakeries
+- `meal_takeaway` - Takeout restaurants
+
+**Shopping:**
+- `store` - General stores
+- `supermarket` - Grocery stores
+- `shopping_mall` - Shopping centers
+- `clothing_store` - Clothing shops
+- `convenience_store` - Convenience stores
+
+**Services:**
+- `bank` - Banks
+- `atm` - ATMs
+- `gas_station` - Gas/petrol stations
+- `pharmacy` - Pharmacies
+- `post_office` - Post offices
+
+**Health:**
+- `hospital` - Hospitals
+- `doctor` - Doctor's offices
+- `dentist` - Dental clinics
+
+**Transport:**
+- `bus_station` - Bus stations
+- `train_station` - Train stations
+- `airport` - Airports
+- `taxi_stand` - Taxi stands
+- `parking` - Parking lots
+
+**Entertainment:**
+- `movie_theater` - Cinemas
+- `gym` - Fitness centers
+- `park` - Parks
+- `museum` - Museums
+- `zoo` - Zoos
+
+**Accommodation:**
+- `hotel` - Hotels
+- `lodging` - All lodging types
+
+### Examples
+
+**Find nearby restaurants:**
+```json
+{
+  "lat": 40.7484,
+  "lng": -73.9857,
+  "radius": 500,
+  "type": "restaurant"
+}
+```
+
+**Find coffee shops:**
+```json
+{
+  "lat": 37.7749,
+  "lng": -122.4194,
+  "type": "cafe",
+  "radius": 1000
+}
+```
+
+**Find specific chain:**
+```json
+{
+  "lat": 37.7749,
+  "lng": -122.4194,
+  "type": "cafe",
+  "keyword": "starbucks"
+}
+```
+
+**Find gas stations:**
+```json
+{
+  "lat": 34.0522,
+  "lng": -118.2437,
+  "type": "gas_station",
+  "radius": 2000
+}
+```
+
+**Find hotels:**
+```json
+{
+  "lat": 51.5074,
+  "lng": -0.1278,
+  "type": "hotel",
+  "radius": 1000
+}
+```
+
+### Response Format
+
+```json
+{
+  "success": true,
+  "type": "restaurant",
+  "search_parameters": {
+    "location": {"lat": 40.7484, "lng": -73.9857},
+    "radius": 500,
+    "type": "restaurant"
+  },
+  "results": [
+    {
+      "name": "Example Restaurant",
+      "vicinity": "123 Main St, New York",
+      "rating": 4.5,
+      "user_ratings_total": 150,
+      "price_level": 2,
+      "geometry": {
+        "location": {"lat": 40.7485, "lng": -73.9860}
+      },
+      "types": ["restaurant", "food", "establishment"],
+      "opening_hours": {"open_now": true}
+    }
+  ],
+  "total_results": 10,
+  "status": "OK"
+}
+```
+
+### Response Fields
+
+| Field | Description |
+|-------|-------------|
+| name | Place name |
+| vicinity | Address or location description |
+| rating | Average rating (1-5) |
+| user_ratings_total | Number of reviews |
+| price_level | Price level (0-4, 0=free, 4=very expensive) |
+| geometry.location | Place coordinates |
+| types | Place type categories |
+| opening_hours.open_now | Whether currently open |
+
+### Error Response
+
+```json
+{
+  "error": "lat and lng are required for nearby places search"
+}
+```
+
+## Price Level Guide
+
+| Level | Meaning |
+|-------|---------|
+| 0 | Free |
+| 1 | Inexpensive ($) |
+| 2 | Moderate ($$) |
+| 3 | Expensive ($$$) |
+| 4 | Very Expensive ($$$$) |
+
+## Common Workflows
+
+### Find places near an address
+
+1. Use `geocoding` tool to convert address to coordinates
+2. Use `nearby_places` with the lat/lng from step 1
+
+### Find best-rated places
+
+1. Search with appropriate type and radius
+2. Sort results by rating in response
+3. Filter by minimum rating threshold
+
+### Find open places now
+
+1. Search with desired type
+2. Check `opening_hours.open_now` in results
+
+## Radius Guidelines
+
+| Radius | Use Case |
+|--------|----------|
+| 100-500m | Walking distance |
+| 500-1000m | Short walk |
+| 1000-2000m | 5-10 min walk |
+| 2000-5000m | Driving distance |
+| 5000-50000m | City-wide search |
+
+## Tips
+
+1. **Use specific types**: "cafe" not "coffee"
+2. **Add keywords**: Filter by chain name or cuisine
+3. **Adjust radius**: Start small, expand if needed
+4. **Check ratings**: Higher ratings usually mean better quality
+5. **Verify open_now**: Important for time-sensitive searches
+
+## Setup Requirements
+
+1. Connect the **Show Nearby Places** (gmaps_nearby_places) node to Zeenie's `input-tools` handle
+2. Google Maps API key must be configured in Credentials
+3. Places API must be enabled in Google Cloud Console