Metadata-Version: 2.4
Name: root-engine
Version: 0.1.4
Summary: A lightweight personal AI assistant framework
Project-URL: Homepage, https://github.com/TreyBros/root_engine
Project-URL: Repository, https://github.com/TreyBros/root_engine
Project-URL: Bug Tracker, https://github.com/TreyBros/root_engine/issues
Author-email: Trey Timbrook <trey@rootbrosai.com>
Maintainer-email: Trey Timbrook <trey@rootbrosai.com>
License: Proprietary
License-File: LICENSE
Keywords: agent,ai,chatbot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: croniter>=2.0.0
Requires-Dist: dingtalk-stream>=0.4.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: json-repair>=0.30.0
Requires-Dist: lark-oapi>=1.0.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: msgpack>=1.0.8
Requires-Dist: oauth-cli-kit>=0.1.1
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-socketio>=5.11.0
Requires-Dist: python-socks[asyncio]>=2.4.0
Requires-Dist: python-telegram-bot[socks]>=21.0
Requires-Dist: qq-botpy>=1.0.0
Requires-Dist: readability-lxml>=0.8.0
Requires-Dist: rich>=13.0.0
Requires-Dist: slack-sdk>=3.26.0
Requires-Dist: slackify-markdown>=0.2.0
Requires-Dist: socksio>=1.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: websocket-client>=1.6.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <img src="root_engine_logo.png" alt="Root Engine" width="500">
  <h1>Root Engine</h1>
  <p><b>Ultra-lightweight, extensible runtime for personal agents, tool use, and multi-channel automation.</b></p>
  <p>
    <img src="https://img.shields.io/badge/python-≥3.11-blue" alt="Python">
  </p>
</div>

## What is Root Engine?

**Root Engine** is a compact agent runtime designed to be **easy to read**, **easy to extend**, and **fast to ship**.
It focuses on the fundamentals: **agent loop + tools + skills + memory + channels + scheduling**—without burying you in frameworks.

If you want a repo you can actually *understand end-to-end*, modify confidently, and deploy quickly, this is the point.

---

## Key Features

- **Ultra-Lightweight Core**
  Small, focused agent runtime with clean boundaries between agent logic, tools, and integrations.

- **Provider-Driven LLM Support**
  Plug in popular LLM providers (or any OpenAI-compatible endpoint) via a simple provider registry + config.

- **Tool Use + Skills System**
  Built-in tools and a skills loader so agents can execute actions, call external capabilities, and stay modular.

- **Persistent Memory**
  Optional long-running memory for continuity across sessions.

- **Multi-Channel Gateways**
  Run Root Engine through chat platforms and messaging channels (where supported in this repo).

- **Scheduled Tasks (Cron)**
  Run proactive reminders, routines, and agent jobs on a schedule.

- **MCP Support**
  Connect external tool servers using Model Context Protocol, automatically discovered on startup.

- **Security Controls**
  Workspace restrictions and allow-lists to reduce risk when running agents in real environments.

---

## Architecture

<p align="center">
  <img src="root_engine_arch.png" alt="Root Engine architecture" width="800">
</p>

At a high level:
- A **CLI** launches an **agent** or a **gateway**
- The **agent loop** runs LLM ↔ tool execution
- A **provider registry** resolves LLM routing
- **Skills** extend capabilities cleanly
- **Channels** handle inbound/outbound messaging
- **Cron/heartbeat** enable proactive behavior

---

## Install

**Requires Python 3.11+**

```bash
git clone https://github.com/TreyBros/root_engine
cd root-engine
pip install -e .
```

> Once published on PyPI: `pip install root-engine`

---

## Quick Start

Root Engine reads configuration from: `~/.root-engine/config.json`

### 1) Initialize

```bash
root-engine onboard
```

### 2) Configure your provider + model

Edit `~/.root-engine/config.json` and set at minimum:

Provider API key (example: OpenRouter)

```json
{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  }
}
```

Default model

```json
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}
```

### 3) Chat

```bash
root-engine agent
```

Or one-shot:

```bash
root-engine agent -m "Hello!"
```

---

## Chat Apps

Root Engine can run as a gateway for supported chat platforms (tokens/credentials required).
Enable a channel in `~/.root-engine/config.json`, then run:

```bash
root-engine gateway
```

### Channel Config Examples

**Telegram**

```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}
```

**Discord**

```json
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}
```

**Slack (Socket Mode)**

```json
{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "groupPolicy": "mention"
    }
  }
}
```

---

## Configuration

Config file: `~/.root-engine/config.json`

### Providers

Root Engine uses a provider registry to route models and normalize configuration.

Common provider entries include:

- `openrouter`
- `anthropic`
- `openai`
- `deepseek`
- `groq`
- `gemini`
- `minimax`
- `dashscope`
- `moonshot`
- `zhipu`
- `vllm` (local / OpenAI-compatible)
- `custom` (any OpenAI-compatible API base)

Exact available providers depend on what's included in this repo version.

### Custom Provider (Any OpenAI-compatible API)

```json
{
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.your-provider.com/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "your-model-name"
    }
  }
}
```

### vLLM (local / OpenAI-compatible)

```json
{
  "providers": {
    "vllm": {
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}
```

---

## MCP (Model Context Protocol)

Root Engine can connect to MCP tool servers and expose them as native tools.

Example config:

```json
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      }
    }
  }
}
```

Supported transport modes:

- **Stdio**: `command` + `args`
- **HTTP**: `url` (remote endpoint)

MCP tools are discovered and registered on startup.

---

## Security

For safer local/prod use, restrict tool access to your workspace:

```json
{
  "tools": {
    "restrictToWorkspace": true
  }
}
```

And restrict who can interact on channels:

```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `root-engine onboard` | Initialize config & workspace |
| `root-engine agent` | Interactive agent chat |
| `root-engine agent -m "..."` | One-shot message |
| `root-engine agent --no-markdown` | Plain-text replies |
| `root-engine agent --logs` | Show runtime logs |
| `root-engine gateway` | Start multi-channel gateway |
| `root-engine status` | Show runtime/config status |
| `root-engine channels status` | Show channel status |
| `root-engine cron add ...` | Add scheduled job |
| `root-engine cron list` | List scheduled jobs |
| `root-engine cron remove <id>` | Remove scheduled job |

Interactive mode exits: `exit`, `quit`, `/exit`, `/quit`, `:q`, or `Ctrl+D`.

---

## Scheduled Tasks (Cron)

```bash
# Add a job
root-engine cron add --name "daily" --message "Good morning!" --cron "0 9 * * *"
root-engine cron add --name "hourly" --message "Check status" --every 3600

# List jobs
root-engine cron list

# Remove a job
root-engine cron remove <job_id>
```

---

## Docker

### Compose

```bash
docker compose run --rm root-engine-cli onboard
vim ~/.root-engine/config.json
docker compose up -d root-engine-gateway
docker compose run --rm root-engine-cli agent -m "Hello!"
docker compose logs -f root-engine-gateway
docker compose down
```

### Docker

```bash
docker build -t root-engine .

docker run -v ~/.root-engine:/root/.root-engine --rm root-engine onboard
vim ~/.root-engine/config.json

docker run -v ~/.root-engine:/root/.root-engine -p 18790:18790 root-engine gateway
docker run -v ~/.root-engine:/root/.root-engine --rm root-engine agent -m "Hello!"
docker run -v ~/.root-engine:/root/.root-engine --rm root-engine status
```

---

## Project Structure

```
root_engine/
├── agent/          # Core agent logic
│   ├── loop.py     # Agent loop (LLM ↔ tool execution)
│   ├── context.py  # Prompt builder
│   ├── memory.py   # Persistent memory
│   ├── skills.py   # Skills loader
│   ├── subagent.py # Background task execution
│   └── tools/      # Built-in tools
├── skills/         # Bundled skills
├── channels/       # Chat channel integrations
├── bus/            # Message routing
├── cron/           # Scheduled tasks
├── heartbeat/      # Proactive wake-up
├── providers/      # LLM providers
├── session/        # Conversation sessions
├── config/         # Configuration schema + loader
└── cli/            # CLI commands
```
