root-engine 0.1.4__tar.gz

root_engine-0.1.4/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.log
+bridge/node_modules/
+bridge/dist/
+CLAUDE.md
+core_agent_lines.sh

root_engine-0.1.4/LICENSE

@@ -0,0 +1,13 @@
+Proprietary Software License
+
+Copyright (c) 2026 Trey Timbrook / Rootbros AI LLC. All rights reserved.
+
+This software and its source code are the exclusive property of Trey Timbrook
+and Rootbros AI LLC. Unauthorized copying, modification, distribution,
+sublicensing, or use of this software, in whole or in part, is strictly
+prohibited without prior written permission from Rootbros AI LLC.
+
+This software is provided for authorized use only. Access to this software
+does not grant any rights to the underlying intellectual property.
+
+For licensing inquiries, contact: trey@rootbrosai.com

root_engine-0.1.4/PKG-INFO

@@ -0,0 +1,437 @@
+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
+```