machinaos 0.0.1

package/docs-MachinaOs/nodes/ai-agent.mdx

@@ -0,0 +1,216 @@
+---
+title: AI Agent & Memory
+description: Build intelligent agents with conversation memory
+---
+
+# AI Agent & Memory
+
+Create AI agents that remember context and can reason through complex tasks.
+
+## AI Agent Node
+
+The AI Agent is a powerful node that combines an AI model with memory and optional tools for complex reasoning tasks.
+
+### Input Handles
+
+| Handle | Position | Purpose |
+|--------|----------|---------|
+| Main Input | Left | User prompt/data |
+| Memory | Bottom-left (diamond) | Connect Simple Memory |
+| Model | Top (diamond) | Optional model override |
+
+### Parameters
+
+<ParamField path="systemPrompt" type="string">
+  Instructions that define the agent's behavior and personality
+</ParamField>
+
+<ParamField path="prompt" type="string" required>
+  The user message. Supports template variables.
+</ParamField>
+
+<ParamField path="maxIterations" type="number" default="5">
+  Maximum reasoning iterations for complex tasks
+</ParamField>
+
+### Output
+
+```json
+{
+  "response": "The agent's final response",
+  "iterations": 2,
+  "reasoning": ["Step 1 thought", "Step 2 thought"]
+}
+```
+
+### Example Configuration
+
+```
+System Prompt: You are a helpful customer service agent for TechCorp.
+              Answer questions about our products and services.
+              Be professional and concise.
+
+Prompt: {{webhookTrigger.body.question}}
+Max Iterations: 3
+```
+
+## Simple Memory Node
+
+Stores conversation history for AI agents, enabling context-aware responses.
+
+### Parameters
+
+<ParamField path="sessionId" type="string" default="default">
+  Unique identifier for the conversation session
+</ParamField>
+
+<ParamField path="memoryType" type="select" default="buffer">
+  Memory storage mode
+</ParamField>
+
+<ParamField path="windowSize" type="number" default="10">
+  Number of messages to keep (Window mode only)
+</ParamField>
+
+### Memory Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| Buffer | Keeps all messages | Short conversations |
+| Window | Keeps last N messages | Long conversations |
+
+### Connection
+
+Simple Memory connects to the AI Agent's **memory handle** (diamond shape on bottom-left):
+
+```
+[Simple Memory] ---(diamond)---> [AI Agent]
+```
+
+<Warning>
+Connect to the diamond handle, not the main input. The main input is for data flow.
+</Warning>
+
+### Session Management
+
+Use dynamic session IDs for multi-user scenarios:
+
+```
+Session ID: {{webhookTrigger.body.user_id}}
+```
+
+This creates separate memory for each user.
+
+### Output
+
+Simple Memory is a **config node** - it doesn't produce output. The AI Agent reads its configuration directly.
+
+## Building an Agent Workflow
+
+### Basic Setup
+
+```
+[Webhook Trigger] --> [AI Agent] --> [Webhook Response]
+                          ^
+                          |
+                   [Simple Memory]
+                          ^
+                          |
+                   [OpenAI Chat]
+```
+
+### Step-by-Step
+
+1. **Add AI Agent** from AI Agents category
+2. **Add Simple Memory** and connect to memory handle
+3. **Add AI Model** and connect to model handle (optional)
+4. **Add Trigger** (Webhook, WhatsApp, etc.) connected to main input
+5. **Add Response** node connected to agent output
+
+## Multi-Turn Conversation Example
+
+### First Request
+```bash
+curl -X POST http://localhost:3010/webhook/chat \
+  -d '{"user_id": "user123", "message": "My name is Alex"}'
+```
+
+Response: "Nice to meet you, Alex! How can I help you today?"
+
+### Second Request
+```bash
+curl -X POST http://localhost:3010/webhook/chat \
+  -d '{"user_id": "user123", "message": "What is my name?"}'
+```
+
+Response: "Your name is Alex, as you told me earlier."
+
+## Memory Persistence
+
+- Memory is stored in **SQLite** database
+- Survives server restarts
+- Managed automatically by the AI Agent
+
+### Clearing Memory
+
+To clear a session's memory, delete the session from the database or create a new session ID.
+
+## Advanced: Window Mode
+
+For long-running conversations, use Window mode to limit memory:
+
+```
+Memory Type: Window
+Window Size: 10
+```
+
+This keeps only the last 10 message pairs, preventing context overflow.
+
+## Tips
+
+<Tip>
+Use descriptive **system prompts** to define agent behavior clearly.
+</Tip>
+
+<Tip>
+Set **Max Iterations** based on task complexity. Simple Q&A: 1-2, Complex reasoning: 3-5.
+</Tip>
+
+<Tip>
+Use unique **Session IDs** per user/conversation for proper isolation.
+</Tip>
+
+<Warning>
+Long conversations with Buffer mode can exceed model context limits. Use Window mode for production.
+</Warning>
+
+## Troubleshooting
+
+<Accordion title="Agent doesn't remember previous messages">
+  - Verify Simple Memory is connected to diamond handle (not main input)
+  - Check Session ID is consistent across requests
+  - Ensure workflow is deployed (not just saved)
+</Accordion>
+
+<Accordion title="Agent gives inconsistent responses">
+  - Check if Session ID changes between requests
+  - Verify memory type and window size settings
+  - Review system prompt for clarity
+</Accordion>
+
+<Accordion title="Memory grows too large">
+  - Switch to Window mode
+  - Set appropriate window size (10-20 messages)
+  - Consider clearing sessions periodically
+</Accordion>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="AI Models" icon="brain" href="/nodes/ai-models">
+    Available chat models
+  </Card>
+  <Card title="AI Tutorial" icon="graduation-cap" href="/tutorials/ai-agent-workflow">
+    Step-by-step agent tutorial
+  </Card>
+</CardGroup>

package/docs-MachinaOs/nodes/ai-models.mdx

@@ -0,0 +1,240 @@
+---
+title: AI Chat Models
+description: OpenAI, Anthropic Claude, and Google Gemini integration
+---
+
+# AI Chat Models
+
+MachinaOs supports three major AI providers for chat completions.
+
+## Available Models
+
+Models are fetched dynamically from each provider's API when you add your API key.
+
+### OpenAI
+| Model | Best For |
+|-------|----------|
+| gpt-5.2 | Most capable, professional tasks |
+| gpt-5 | Advanced reasoning, multimodal |
+| o3 | Complex reasoning |
+| o4-mini | Fast, cost-efficient reasoning |
+
+### Anthropic Claude
+| Model | Best For |
+|-------|----------|
+| claude-opus-4.5 | Best for coding and agents |
+| claude-sonnet-4.5 | Balanced performance |
+| claude-haiku-4.5 | Fast responses |
+
+### Google Gemini
+| Model | Best For |
+|-------|----------|
+| gemini-3-pro | Most intelligent, complex tasks |
+| gemini-3-flash | Fast, frontier performance |
+| gemini-2.5-pro | Long context, multimodal |
+
+## Adding API Keys
+
+1. Click the **key icon** in the toolbar
+2. Select the provider
+3. Enter your API key
+4. Click **Validate** to test
+
+<Info>
+API keys are encrypted and stored locally. They're never sent to MachinaOs servers.
+</Info>
+
+## OpenAI Chat Model
+
+### Parameters
+
+<ParamField path="model" type="select" required>
+  The model to use (gpt-5.2, gpt-5, o3, o4-mini)
+</ParamField>
+
+<ParamField path="prompt" type="string" required>
+  The message to send. Supports template variables.
+</ParamField>
+
+<ParamField path="temperature" type="slider" default="0.7">
+  Randomness (0 = deterministic, 1 = creative)
+</ParamField>
+
+<ParamField path="maxTokens" type="number" default="1000">
+  Maximum response length
+</ParamField>
+
+<ParamField path="responseFormat" type="select" default="text">
+  Output format: text or json_object
+</ParamField>
+
+### Output
+
+```json
+{
+  "response": "The AI's response text",
+  "model": "gpt-5.2",
+  "usage": {
+    "prompt_tokens": 50,
+    "completion_tokens": 100,
+    "total_tokens": 150
+  }
+}
+```
+
+### Example
+
+```
+Prompt: Summarize this in 2 sentences: {{webhookTrigger.body.text}}
+Temperature: 0.3
+Max Tokens: 200
+```
+
+## Anthropic Claude Model
+
+### Parameters
+
+<ParamField path="model" type="select" required>
+  Claude model (claude-opus-4.5, claude-sonnet-4.5, claude-haiku-4.5)
+</ParamField>
+
+<ParamField path="prompt" type="string" required>
+  The message to send
+</ParamField>
+
+<ParamField path="systemPrompt" type="string">
+  System instructions for the model
+</ParamField>
+
+<ParamField path="temperature" type="slider" default="0.7">
+  Randomness (0-1)
+</ParamField>
+
+<ParamField path="maxTokens" type="number" default="1000">
+  Maximum response length
+</ParamField>
+
+### Output
+
+```json
+{
+  "response": "Claude's response",
+  "model": "claude-sonnet-4.5",
+  "stop_reason": "end_turn"
+}
+```
+
+### Example
+
+```
+System Prompt: You are a helpful coding assistant.
+Prompt: Explain this error: {{webhookTrigger.body.error}}
+```
+
+## Google Gemini Model
+
+### Parameters
+
+<ParamField path="model" type="select" required>
+  Gemini model (gemini-3-pro, gemini-3-flash, gemini-2.5-pro)
+</ParamField>
+
+<ParamField path="prompt" type="string" required>
+  The message to send
+</ParamField>
+
+<ParamField path="temperature" type="slider" default="0.7">
+  Randomness (0-1)
+</ParamField>
+
+<ParamField path="maxTokens" type="number" default="1000">
+  Maximum response length
+</ParamField>
+
+<ParamField path="safetySettings" type="select" default="default">
+  Content safety level
+</ParamField>
+
+### Output
+
+```json
+{
+  "response": "Gemini's response",
+  "model": "gemini-3-pro"
+}
+```
+
+## Comparing Providers
+
+| Feature | OpenAI | Claude | Gemini |
+|---------|--------|--------|--------|
+| Speed | Fast | Medium | Fast |
+| Reasoning | Good | Excellent | Good |
+| Context Window | 128K | 200K | 1M |
+| Multimodal | Yes | Yes | Yes |
+| JSON Mode | Yes | No | No |
+
+## Common Use Cases
+
+### Text Generation
+```
+Prompt: Write a product description for: {{input.product_name}}
+Temperature: 0.8
+```
+
+### Data Extraction
+```
+Prompt: Extract the email and phone from: {{input.text}}
+Response Format: json_object
+Temperature: 0
+```
+
+### Translation
+```
+Prompt: Translate to Spanish: {{input.text}}
+Temperature: 0.3
+```
+
+### Summarization
+```
+Prompt: Summarize in 3 bullet points: {{input.article}}
+Temperature: 0.3
+Max Tokens: 200
+```
+
+## Tips
+
+<Tip>
+Use **temperature 0** for deterministic outputs like data extraction.
+</Tip>
+
+<Tip>
+Use **temperature 0.7-0.9** for creative writing tasks.
+</Tip>
+
+<Tip>
+Enable **JSON mode** (OpenAI) when you need structured output.
+</Tip>
+
+<Warning>
+API calls cost money. Monitor your usage in your provider's dashboard.
+</Warning>
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| 401 Unauthorized | Invalid API key | Check/update API key |
+| 429 Rate Limited | Too many requests | Add delay, reduce frequency |
+| 500 Server Error | Provider issue | Retry later |
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="AI Agent" icon="robot" href="/nodes/ai-agent">
+    Use models with memory and tools
+  </Card>
+  <Card title="AI Tutorial" icon="graduation-cap" href="/tutorials/ai-agent-workflow">
+    Build an AI-powered workflow
+  </Card>
+</CardGroup>