bonza-mragent 0.1.8

A lightweight, open-source AI Agent powered by free APIs

🤖 MRAgent

A lightweight, open-source AI Agent powered by free APIs

Features • Architecture • Getting Started • API Providers • Roadmap

---

✨ Overview

MRAgent is a lightweight AI agent that connects to free-tier LLM and multimodal APIs to deliver a powerful, personal assistant experience — without expensive subscriptions. It combines text generation, image generation, text-to-speech, speech-to-text, screen monitoring, web browsing, code execution, terminal access, and file management into a single, extensible agent.

Philosophy: Leverage the best free APIs available (primarily from NVIDIA and other open-source providers) to build an agent that rivals commercial solutions.

---

🚀 Features

Capability	Description	Status
💬 LLM Chat	Multi-model text generation (GPT-OSS, Kimi, GLM-5, Llama 3.3)	✅ Implemented
🎨 Image Generation	Text-to-image via Stable Diffusion 3.5 Large & FLUX Dev	✅ Implemented
🗣️ Text-to-Speech	Natural voice synthesis via Edge TTS (Free, Neutral)	✅ Implemented
👂 Speech-to-Text	Audio transcription via Groq Whisper v3 (Ultra-fast)	✅ Implemented
📧 Email Skill	Send & receive emails via AgentMail (Interactive /email command)	✅ Implemented
📱 Telegram Bot	Chat, Voice, & Image interaction	✅ Implemented
💓 VivreCard	Background Scheduler & Heartbeat System	✅ Implemented
🛡️ Poneglyph	System Guardian & Doctor (Auto-diagnostics)	✅ Implemented
🌐 Web Browsing	Autonomous internet surfing and information gathering	✅ Implemented
🖥️ Screen Monitoring	Capture and analyze screen content in real-time	✅ Implemented
💻 Code Execution	Write, run, and debug code in multiple languages	✅ Implemented
🔧 Terminal Access	Execute shell commands and system operations	✅ Implemented
📁 File Management	Navigate, create, move, and organize files	✅ Implemented
🔍 Web Search	Search the internet via Brave Search API	✅ Implemented
📛 Identity Setup	Interactive wizard to customize User and Agent persona	✅ Implemented
🛡️ HitL Security	Human-in-the-Loop required for Terminal and Code execution	✅ Implemented

---

🏗️ Architecture

MRAgent/
├── README.md
├── .env.example          # Template for API keys
├── .gitignore
├── requirements.txt      # Python dependencies
├── main.py               # Entry point
├── config/
│   └── settings.py       # Configuration & API key management
├── data/
│   ├── mragent.json      # 🆕 Poneglyph Configuration
│   └── vivrecard_jobs.json # Scheduled jobs
├── core/
│   └── poneglyph.py      # 🆕 System Guardian & Doctor
├── agents/
│   ├── core.py           # Core agent orchestration loop
│   ├── vivrecard.py      # 🆕 Scheduler system
│   ├── planner.py        # Task planning & decomposition
│   └── executor.py       # Action execution engine
├── skills/               # Modular Skills System
│   ├── base.py           # Base skill interface
│   ├── agentmail.py      # Email skill
│   └── telegram.py       # Telegram skill
├── providers/
│   ├── base.py           # Base API provider interface
│   ├── nvidia_llm.py     # NVIDIA LLM provider (GPT-OSS, Kimi, GLM)
│   ├── nvidia_image.py   # NVIDIA image generation (SD 3.5, FLUX)
│   ├── tts.py            # Edge TTS provider
│   ├── nvidia_stt.py     # Groq STT provider
│   └── brave_search.py   # Brave Search API
├── tools/
│   ├── browser.py        # Web browsing automation
│   ├── terminal.py       # Shell command execution
│   └── ...
├── ui/
│   ├── cli.py            # Command-line interface
│   ├── telegram_bot.py   # Telegram bot interface
│   └── web.py            # Flask Web Interface
└── utils/
    ├── logger.py         # Logging utilities
    └── helpers.py        # Shared helper functions

---

🛠️ Getting Started

Prerequisites

• Python 3.10+
• Free API keys (see API Providers)

Installation

Installation

One-Line Installer (Recommended)

Mac/Linux:

curl -fsSL https://raw.githubusercontent.com/bonzainsights/MrAgent/main/install.sh | bash

Windows (PowerShell):

iwr https://raw.githubusercontent.com/bonzainsights/MrAgent/main/install.bat | iex

Pip (Python Package)

If you have Python 3.10+ installed:

pip install bonza-mragent
mragent

Homebrew (macOS)

brew install --HEAD https://raw.githubusercontent.com/bonzainsights/MRAgent/main/Formula/mragent.rb

Manual Setup (Advanced)

# Clone the repository
git clone https://github.com/bonzainsights/MrAgent.git
cd MRAgent

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up your environment variables
cp .env.example .env
# Edit .env with your API keys

Quick Start

If you boot the system without API keys or an identity configured, an Interactive Setup Wizard will safely guide you through copying your free NVIDIA NIM key and naming your Assistant before booting automatically!

# Run the agent (CLI mode + Web UI)
python main.py

# Run as Telegram bot
python main.py --mode telegram

# Run System Diagnostic
python main.py doctor

---

🔑 API Providers

MRAgent is built around free-tier APIs to keep costs at zero. Here are the current providers:

NVIDIA NIM (Primary)

Model	Purpose	API
GPT-OSS-120B	Reasoning (Primary)	NVIDIA NIM
Kimi K2.5	General-purpose LLM	NVIDIA NIM
GLM-5	Reasoning & code	NVIDIA NIM
Llama 3.3 70B	Reliable fallback	NVIDIA NIM
Qwen2.5 Coder	Code generation	NVIDIA NIM
Stable Diffusion 3.5 Large	Image generation	NVIDIA NIM
FLUX.1 Dev	Image generation	NVIDIA NIM

Other Free Providers

Provider	Purpose	Service
Groq	Speech-to-Text	Whisper Large v3 (Free)
Edge TTS	Text-to-Speech	Microsoft Edge Neural (Free)
AgentMail	Email	AgentMail.to (Free)
Brave Search	Web search	Brave Search API (Free)
Telegram	Messaging Interface	Telegram Bot API (Free)

💡 Adding new providers? Implement the base interface in providers/base.py and register your provider in the config.

---

🗺️ Roadmap

• Project setup & repository initialization
• Core agent loop with task planning
• NVIDIA LLM integration (multi-model)
• Image generation pipeline
• Text-to-speech (Edge TTS)
• Speech-to-text (Groq Whisper)
• Telegram bot interface (Voice & Image support)
• Web Interface (Chat & Voice)
• Email Integration (AgentMail)
• VivreCard Scheduler
• Poneglyph System (Guardian & Doctor)
• Brave Search integration
• Terminal & code execution tools
• File management system
• Screen monitoring & analysis
• Web browsing automation
• Security: Terminal/Code Execution Approvals (HitL)
• Security: Web UI & Telegram Authentication
• Interactive Startup Wizards (API Keys & Identity)
• NVIDIA API Key Consolidation (Global Defaulting)

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is open source. See the LICENSE file for details.

---

⚠️ Disclaimer

MRAgent uses free-tier API keys which may have rate limits and usage quotas. The agent is designed to work within these constraints. Never commit your .env file or expose API keys publicly.

---

Built with ❤️ by Bonza Insights & achbj