VIRA - The Intelligent Web Automation Agent

VIRA (Versatile Intelligent Robotic Automator) is not just a browser automation tool—it's an intelligent agent that understands natural language goals and autonomously decides how to achieve them.

🌟 What Makes VIRA "Magical"?

1. Natural Language Goals

Traditional automation (BAD):

{
  "tasks": [
    {"action": "goto", "value": "https://amazon.com"},
    {"action": "wait", "selector": "#twotabsearchtextbox"},
    {"action": "type", "selector": "#twotabsearchtextbox", "value": "wireless mouse"},
    {"action": "click", "selector": "#nav-search-submit-button"},
    {"action": "wait", "selector": ".s-result-item"},
    {"action": "scrape_text", "selector": ".a-price-whole"}
  ]
}

VIRA (EXCELLENT):

const goal = {
  description: "Go to Amazon, search for 'wireless mouse', and get the prices of the first 5 results"
};

const result = await vira.execute(goal);

2. LLM-Powered Intelligence

VIRA uses a Large Language Model to:

• Understand your intent
• Analyze the current page's HTML structure
• Generate the optimal automation plan
• Adapt when things go wrong

3. Self-Healing Capabilities

When a selector breaks (because the website changed), VIRA doesn't just fail—it heals itself:

❌ Selector #old-button not found
🔄 VIRA analyzing page...
✅ Found alternative: button[aria-label="Login"]
✅ Continuing execution...

4. Configurable LLM Provider

Choose your LLM based on your needs:

| Provider | Use Case | Privacy | Cost | |----------|----------|---------|------| | OpenAI (GPT-4) | Maximum accuracy for complex tasks | ❌ Cloud | 💰💰 | | Anthropic (Claude) | Balanced performance | ❌ Cloud | 💰💰 | | Ollama (Local) | Privacy-first, unlimited usage | ✅ Local | 🆓 Free | | Custom Endpoint | Your own LLM infrastructure | ✅ Your choice | Your choice |

🚀 Quick Start

Installation

npm install n8n-nodes-vira

Basic Usage

import { ViraAgent } from 'n8n-nodes-vira';

// Configure your LLM
const llmConfig = {
  provider: 'ollama',  // Free & private!
  model: 'llama2',
  baseUrl: 'http://localhost:11434'
};

// Create VIRA instance
const vira = new ViraAgent(llmConfig, {
  headless: true
}, {
  enableSelfHealing: true,
  maxRetries: 3,
  verbose: true
});

// Define your goal in natural language
const goal = {
  description: "Go to example.com and extract the main heading text"
};

// Execute and let VIRA figure out the rest
const result = await vira.execute(goal);

console.log('Goal achieved:', result.goalAchieved);
console.log('Data extracted:', result.data);

🔧 Configuration

LLM Providers

OpenAI (GPT-4/GPT-4 Turbo)

const llmConfig = {
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4',  // or 'gpt-4-turbo', 'gpt-3.5-turbo'
  temperature: 0.7,
  maxTokens: 4096
};

Anthropic (Claude 3/3.5)

const llmConfig = {
  provider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-5-sonnet-20241022',  // or claude-3-opus, claude-3-sonnet
  temperature: 0.7,
  maxTokens: 4096
};

Ollama (Local LLM - Recommended for Privacy)

const llmConfig = {
  provider: 'ollama',
  model: 'llama2',  // or mistral, codellama, etc.
  baseUrl: 'http://localhost:11434'
};

First install Ollama: https://ollama.ai/

# Pull a model
ollama pull llama2

# Start Ollama server (runs automatically after install)
ollama serve

Custom Endpoint

const llmConfig = {
  provider: 'custom',
  apiKey: 'your-custom-key',
  model: 'your-model',
  baseUrl: 'https://your-llm-endpoint.com'
};

Engine Configuration

const engineConfig = {
  headless: true,           // Run in headless mode
  timeout: 30000,           // Default timeout (ms)
  screenshotOnError: true,  // Take screenshots on failure
  sessionName: 'my-session',
  saveSession: false,       // Save cookies
  loadSession: false        // Load cookies
};

VIRA Configuration

const viraConfig = {
  enableSelfHealing: true,    // Enable automatic recovery
  maxRetries: 3,              // Max retry attempts
  verbose: true,              // Detailed logging
  confidenceThreshold: 0.7    // Minimum confidence to accept plan
};

📖 Examples

Example 1: Web Scraping

const goal = {
  description: "Go to news.ycombinator.com and get the titles of the top 5 stories",
  startUrl: "https://news.ycombinator.com"
};

const result = await vira.execute(goal);
console.log('Top stories:', result.data);

Example 2: Form Automation

const goal = {
  description: "Go to the contact form, fill it with name 'John Doe', email '[email protected]', message 'Hello!', and submit",
  startUrl: "https://example.com/contact",
  context: "The form has standard fields for name, email, and message"
};

const result = await vira.execute(goal);

Example 3: Login Flow

const goal = {
  description: "Log in to the site using username '[email protected]' and password 'secret123'",
  startUrl: "https://example.com/login"
};

const result = await vira.execute(goal);

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│                 VIRA AGENT                      │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────────┐      ┌──────────────┐       │
│  │   Natural    │      │     LLM      │       │
│  │   Language   │─────▶│   Provider   │       │
│  │   Goal       │      │   (Config)   │       │
│  └──────────────┘      └──────────────┘       │
│         │                      │               │
│         ▼                      ▼               │
│  ┌──────────────┐      ┌──────────────┐       │
│  │     Plan     │      │   OpenAI /   │       │
│  │  Generator   │◀─────│  Anthropic / │       │
│  │              │      │   Ollama     │       │
│  └──────────────┘      └──────────────┘       │
│         │                                      │
│         ▼                                      │
│  ┌──────────────┐                             │
│  │  Executable  │                             │
│  │    Tasks     │                             │
│  └──────────────┘                             │
│         │                                      │
│         ▼                                      │
│  ┌──────────────┐      ┌──────────────┐       │
│  │  Automation  │─────▶│   Selector   │       │
│  │    Engine    │      │    Healer    │       │
│  │  (Playwright)│◀─────│ (Self-Heal)  │       │
│  └──────────────┘      └──────────────┘       │
│         │                                      │
│         ▼                                      │
│  ┌──────────────┐                             │
│  │   Results +  │                             │
│  │  Extracted   │                             │
│  │     Data     │                             │
│  └──────────────┘                             │
└─────────────────────────────────────────────────┘

🧪 Testing

VIRA maintains 100% test stability:

npm test

# Output:
# ✓ 29/29 tests passing
# ✓ Execution time: ~25 seconds
# ✓ Zero flaky tests

🔐 Privacy & Security

Why Use Local LLMs (Ollama)?

1. Complete Privacy: Your automation goals and page HTML never leave your machine
2. No API Costs: Unlimited usage, zero ongoing costs
3. No Rate Limits: Run as many automations as you want
4. Offline Capable: Works without internet (after model download)

Perfect for:

• Scraping internal/private websites
• Handling sensitive data
• High-volume automation
• Air-gapped environments

🆚 VIRA vs Traditional Automation

| Feature | Traditional Tools | VIRA | |---------|------------------|------| | Input Format | JSON with selectors | Natural language | | Selector Management | Manual updates when site changes | Automatic self-healing | | Intelligence | Rule-based | LLM-powered reasoning | | Adaptability | Breaks on changes | Adapts and recovers | | Learning Curve | Steep (CSS selectors, DOM) | Gentle (natural language) | | Maintenance | Constant updates needed | Self-maintaining |

📦 Use with n8n (Coming Soon)

VIRA will be available as an n8n community node, allowing you to integrate intelligent web automation directly into your workflows.

[Trigger] ─▶ [VIRA Node] ─▶ [Process Data] ─▶ [Send Email]

🤝 Contributing

We welcome contributions! Areas of focus:

• Additional LLM providers
• Enhanced self-healing strategies
• More sophisticated plan generation
• n8n node development

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

• Built on Playwright for browser automation
• Inspired by the vision of truly intelligent agents
• Designed for accessibility, flexibility, and power

VIRA: From "simple automation" to "intelligent agent" 🚀✨