machinaos 0.0.1

package/docs-MachinaOs/nodes/whatsapp.mdx

@@ -0,0 +1,305 @@
+---
+title: WhatsApp Nodes
+description: Send, receive, and manage WhatsApp messages
+---
+
+# WhatsApp Nodes
+
+Automate WhatsApp messaging with three specialized nodes.
+
+## Available Nodes
+
+| Node | Type | Purpose |
+|------|------|---------|
+| WhatsApp Connect | Action | Check connection status |
+| WhatsApp Receive | Trigger | Wait for incoming messages |
+| WhatsApp Send | Action | Send messages |
+
+## Setup Requirements
+
+1. WhatsApp service running (included in Docker setup)
+2. WhatsApp account for pairing
+3. Scan QR code to link device
+
+### Connecting
+
+1. Click **Android/WhatsApp icon** in toolbar
+2. Scan displayed QR code with WhatsApp mobile app
+3. Go to WhatsApp > Settings > Linked Devices > Link a Device
+
+---
+
+## WhatsApp Receive
+
+Trigger node that fires when messages arrive.
+
+### Parameters
+
+<ParamField path="messageTypeFilter" type="select" default="all">
+  Filter by message type: all, text, image, video, audio, document, location, contact
+</ParamField>
+
+<ParamField path="filter" type="select" default="all">
+  Sender filter mode
+</ParamField>
+
+<ParamField path="phone_number" type="string">
+  Specific phone number (when filter = contact)
+</ParamField>
+
+<ParamField path="group_id" type="select">
+  Specific group (when filter = group)
+</ParamField>
+
+<ParamField path="keywords" type="string">
+  Comma-separated keywords (when filter = keywords)
+</ParamField>
+
+<ParamField path="forwardedFilter" type="select" default="all">
+  Forwarded message handling: all, only_forwarded, ignore_forwarded
+</ParamField>
+
+<ParamField path="ignoreOwnMessages" type="boolean" default="true">
+  Skip messages sent by yourself
+</ParamField>
+
+### Filter Options
+
+| Filter | Description |
+|--------|-------------|
+| All Messages | Receive everything |
+| From Any Contact | Non-group messages only |
+| From Specific Contact | Match phone number |
+| From Specific Group | Match group |
+| Contains Keywords | Match keywords in message |
+
+### Output
+
+```json
+{
+  "message_id": "ABC123",
+  "sender": "1234567890@s.whatsapp.net",
+  "sender_phone": "+1234567890",
+  "chat_id": "1234567890@s.whatsapp.net",
+  "message_type": "text",
+  "text": "Hello!",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "is_group": false,
+  "is_from_me": false,
+  "push_name": "John Doe",
+  "is_forwarded": false,
+  "forwarding_score": 0,
+  "group_info": null
+}
+```
+
+### Group Message Output
+
+When `is_group` is true:
+
+```json
+{
+  "group_info": {
+    "group_jid": "123456789@g.us",
+    "sender_jid": "1234567890@s.whatsapp.net",
+    "sender_phone": "+1234567890",
+    "sender_name": "John Doe"
+  }
+}
+```
+
+### Example: Reply to Specific Keywords
+
+```
+Filter: Contains Keywords
+Keywords: help, support, question
+```
+
+---
+
+## WhatsApp Send
+
+Send messages to contacts or groups.
+
+### Parameters
+
+<ParamField path="phone_number" type="string" required>
+  Recipient phone number with country code (e.g., +1234567890)
+</ParamField>
+
+<ParamField path="message" type="string" required>
+  Message content. Supports template variables.
+</ParamField>
+
+### Output
+
+```json
+{
+  "success": true,
+  "message_id": "XYZ789",
+  "timestamp": "2024-01-15T10:35:00Z"
+}
+```
+
+### Example: Auto-Reply
+
+```
+Phone Number: {{whatsappReceive.sender_phone}}
+Message: Thanks for your message! I'll get back to you soon.
+```
+
+### Example: Forward to Admin
+
+```
+Phone Number: +1987654321
+Message: New message from {{whatsappReceive.push_name}}: {{whatsappReceive.text}}
+```
+
+---
+
+## WhatsApp Connect
+
+Check WhatsApp connection status and device info.
+
+### Output
+
+```json
+{
+  "connected": true,
+  "device_id": "abc123",
+  "phone_number": "+1234567890",
+  "platform": "android",
+  "push_name": "My Business"
+}
+```
+
+### Use Case
+
+Check connection before sending:
+
+```
+[WhatsApp Connect] --> [Python Executor] --> [WhatsApp Send]
+                           (check status)
+```
+
+---
+
+## Common Workflows
+
+### Auto-Responder
+
+```
+[WhatsApp Receive] --> [OpenAI Chat] --> [WhatsApp Send]
+```
+
+**AI Prompt:**
+```
+Respond to this customer message: {{whatsappReceive.text}}
+Be helpful and professional.
+```
+
+**Send Config:**
+```
+Phone: {{whatsappReceive.sender_phone}}
+Message: {{openaiChatModel.response}}
+```
+
+### Group Monitor
+
+```
+[WhatsApp Receive] --> [Python Executor] --> [Webhook/Database]
+     (group filter)        (log message)
+```
+
+**Filter Config:**
+```
+Filter: From Specific Group
+Group: [Select your group]
+```
+
+### Keyword Bot
+
+```
+[WhatsApp Receive] --> [Python Executor] --> [WhatsApp Send]
+   (keywords: help)      (select response)
+```
+
+**Python Code:**
+```python
+text = input_data.get("text", "").lower()
+
+if "hours" in text:
+    response = "We're open 9am-5pm, Mon-Fri"
+elif "price" in text:
+    response = "Please visit our website for pricing"
+else:
+    response = "How can I help you?"
+
+output = {"response": response}
+```
+
+---
+
+## Tips
+
+<Tip>
+Use `{{whatsappReceive.sender_phone}}` to reply to the sender automatically.
+</Tip>
+
+<Tip>
+Combine with **Simple Memory** for context-aware conversations per contact.
+</Tip>
+
+<Tip>
+Set `Session ID: {{whatsappReceive.sender_phone}}` in Simple Memory for per-user history.
+</Tip>
+
+<Warning>
+Respect WhatsApp's terms of service. Don't send spam or bulk unsolicited messages.
+</Warning>
+
+---
+
+## Troubleshooting
+
+<Accordion title="QR code not appearing">
+  Check WhatsApp service status:
+  ```bash
+  docker-compose logs whatsapp
+  ```
+  Restart if needed:
+  ```bash
+  docker-compose restart whatsapp
+  ```
+</Accordion>
+
+<Accordion title="Messages not received">
+  - Verify workflow is **deployed** (not just saved)
+  - Check filter settings aren't too restrictive
+  - Confirm `ignoreOwnMessages` setting
+</Accordion>
+
+<Accordion title="Send fails">
+  - Include country code in phone number
+  - Check WhatsApp connection status
+  - Verify recipient hasn't blocked you
+</Accordion>
+
+<Accordion title="Connection drops frequently">
+  - Check internet connectivity
+  - Ensure phone stays online
+  - Don't use WhatsApp Web simultaneously
+</Accordion>
+
+---
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="WhatsApp Tutorial" icon="whatsapp" href="/tutorials/whatsapp-automation">
+    Step-by-step guide
+  </Card>
+  <Card title="AI Agent" icon="robot" href="/nodes/ai-agent">
+    Add AI-powered responses
+  </Card>
+</CardGroup>

package/docs-MachinaOs/quickstart.mdx

@@ -0,0 +1,119 @@
+---
+title: Quick Start
+description: Build your first workflow in 5 minutes
+---
+
+# Quick Start
+
+Let's create a simple workflow that responds to a webhook with an AI-generated message.
+
+## Step 1: Create a New Workflow
+
+1. Open MachinaOs at `http://localhost:3000`
+2. Click **File > New Workflow** or press `Ctrl+N`
+3. You'll see an empty canvas with a component palette on the left
+
+## Step 2: Add a Webhook Trigger
+
+1. In the component palette, expand **Utilities**
+2. Drag **Webhook Trigger** onto the canvas
+3. Click the node to select it, then click the **gear icon** to configure:
+
+```
+Path: hello
+Method: POST
+```
+
+<Tip>
+Your webhook will be available at `http://localhost:3010/webhook/hello`
+</Tip>
+
+## Step 3: Add an AI Chat Model
+
+1. Expand **AI Models** in the palette
+2. Drag **OpenAI Chat Model** onto the canvas
+3. Position it to the right of the Webhook Trigger
+4. Connect them by dragging from the Webhook's output handle to the AI model's input handle
+
+### Configure the AI Model
+
+Click the gear icon and set:
+
+```
+Model: gpt-4o-mini
+Temperature: 0.7
+```
+
+<Warning>
+You need an OpenAI API key. Click the **key icon** in the toolbar to add it.
+</Warning>
+
+## Step 4: Set the Prompt
+
+In the AI model's parameters, set the **Prompt**:
+
+```
+You are a friendly assistant. The user sent: {{webhookTrigger.body}}
+
+Respond with a helpful greeting.
+```
+
+<Info>
+The `{{webhookTrigger.body}}` syntax pulls data from the webhook's output.
+</Info>
+
+## Step 5: Add a Webhook Response
+
+1. Drag **Webhook Response** from Utilities
+2. Connect the AI model's output to the Webhook Response input
+3. Configure it:
+
+```
+Status Code: 200
+Body: {{openaiChatModel.response}}
+Content Type: application/json
+```
+
+## Step 6: Deploy and Test
+
+1. Click the **Deploy** button (purple) in the toolbar
+2. Your workflow is now listening for webhooks
+
+### Test with curl
+
+```bash
+curl -X POST http://localhost:3010/webhook/hello \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hello from curl!"}'
+```
+
+You should receive an AI-generated response!
+
+## Your First Workflow
+
+Your completed workflow looks like this:
+
+```
+[Webhook Trigger] --> [OpenAI Chat] --> [Webhook Response]
+```
+
+<Check>
+Congratulations! You've built your first MachinaOs workflow.
+</Check>
+
+## What's Next?
+
+<CardGroup cols={2}>
+  <Card title="AI Agent Tutorial" icon="robot" href="/tutorials/ai-agent-workflow">
+    Build an AI agent with memory and tools
+  </Card>
+  <Card title="WhatsApp Automation" icon="whatsapp" href="/tutorials/whatsapp-automation">
+    Automate WhatsApp messages
+  </Card>
+  <Card title="Node Catalog" icon="grid" href="/nodes/overview">
+    Explore all 34 nodes
+  </Card>
+  <Card title="Deployment" icon="server" href="/deployment/docker">
+    Deploy to production
+  </Card>
+</CardGroup>

package/docs-MachinaOs/tutorials/ai-agent-workflow.mdx

@@ -0,0 +1,177 @@
+---
+title: AI Agent Workflow
+description: Build an AI agent with conversation memory and tools
+---
+
+# AI Agent Workflow
+
+Create an intelligent AI agent that remembers conversation history and can use tools.
+
+## What You'll Build
+
+A chatbot that:
+- Maintains conversation context across messages
+- Uses an AI model (OpenAI, Claude, or Gemini)
+- Responds via webhook
+
+## Prerequisites
+
+- MachinaOs running locally
+- An AI provider API key (OpenAI, Anthropic, or Google)
+
+## Step 1: Add the AI Agent
+
+1. Drag **AI Agent** from the AI Agents category
+2. This is the core of your intelligent assistant
+
+The AI Agent node has multiple input handles:
+- **Main Input** (left) - Receives the user prompt
+- **Memory Input** (bottom-left diamond) - Connects to memory nodes
+- **Model Input** (top) - Optional model override
+
+## Step 2: Connect a Chat Model
+
+1. Drag **OpenAI Chat Model** (or Claude/Gemini) onto the canvas
+2. Connect it to the AI Agent's model input (top handle)
+3. Configure the model:
+
+```
+Model: gpt-4o
+Temperature: 0.7
+Max Tokens: 1000
+```
+
+<Tip>
+You can use any AI provider. Claude excels at reasoning, Gemini handles multimodal input.
+</Tip>
+
+## Step 3: Add Conversation Memory
+
+1. Drag **Simple Memory** from AI Agents
+2. Connect it to the AI Agent's memory input (bottom-left diamond handle)
+3. Configure:
+
+```
+Session ID: default
+Memory Type: Buffer
+```
+
+### Memory Types
+
+| Type | Description |
+|------|-------------|
+| Buffer | Keeps all messages in the session |
+| Window | Keeps only the last N messages |
+
+<Info>
+Memory is stored in SQLite and persists across server restarts.
+</Info>
+
+## Step 4: Add a Webhook Trigger
+
+1. Drag **Webhook Trigger** from Utilities
+2. Connect its output to the AI Agent's main input
+3. Configure:
+
+```
+Path: chat
+Method: POST
+```
+
+## Step 5: Add a Webhook Response
+
+1. Drag **Webhook Response** from Utilities
+2. Connect the AI Agent's output to Webhook Response
+3. Configure:
+
+```
+Status Code: 200
+Body: {{aiAgent.response}}
+Content Type: application/json
+```
+
+## Complete Workflow
+
+```
+[Webhook Trigger] --> [AI Agent] --> [Webhook Response]
+                         ^
+                         |
+               [Simple Memory]
+                         ^
+                         |
+               [OpenAI Chat Model]
+```
+
+## Step 6: Configure the Agent Prompt
+
+Click on the AI Agent and set the system prompt:
+
+```
+You are a helpful assistant. You remember our conversation history.
+Be concise and friendly in your responses.
+```
+
+## Step 7: Deploy and Test
+
+1. Click **Deploy**
+2. Test with curl:
+
+```bash
+# First message
+curl -X POST http://localhost:3010/webhook/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hi, my name is Alex"}'
+
+# Second message (agent remembers your name)
+curl -X POST http://localhost:3010/webhook/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "What is my name?"}'
+```
+
+The agent should respond with your name, demonstrating memory!
+
+## Advanced: Multiple Sessions
+
+Use different session IDs for different conversations:
+
+```
+Session ID: {{webhookTrigger.body.user_id}}
+```
+
+This creates separate memory for each user.
+
+## Advanced: Window Memory
+
+For long conversations, use Window mode to limit memory:
+
+```
+Memory Type: Window
+Window Size: 10
+```
+
+This keeps only the last 10 message exchanges.
+
+## Troubleshooting
+
+<Accordion title="Agent doesn't remember previous messages">
+  - Ensure Simple Memory is connected to the memory input (diamond handle)
+  - Check that Session ID is consistent between requests
+  - Memory is saved after each exchange automatically
+</Accordion>
+
+<Accordion title="API key not found">
+  - Click the key icon in the toolbar
+  - Add your API key for the provider you're using
+  - Keys are stored securely and encrypted
+</Accordion>
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="WhatsApp Automation" icon="whatsapp" href="/tutorials/whatsapp-automation">
+    Connect your agent to WhatsApp
+  </Card>
+  <Card title="AI Models Reference" icon="brain" href="/nodes/ai-models">
+    Compare AI providers
+  </Card>
+</CardGroup>