machinaos 0.0.12 → 0.0.13

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

package/server/skills/web_agent/http-request-skill/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: http-request-skill
+description: Make HTTP requests to external APIs and web services. Supports GET, POST, PUT, DELETE, PATCH methods with headers and JSON body.
+allowed-tools: http_request
+metadata:
+  author: machina
+  version: "1.0"
+  category: integration
+  icon: "🌐"
+  color: "#EF4444"
+---
+
+# HTTP Request Tool
+
+Make HTTP requests to external APIs and web services.
+
+## How It Works
+
+This skill provides instructions for the **HTTP Request** tool node. Connect the **HTTP Request** node to Zeenie's `input-tools` handle to enable API calls.
+
+## http_request Tool
+
+Make an HTTP request to any URL.
+
+### Schema Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| url | string | Yes | Full URL to request (e.g., `https://api.example.com/data`) |
+| method | string | No | HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH` (default: `GET`) |
+| body | object | No | Request body as JSON object (for POST/PUT/PATCH) |
+
+### Node Parameters
+
+Additional options can be configured on the node:
+
+| Parameter | Description |
+|-----------|-------------|
+| headers | Custom headers as JSON (e.g., `{"Authorization": "Bearer token"}`) |
+| base_url | Base URL prepended to the url parameter |
+
+### Response Format
+
+```json
+{
+  "status": 200,
+  "data": { "key": "value" },
+  "url": "https://api.example.com/data",
+  "method": "GET"
+}
+```
+
+### Examples
+
+**GET request (fetch data):**
+```json
+{
+  "url": "https://api.example.com/users/123",
+  "method": "GET"
+}
+```
+
+**POST request (create resource):**
+```json
+{
+  "url": "https://api.example.com/users",
+  "method": "POST",
+  "body": {
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+**PUT request (update resource):**
+```json
+{
+  "url": "https://api.example.com/users/123",
+  "method": "PUT",
+  "body": {
+    "name": "John Updated"
+  }
+}
+```
+
+**DELETE request:**
+```json
+{
+  "url": "https://api.example.com/users/123",
+  "method": "DELETE"
+}
+```
+
+**PATCH request (partial update):**
+```json
+{
+  "url": "https://api.example.com/users/123",
+  "method": "PATCH",
+  "body": {
+    "status": "active"
+  }
+}
+```
+
+### Real-World Examples
+
+**Get Bitcoin price:**
+```json
+{
+  "url": "https://api.coindesk.com/v1/bpi/currentprice.json",
+  "method": "GET"
+}
+```
+
+**Get weather:**
+```json
+{
+  "url": "https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_KEY",
+  "method": "GET"
+}
+```
+
+**Post to webhook:**
+```json
+{
+  "url": "https://hooks.slack.com/services/xxx",
+  "method": "POST",
+  "body": {
+    "text": "Hello from MachinaOS!"
+  }
+}
+```
+
+**Check website status:**
+```json
+{
+  "url": "https://example.com",
+  "method": "GET"
+}
+```
+
+### Error Responses
+
+**Timeout:**
+```json
+{
+  "error": "Request timed out"
+}
+```
+
+**Connection failed:**
+```json
+{
+  "error": "Connection failed: Unable to reach host"
+}
+```
+
+**HTTP error:**
+```json
+{
+  "status": 404,
+  "data": "Not Found",
+  "url": "https://api.example.com/missing",
+  "method": "GET"
+}
+```
+
+## HTTP Status Codes
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| 200-299 | Success | Process the response data |
+| 400 | Bad Request | Check request parameters |
+| 401 | Unauthorized | Check API key/authentication |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Check URL path |
+| 429 | Too Many Requests | Rate limited, wait and retry |
+| 500-599 | Server Error | External service issue |
+
+## Use Cases
+
+| Use Case | Method | Description |
+|----------|--------|-------------|
+| Fetch data | GET | Retrieve resources |
+| Create resource | POST | Add new data |
+| Update resource | PUT/PATCH | Modify existing data |
+| Delete resource | DELETE | Remove data |
+| Health check | GET | Verify service availability |
+| Webhook trigger | POST | Send events to services |
+
+## Guidelines
+
+1. **URLs**: Must be fully qualified with protocol (https://)
+2. **Authentication**: Use node headers for API keys/tokens
+3. **Timeout**: Default 30 seconds
+4. **JSON body**: Automatically serialized for POST/PUT/PATCH
+5. **Response**: JSON responses are automatically parsed
+
+## Security Notes
+
+1. Never expose API keys in responses to users
+2. Validate URLs before making requests
+3. Avoid internal/private network addresses (localhost, 192.168.x.x)
+4. Respect rate limits of external services
+5. Don't store sensitive data from API responses
+
+## Setup Requirements
+
+1. Connect the **HTTP Request** node to Zeenie's `input-tools` handle
+2. Configure authentication headers on the node if needed
+3. Ensure network access to target APIs

package/server/skills/android/skill/SKILL.md

@@ -1,84 +0,0 @@
----
-name: android-skill
-description: Control Android devices - battery, wifi, bluetooth, apps, location, camera, and sensors. Use when user wants to interact with their Android phone or tablet.
-metadata:
-  author: machina
-  version: "2.0"
-  category: device
-  icon: "📱"
-  color: "#3DDC84"
----
-
-# Android Device Control
-
-This skill provides context for monitoring and controlling Android devices.
-
-## How It Works
-
-This skill provides instructions and context. To execute Android actions, connect the **Android Toolkit** node to the Zeenie's `input-tools` handle, then connect Android service nodes to the toolkit:
-
-```
-[Battery Monitor] --+
-                    |
-[WiFi Automation] --+--> [Android Toolkit] --> [Zeenie]
-                    |
-[Location]       ---+
-```
-
-## Available Android Service Nodes
-
-Connect these to the Android Toolkit:
-
-| Node | Capabilities |
-|------|-------------|
-| **Battery Monitor** | Battery level, charging status, health, temperature |
-| **WiFi Automation** | Enable/disable WiFi, scan networks, get status |
-| **Bluetooth Automation** | Enable/disable Bluetooth, paired devices |
-| **App Launcher** | Launch applications by package name |
-| **App List** | List installed applications |
-| **Location** | Get current GPS coordinates |
-| **Audio Automation** | Volume control, mute/unmute |
-| **Screen Control** | Brightness, wake/sleep screen |
-| **Camera Control** | Camera info, capture photos |
-| **Motion Detection** | Accelerometer, gyroscope data |
-| **Environmental Sensors** | Temperature, humidity, pressure |
-
-## Example Interactions
-
-**User**: "What's my phone's battery level?"
-- Use the Battery Monitor service with action "status"
-
-**User**: "Turn off WiFi"
-- Use the WiFi Automation service with action "disable"
-
-**User**: "What apps are installed?"
-- Use the App List service with action "list"
-
-**User**: "Open Chrome"
-- Use the App Launcher service with action "launch", package_name "com.android.chrome"
-
-**User**: "Where is my phone?"
-- Use the Location service with action "current"
-
-**User**: "Set volume to 50%"
-- Use the Audio Automation service with action "set_volume", volume 50
-
-## Device Connection
-
-Before using Android tools, ensure:
-1. Device is connected via ADB (USB) or remote WebSocket
-2. Android Device Setup node shows connected status (green indicator)
-3. Required permissions are granted on the device
-
-## Error Handling
-
-- If device is not connected, inform user to check connection
-- If permission is denied, suggest enabling it in device settings
-- If action fails, provide the error message and suggest alternatives
-
-## Setup Requirements
-
-1. Connect this skill to Zeenie's `input-skill` handle
-2. Add **Android Toolkit** node and connect to Zeenie's `input-tools` handle
-3. Connect desired Android service nodes to the Android Toolkit
-4. Ensure Android device is paired (green status indicator)