🚀 OXORAY

Agentic OS for LinkedIn Automation & Autonomous B2B Lead Generation

Describe your product. Define your target market. The AI finds the leads for you.

OXORAY is a self-hosted, open-source LinkedIn automation engine for B2B lead generation. Unlike traditional scraping tools or manual sequences, you do not need a pre-built list of profiles to contact. You simply describe your product and your target market. The system autonomously discovers, qualifies, and contacts the right prospects on your behalf.

How it works:

1. Provide Objective: Submit your product description and campaign target (e.g., "SaaS analytics platform targeting VP of Engineering at Series B startups").
2. Autonomous Discovery: The embedded LLM generates optimal LinkedIn search queries to discover raw candidate profiles.
3. Active Learning (Explore/Exploit): A Bayesian ML model (Gaussian Process Regressor on profile embeddings) learns your specific ideal customer profile. It dynamically balances exploring new profile types vs. exploiting known high-value prospects.
4. LLM Qualification: Selected profiles are passed to an LLM for hard qualification. The Bayesian model learns from every LLM decision, making candidate selection progressively smarter.
5. Agentic Engagement: Qualified leads receive highly personalized connection requests. Once connected, an autonomous AI agent manages multi-turn follow-up conversations.

---

🏗️ System Architecture & Flowchart

OXORAY operates as a stateful, autonomous engine. It leverages Bayesian Active Learning, Large Language Models, and stealth browser automation to source, qualify, and engage with leads automatically.

graph TD
    User([User / Operator]) -->|Configures Campaign| CLI[CLI Tool]
    User -->|Views CRM Dashboard| Frontend[Next.js Frontend]
    
    CLI --> CRM[(Django CRM Database)]
    Frontend --> CRM
    
    subgraph OXORAY Engine
        Engine[Task Engine Worker]
        Pipeline[ML Qualification Pipeline]
        Browser[Playwright Browser Automation]
        Agent[ReAct Follow-up Agent]
        
        Engine -->|Schedules Tasks| Pipeline
        Engine -->|Schedules Tasks| Agent
        
        Pipeline -->|1. Navigate & Scrape| Browser
        Pipeline -->|2. Score Embeddings| ML_Model[Gaussian Process Regressor]
        Pipeline -->|3. Qualify Candidates| LLM[LLM API]
        
        Agent -->|Reads Chat History| CRM
        Agent -->|Drafts Responses| LLM
        Agent -->|Sends Messages| Browser
        
        Browser <-->|Interacts| LinkedIn[(LinkedIn)]
    end
    
    Pipeline -->|Updates Profile State| CRM
    Browser -->|Stores Messages| CRM

Loading

---

✨ Key Features

Feature	Description
🧠 Autonomous Lead Discovery	No contact lists needed. AI generates targeted search queries natively on LinkedIn.
🎯 Bayesian Active Learning	Gaussian Process model on profile embeddings learns your ideal customer via an explore/exploit loop.
🤖 Stealth Browser Automation	Playwright + specialized stealth plugins mimic real user behavior to remain undetectable.
🛡️ Voyager API Scraping	Leverages LinkedIn's internal Voyager API for pristine, structured profile data without brittle HTML scraping.
🔄 Stateful Pipeline	Profiles transition through defined states (QUALIFIED → READY_TO_CONNECT → PENDING → CONNECTED → COMPLETED).
⏱️ Smart Rate Limiting	Configurable daily and weekly limits per action type automatically prevent account restrictions.
💾 Self-Hosted CRM	Full data ownership. Built-in Django web interface allows you to natively browse Leads, Deals, and Conversations.
🐳 One-Command Setup	Fully dockerized deployment with an interactive onboarding wizard and real-time engine stream viewer.
✍️ Agentic Follow-ups	A ReAct AI agent reads chat history, decides when to respond, drafts messages, and manages future scheduling.

---

📖 Deep Dive: The ML Pipeline

OXORAY utilizes a continuous task queue backed by a persistent PostgreSQL/SQLite model.

Core Task Types:

1. Connect Task: Ranks qualified profiles based on Gaussian Process model probability and sends connection requests (respecting your safety rate limits). If the queue is low, it triggers further profile discovery and qualification.
2. Check Pending Task: Periodically verifies if pending connection requests have been accepted, using an exponential backoff algorithm.
3. Follow-Up Task: Awakens the AI conversational agent to read new messages, craft context-aware replies, and nurture the lead.

The Active Qualification Loop

As profiles are discovered, they are automatically scraped and embedded into 384-dimensional FastEmbed vectors. To decide which raw prospect to evaluate next, the system uses a balance-driven strategy:

• Exploit Mode: When the pipeline is starved of qualified leads, it picks the profile with the highest predicted qualification probability.
• Explore Mode: When the pipeline is healthy, it picks the profile with the highest BALD (Bayesian Active Learning by Disagreement) score to learn more about uncertain boundary cases.

Every LLM decision feeds back into the GP model. During a "Cold Start" (fewer than 2 labeled profiles), candidates are selected sequentially. As labels accumulate, the ML model becomes highly efficient at prioritizing high-value candidates without wasting LLM tokens.

---

📋 Prerequisites

Requirement	Description
A LinkedIn account	Standard email and password for authentication.
An LLM API key	Bring your own OpenAI, Anthropic, or OpenAI-compatible endpoint key.
Campaign details	A simple natural language product description and target market definition.

---

⚡ Quick Start (Docker — Recommended)

We highly recommend deploying via Docker to ensure Playwright and all ML dependencies work seamlessly out-of-the-box. Pre-built images are available via GitHub Container Registry.

# Pull and run the latest image
docker run --pull always -it -p 5900:5900 -p 8000:8000 -v ~/.oxoray/data:/app/data ghcr.io/anurag-m1/oxoray:latest

On your first run, an interactive onboarding wizard will launch in your terminal. It will securely prompt for your LinkedIn credentials, API keys, and initial campaign setup. All generated data, cookies, models, and embeddings persist securely on your host machine inside ~/.oxoray/data.

Once the container initializes, open http://localhost:8000/engine.html in your browser to watch the stealth browser operating live!

---

⚙️ Local Installation (Development)

If you prefer to run the source code directly on your host machine for development or contribution purposes:

1. Clone & Set Up

Ensure you have Python 3.12+ and Git installed.

git clone https://github.com/anurag-m1/OXORAY.git
cd OXORAY

# Automatically install dependencies, Playwright browsers, and bootstrap the CRM
make setup

2. Run the Engine

make run

The terminal wizard will guide you through campaign setup. This process is fully stateful — you can stop the process (Ctrl+C) and restart it at any time without losing progress.

3. View Your Data (CRM Admin Dashboard)

OXORAY bundles a complete CRM interface powered by Django.

# Create an admin user account (run this only once)
python manage.py createsuperuser

# Start the web server
make admin

Access your dashboard by navigating to http://localhost:8000/admin/ in your web browser.

---

📂 Project Structure

OXORAY/
├── cli/                   # Command-line interface for campaign management
├── crm/                   # Django CRM apps (Leads, Deals, Companies)
├── docs/                  # Detailed project documentation and architecture guides
├── frontend/              # Next.js web dashboard and modern UI components
├── linkedin/              # Core Agentic Engine
│   ├── actions/           # Stealth browser interaction scripts (connect, message)
│   ├── agents/            # ReAct conversational follow-up AI agent
│   ├── api/               # LinkedIn internal Voyager API client integration
│   ├── browser/           # Playwright session, proxy, and stealth management
│   ├── db/                # Database ORM models, queries, and migrations
│   ├── ml/                # ML Pipeline: Gaussian Process, BALD scoring, FastEmbed
│   ├── pipeline/          # Sourcing logic and candidate qualification flow
│   └── engine.py          # Primary background task queue worker loop

├── manage.py              # Django CLI entrypoint
├── local.yml              # Docker Compose configuration for development
└── Makefile               # Developer shortcuts (make setup, run, admin)

---

📚 Further Documentation

For deep technical dives into specific systems, refer to our comprehensive documentation folder:

• System Architecture
• Configuration Reference
• Understanding the Profile Lifecycle
• Advanced Docker Setup
• Customizing Follow-up Messaging

---

Built for autonomous, scalable, and stealthy lead generation.