Skip to content

mtecnic/workerAI

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.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors