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 'john@example.com', 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 'user@example.com' 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" 🚀✨