Skip to content

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

13 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

workerAI

An intelligent agentic workflow system powered by vLLM and LangGraph

workerAI is a Python-based autonomous agent that executes complex tasks by dynamically planning, reasoning, and using a library of specialized tools. Built on a robust ReAct (Reason-Act) loop using LangGraph, it provides a powerful, self-correcting orchestration system for handling diverse workflows.

🌟 Features

  • Autonomous Task Execution: Takes high-level tasks and breaks them down autonomously
  • Tool-Calling Architecture: LLM-driven tool selection and execution
  • Stateful Reasoning Loop: Cyclical ReAct pattern for robust task completion
  • 100% In-House: All components run on your infrastructure (vLLM, ChromaDB, etc.)
  • Comprehensive Tools:
    • Web search and scraping
    • Email management (send/read)
    • File system operations
    • Vector-based long-term memory
  • Interactive & Programmatic Modes: CLI, single-task, or file-based execution

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    User Request                         │
└───────────────────┬─────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────┐
│              LangGraph Orchestrator                     │
│  ┌──────────────────────────────────────────────────┐  │
│  │  call_model → router → call_tool → call_model   │  │
│  │      ↑                                    │       │  │
│  │      └────────────────────────────────────┘       │  │
│  └──────────────────────────────────────────────────┘  │
└───────┬─────────────────────────────────────────────────┘
        │
        ├─── vLLM (Tool-calling LLM)
        │
        └─── Tool Registry
              ├─── Web Tools (search, scrape)
              ├─── Email Tools (send, read)
              ├─── File Tools (read, write, list, delete)
              └─── Memory Tools (memorize, recall)

📋 Prerequisites

  1. Python 3.10+
  2. vLLM Server running with a tool-calling capable model (e.g., Llama-3-70B, Mixtral-8x22B)
  3. Optional: Email credentials (for email tools)
  4. Optional: Playwright browsers installed (for web scraping)

🚀 Quick Start

1. Clone the Repository

git clone <repository-url>
cd workerAI

2. Install Dependencies

pip install -r requirements.txt

3. Install Playwright Browsers (for web scraping)

playwright install

4. Configure Environment

cp .env.example .env
# Edit .env with your settings (vLLM endpoint, email credentials, etc.)

5. Start vLLM Server

In a separate terminal:

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3-70B-Instruct \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

6. Run workerAI

Interactive mode:

python main.py

Single task:

python main.py -t "Research recent AI developments and summarize the top 3 trends"

From file:

echo "Search for Python programming tutorials and save to file" > task.txt
python main.py -f task.txt

Verbose mode:

python main.py -t "Your task here" -v

📁 Project Structure

workerAI/
├── main.py                      # Entry point (CLI interface)
├── config.py                    # Configuration management
├── llm_client.py               # vLLM client wrapper
├── requirements.txt            # Python dependencies
│
├── orchestrator/               # LangGraph-based orchestrator
│   ├── __init__.py
│   ├── state.py               # AgentState TypedDict
│   ├── graph.py               # LangGraph definition (ReAct loop)
│   └── manager.py             # Node functions (call_model, call_tool, etc.)
│
├── tools/                      # Tool library
│   ├── __init__.py
│   ├── tool_registry.py       # Central tool registry + schemas
│   ├── web_browser.py         # search_web, scrape_url
│   ├── email_client.py        # send_email, read_inbox
│   ├── file_system.py         # read_file, write_file, etc.
│   └── vector_memory.py       # memorize, recall (ChromaDB)
│
└── prompts/
    └── orchestrator_prompt.md  # System prompt for the agent

🔧 Configuration

All configuration is managed through environment variables (.env file) or config.py.

Key settings:

Variable Description Default
VLLM_BASE_URL vLLM API endpoint http://localhost:8000/v1
VLLM_MODEL_NAME Model to use meta-llama/Llama-3-70B-Instruct
MAX_ITERATIONS Safety limit for agent loops 20
WORKING_DIRECTORY Workspace for file operations ./workspace
CHROMA_PERSIST_DIRECTORY Vector DB storage ./data/chroma_db
VERBOSE Enable detailed logging true

See .env.example for all available options.

🛠️ Available Tools

Web Tools

  • search_web(query, num_results=5): Google search
  • scrape_url(url): Extract text content from URLs

Email Tools

  • send_email(to, subject, body): Send emails via SMTP
  • read_inbox(max_emails=10, unread_only=true): Read emails via IMAP

File Tools

  • read_file(file_path): Read file contents
  • write_file(file_path, content, append=false): Write to files
  • list_directory(directory_path="."): List directory contents
  • delete_file(file_path): Delete a file

Memory Tools

  • memorize(text, metadata={}): Store in vector memory
  • recall(query, num_results=3): Semantic search of memories
  • list_memories(limit=10): List stored memories
  • clear_memory(): Clear all memories

📖 Usage Examples

Example 1: Research Task

python main.py -t "Research the company 'Anthropic' and tell me about their latest products"

The agent will:

  1. Search Google for "Anthropic company latest products"
  2. Scrape relevant URLs
  3. Synthesize information
  4. Provide a comprehensive summary

Example 2: File Analysis

python main.py -t "List all Python files in the current directory and count total lines"

Example 3: Email + Research

python main.py -t "Read my recent emails, find any mentioning 'project deadline', and create a summary file"

Example 4: Multi-Step Workflow

python main.py -t "Search for 'Python async best practices', save the findings to a file called 'async_notes.txt', and memorize the key points for future reference"

🔍 How It Works

The ReAct Loop

  1. User submits task → Initial state created
  2. call_model → LLM receives task + available tools
  3. LLM responds with either:
    • Tool call(s) to execute
    • Final answer
  4. Router decides:
    • Tool calls? → Go to call_tool
    • Final answer? → Go to finalize
  5. call_tool → Executes tools, returns results
  6. Loop back to call_model with tool results
  7. Repeat until final answer or max iterations

Tool Calling Flow

# 1. LLM receives tool schemas
tools = [
    {
        "type": "function",
        "function": {
            "name": "search_web",
            "description": "...",
            "parameters": {...}
        }
    },
    ...
]

# 2. LLM outputs structured tool call
{
    "role": "assistant",
    "tool_calls": [{
        "function": {
            "name": "search_web",
            "arguments": '{"query": "..."}'
        }
    }]
}

# 3. Orchestrator executes tool
result = tool_registry.get_tool_function("search_web")(query="...")

# 4. Result fed back to LLM
{
    "role": "tool",
    "content": result
}

🧪 Testing

Test the system with a simple task:

python main.py -t "What is 2+2? Use the memorize tool to remember this answer."

You should see:

  • The agent calling the memorize tool
  • A final answer of "4"
  • Verbose logs showing the reasoning loop (if -v is enabled)

🔐 Security Notes

  • Email Credentials: Use app-specific passwords, not your main password
  • vLLM Server: Ensure your vLLM server is not exposed publicly
  • File Operations: The agent can read/write files in WORKING_DIRECTORY
  • Tool Execution: All tool code runs locally with your permissions

🤝 Contributing

This is a robust foundation for agentic workflows. Potential enhancements:

  • Additional tools (database queries, API calls, etc.)
  • Streaming responses
  • Multi-agent collaboration
  • Advanced error recovery
  • Web UI interface

📄 License

See LICENSE file for details.

🙏 Acknowledgments

Built with:


workerAI - Autonomous task execution, powered by you.

Releases

Packages

Contributors

Languages