npmai-agents 0.0.1

A production-grade AI agent framework with 21 integrated tool classes and a four-role autonomous LLM pipeline — built on the NPMAI ECOSYSTEM.

🌐 Website · 📦 PyPI · 🐙 GitHub · 📖 Docs · 🤝 Community

---

✦ What is npmai_agents?

npmai_agents is a monolithic, production-grade desktop AI agent framework — a single Python package containing 21 integrated tool classes and a 4-role autonomous LLM pipeline (Planner → Coder → Auditor → Verifier) that can execute any plain-English task on your computer.

No GPT-4. No Gemini. No monthly bills.
Everything runs free on 45+ open-source LLMs served by the NPMAI ECOSYSTEM load balancer.

pip install npmai_agents

from npmai_agents import AgentBrain

brain = AgentBrain()
brain.run_task("Organise my Downloads folder and email me a summary")
# ↑ That's it. The agent plans, codes, audits, executes, verifies — by itself.

---

🏛️ Built by NPMAI ECOSYSTEM

npmai_agents is an official product of the NPMAI ECOSYSTEM — a free, open-source AI research and development platform serving developers and researchers worldwide.

👤 Founder Sonu Kumar (Bihar Viral Boy) 15-year-old self-taught developer, TEDx Speaker & AI Researcher from Bihar, India · based in Kota, Rajasthan

🌍 Ecosystem Stats 2,000,000+ PyPI downloads 45+ community LLMs 6+ deployed AI products 0₹ cost to users — forever

---

⚡ Why npmai_agents?

🔴 The Problem	🟢 npmai_agents Solution
Paid LLM APIs (GPT-4, Claude, Gemini)	45+ free LLMs via NPMAI load balancer
Single-model, single-purpose agents	4 specialized LLM roles in one pipeline
Scattered automation libraries	21 tool classes in one package
Plain-text credential storage	Fernet-encrypted CredStore (machine key)
No memory between sessions	Persistent Memory via npmai.Memory
Manual document Q&A setup	LARA RAG pipeline built-in
Complex dependency management	Auto-installs everything on first run
Fragile single-attempt execution	Up to 12 auto-retries per step with error feedback

---

🚀 Features

┌─────────────────────────────────────────────────────────────────────┐
│                    npmai_agents  v0.0.1                             │
│                                                                     │
│   ╔══════════════╗  ╔══════════════╗  ╔══════════════╗             │
│   ║  21 TOOLS    ║  ║  4-LLM PIPE  ║  ║  FERNET ENC  ║             │
│   ║  one package ║  ║  autonomous  ║  ║  credentials ║             │
│   ╚══════════════╝  ╚══════════════╝  ╚══════════════╝             │
│                                                                     │
│   ╔══════════════╗  ╔══════════════╗  ╔══════════════╗             │
│   ║  LARA RAG    ║  ║  12x RETRY   ║  ║  KILL SWITCH ║             │
│   ║  built-in    ║  ║  per step    ║  ║  mid-task    ║             │
│   ╚══════════════╝  ╚══════════════╝  ╚══════════════╝             │
│                                                                     │
│   ╔══════════════╗  ╔══════════════╗  ╔══════════════╗             │
│   ║  WORKSPACE   ║  ║  PERSISTENT  ║  ║  SECURITY    ║             │
│   ║  scanner     ║  ║  memory      ║  ║  auditor     ║             │
│   ╚══════════════╝  ╚══════════════╝  ╚══════════════╝             │
└─────────────────────────────────────────────────────────────────────┘

• 🔧 21 integrated tool classes — email, files, PDF, web, spreadsheets, GitHub, Slack, Discord, WhatsApp, Notion, Twitter, system, images, scheduler, Jira, Telegram, QR, voice, watcher, RAG, SSH
• 🧠 Four-role LLM pipeline — each role runs a different model optimised for its purpose
• 🔒 Built-in security auditor — every generated code block is scanned before execution
• 🔐 Fernet-encrypted CredStore — machine-specific AES key, never plain text
• 📚 LARA RAG integration — query and summarise any document
• 💾 Persistent memory — separate contexts for planning, coding, chat, task history
• ♻️ Auto-dependency installer — missing packages pip-installed on first run
• 🎯 12 auto-retries per step — error output fed back to the coder LLM
• 🖥️ Workspace scanner — agent builds a live file-system profile before planning

---

🏗️ Architecture

                    ╔═══════════════════════╗
     Plain English  ║                       ║
     Task Input ──▶ ║      AgentBrain       ║
                    ║                       ║
                    ║  ┌─────────────────┐  ║
                    ║  │  1. WORKSPACE   │  ║  ◀── scans Desktop, Downloads,
                    ║  │     SCANNER     │  ║       Documents, Pictures, etc.
                    ║  └────────┬────────┘  ║
                    ║           │            ║
                    ║  ┌────────▼────────┐  ║
                    ║  │  2. PLANNER     │  ║  ◀── llama3.2:3b / mistral:7b
                    ║  │     LLM         │  ║       breaks task → 2–5 steps
                    ║  └────────┬────────┘  ║
                    ║           │            ║
                    ║    ╔══════▼══════╗     ║   ┌─────────────────────────┐
                    ║    ║  per step:  ║     ║   │ repeats up to 12 times  │
                    ║    ║             ║     ║   │ on failure, feeding     │
                    ║    ║  3. CODER   ║─────║───│ error output back to    │
                    ║    ║     LLM     ║     ║   │ the Coder LLM           │
                    ║    ║  4. AUDITOR ║     ║   └─────────────────────────┘
                    ║    ║     LLM     ║     ║
                    ║    ║  5. EXECUTE ║     ║
                    ║    ║  6. VERIFY  ║     ║
                    ║    ╚═════════════╝     ║
                    ║                       ║
                    ╚═══════════════════════╝
                                │
                                ▼
                       Task Complete ✓

Role	Default Model	Fallback	Job
🗺️ Planner	llama3.2:3b	mistral:7b	Breaks task into 2–5 atomic steps
💻 Coder	codellama:7b-instruct	deepseek-coder:6.7b	Generates executable Python code
🛡️ Auditor	qwen2.5-coder:7b	falcon:7b-instruct	Security scan before execution
✅ Verifier	llama3.2:3b	mistral:7b	Confirms step completed successfully
💬 Chatter	granite3.3:2b	llama3.2:1b	General Q&A / conversational mode

All models served free via NPMAI ECOSYSTEM load balancer with change=True auto-fallback.

---

📦 Installation

pip install npmai_agents

Auto-installs all dependencies on first run. Or pre-install everything:

pip install npmai_agents[full]

Import styles:

# Import specific classes
from npmai_agents import AgentBrain, CredStore, EmailTool, FileTool

# Import the whole module
import npmai_agents

---

📖 Documentation

---

🔐 CredStore — Encrypted Credential Vault

Configure once. All 21 tools read from here. Stored at ~/.npmai_agent/creds.json with a machine-specific Fernet key.

from npmai_agents import CredStore

# ── Save credentials ──────────────────────────────────────────────────
CredStore.save("gmail", {
    "email":     "[e-mail]",
    "password":  "your-app-password",    # Gmail App Password, not login password
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "imap_host": "imap.gmail.com"
})

CredStore.save("github",   {"token": "ghp_xxxxxxxxxxxxxxxxxxxx"})
CredStore.save("slack",    {"bot_token": "xoxb-xxxxxxxxxxxx"})
CredStore.save("notion",   {"token": "secret_xxxxxxxxxxxx"})
CredStore.save("telegram", {"bot_token": "1234567890:AAxxxxxxxxxxxxxx"})

CredStore.save("twitter", {
    "api_key": "...", "api_secret": "...",
    "access_token": "...", "access_token_secret": "..."
})

CredStore.save("jira", {
    "server":    "https://yourworkspace.atlassian.net",
    "email":     "[e-mail]",
    "api_token": "your-jira-api-token"
})

CredStore.save("ssh", {"user": "ubuntu", "password": "secret"})
# or with SSH key: CredStore.save("ssh", {"user": "ubuntu", "key_path": "~/.ssh/id_rsa"})

# ── Load & inspect ────────────────────────────────────────────────────
creds = CredStore.load("gmail")
print(creds["email"])

print(CredStore.all_keys())
# ['gmail', 'github', 'slack', 'notion', 'telegram', 'jira', 'ssh']

Credential reference by tool:

Tool	cred_key	Required fields
EmailTool	"gmail"	email, password, smtp_host, smtp_port, imap_host
GitHubTool	"github"	token
SlackTool	"slack"	bot_token
SpreadsheetTool	"google"	Full service account JSON as dict
NotionTool	"notion"	token
TwitterTool	"twitter"	api_key, api_secret, access_token, access_token_secret
JiraTool	"jira"	server, email, api_token
TelegramTool	"telegram"	bot_token
SSHTool	"ssh"	user, password or key_path

---

🖥️ Workspace — File System Context

from npmai_agents import Workspace

ws = Workspace()

profile = ws.scan()           # scans Desktop, Downloads, Documents, etc.
print(profile["os"])          # 'Windows' / 'Darwin' / 'Linux'
print(profile["home"])        # '/home/sonu'
print(profile["paths"])       # { 'desktop': { path, files }, ... }

ws.update_profile("user_name", "Sonu Kumar")
print(ws.context_summary())   # short text fed to the Planner LLM

---

📧 EmailTool

from npmai_agents import EmailTool

# Send a single email
result = EmailTool.send(
    to="[e-mail]",
    subject="Hello from npmai_agents",
    body="<h1>Sent by an AI agent!</h1>"
)
print(result)   # ✓ Email sent to [e-mail]

# With attachments
result = EmailTool.send(
    to="[e-mail]",
    subject="Monthly Report",
    body="Report attached.",
    attachments=["/home/sonu/report.pdf"]
)

# Read inbox
result = EmailTool.read_inbox(count=10)
for msg in result.data:
    print(msg["from"], "|", msg["subject"])

# Bulk email from CSV (must have 'name' + 'email' columns)
result = EmailTool.send_bulk(
    csv_path="contacts.csv",
    subject="NPMAI Launch Invite",
    body_template="<p>Hello {name}, you're invited!</p>"
)
print(result)   # ✓ Sent 42 emails, 0 failed

---

📁 FileTool

from npmai_agents import FileTool

# Bulk rename
FileTool.bulk_rename("/home/sonu/Docs", pattern="*.txt", prefix="NPMAI_", add_date=True)

# Zip / unzip
FileTool.zip_folder("/home/sonu/project", dest="/home/sonu/project.zip")
FileTool.unzip("/home/sonu/archive.zip", dest="/home/sonu/extracted")

# Find files
result = FileTool.find_files("/home/sonu", pattern="*.py", recursive=True)
print(result.data)   # ['/home/sonu/agent.py', ...]

# Organize by type → creates Images/ Videos/ Docs/ Code/ etc.
FileTool.organize_by_type("/home/sonu/Downloads")

# Read / write
content = FileTool.read_file("/home/sonu/notes.txt").data
FileTool.write_file("/home/sonu/out.txt", "Generated by npmai_agents.")

# Copy tree
FileTool.duplicate_tree("/home/sonu/project", "/home/sonu/project_backup")

---

📄 PDFTool

from npmai_agents import PDFTool

# Extract text
text = PDFTool.extract_text("/home/sonu/paper.pdf").data

# Merge PDFs
PDFTool.merge(["/home/sonu/ch1.pdf", "/home/sonu/ch2.pdf"], out="/home/sonu/book.pdf")

# Split into pages
PDFTool.split("/home/sonu/doc.pdf", out_dir="/home/sonu/pages")

---

🌐 WebTool

from npmai_agents import WebTool

# Scrape page text
result = WebTool.scrape("https://npmai.netlify.app")

# Scrape with CSS selector
result = WebTool.scrape("https://example.com", selector="h2")
print(result.data)   # ['Title 1', 'Title 2', ...]

# Download a file
WebTool.download_file("https://example.com/file.pdf", dest="/home/sonu/file.pdf")

# Full-page screenshot
WebTool.screenshot_url("https://npmai.netlify.app", out="screenshot.png")

# Browser automation (Playwright)
WebTool.browser_action("https://example.com/login", actions=[
    {"type": "fill",       "selector": "#username", "value": "sonu"},
    {"type": "fill",       "selector": "#password", "value": "secret"},
    {"type": "click",      "selector": "#login-btn"},
    {"type": "wait",       "ms": 2000},
    {"type": "screenshot", "path": "after_login.png"}
])

# Raw API call
result = WebTool.api_call(
    url="https://api.example.com/data",
    method="POST",
    headers={"Authorization": "Bearer token"},
    payload={"query": "test"}
)
print(result.data)   # parsed JSON

---

📊 SpreadsheetTool

from npmai_agents import SpreadsheetTool

# Read CSV → pandas DataFrame
df = SpreadsheetTool.read_csv("/home/sonu/data.csv").data

# Write to Excel
SpreadsheetTool.write_excel(
    data=[{"name": "Sonu", "age": 15}],
    path="/home/sonu/out.xlsx",
    sheet="Founders"
)

# Google Sheets (needs 'google' cred with service account JSON)
result = SpreadsheetTool.google_sheets_read(sheet_id="1Bxi...", range_="Sheet1")
print(result.data)   # list of row dicts

---

🐙 GitHubTool

from npmai_agents import GitHubTool

# Create issue
GitHubTool.create_issue(
    repo="sonuramashishnpm/npmai",
    title="Add voice input support",
    body="Feature request...",
    labels=["enhancement"]
)

# Push file (creates or updates)
GitHubTool.push_file(
    repo="sonuramashishnpm/npmai",
    path="docs/agent.md",
    content="# npmai_agents docs\n...",
    message="docs: add agent docs"
)

# List issues
for issue in GitHubTool.list_issues("sonuramashishnpm/npmai").data:
    print(issue["#"], issue["title"])

# Get README
print(GitHubTool.get_readme("sonuramashishnpm/npmai").data[:300])

# Clone & commit-push
GitHubTool.clone_repo("https://github.com/sonuramashishnpm/npmai.git", "/home/sonu/npmai")
GitHubTool.git_commit_push("/home/sonu/npmai", "feat: new endpoints")

---

💬 SlackTool

from npmai_agents import SlackTool

SlackTool.send_message("#general", "npmai_agents task done ✓")

for msg in SlackTool.read_channel("#dev-logs", limit=20).data:
    print(msg["user"], ":", msg["text"])

SlackTool.upload_file("#reports", "/home/sonu/report.pdf", comment="Weekly AI report")

---

🎮 DiscordTool

from npmai_agents import DiscordTool

WEBHOOK = "https://discord.com/api/webhooks/xxxx/yyyy"

DiscordTool.send_webhook(WEBHOOK, "🚀 Deployment complete!")

DiscordTool.send_webhook(WEBHOOK, "Update:", embeds=[{
    "title": "Step 3 Done",
    "description": "All files organized.",
    "color": 3066993
}])

---

📱 WhatsAppTool

from npmai_agents import WhatsAppTool

# Requires WhatsApp Web open in browser
WhatsAppTool.send(phone="[phone]", message="Hello from npmai_agents!", wait=15)

---

📝 NotionTool

from npmai_agents import NotionTool

NotionTool.create_page(
    parent_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    title="NPMAI Research Notes",
    content="Auto-created by npmai_agents."
)

NotionTool.add_db_entry(
    db_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    props={
        "Name":   {"title": [{"text": {"content": "Task Done"}}]},
        "Status": {"select": {"name": "Done"}}
    }
)

---

🐦 TwitterTool

from npmai_agents import TwitterTool

TwitterTool.tweet("Just automated my workflow with npmai_agents 🤖 #OpenSource #AI")

---

⚙️ SystemTool

from npmai_agents import SystemTool

# Shell command
print(SystemTool.run_command("ls -la /home/sonu", timeout=30).output)

# Clipboard
SystemTool.set_clipboard("Copied by npmai_agents")
print(SystemTool.get_clipboard().data)

# Screenshot
SystemTool.screenshot(out="/home/sonu/screen.png")

# Processes
for p in SystemTool.get_processes().data[:5]:
    print(p["name"], p["cpu"], "%")

# Desktop notification
SystemTool.notify("npmai_agents", "Task complete!")

---

🖼️ ImageTool

from npmai_agents import ImageTool

ImageTool.resize("/home/sonu/photo.jpg", width=800, height=600, out="resized.jpg")
ImageTool.convert("/home/sonu/photo.jpg", format="PNG", out="photo.png")

# OCR
text = ImageTool.ocr("/home/sonu/scanned.png").data
print(text)

# Bulk compress
ImageTool.bulk_compress("/home/sonu/Pictures", quality=75)

---

⏱️ SchedulerTool

from npmai_agents import SchedulerTool

def daily_job():
    print("Running daily task!")

SchedulerTool.schedule_task("heartbeat",    "every 5 minutes",        daily_job)
SchedulerTool.schedule_task("daily_report", "every day at 09:00",     daily_job)
SchedulerTool.schedule_task("weekly_sync",  "every monday at 08:00",  daily_job)

SchedulerTool.cancel_task("heartbeat")

---

📋 JiraTool

from npmai_agents import JiraTool

JiraTool.create_issue(
    project="NPMAI",
    summary="Integrate agent v0.0.1 with desktop UI",
    description="Wire agent core to PySide6 app.",
    issue_type="Task"
)
# ✓ Jira issue NPMAI-17 created

---

✈️ TelegramTool

from npmai_agents import TelegramTool

TelegramTool.send(chat_id="123456789", text="✅ Task complete: organised 87 files.")

---

📷 QRTool

from npmai_agents import QRTool

QRTool.generate(data="https://npmai.netlify.app", out="npmai_qr.png", size=10)

---

🎤 VoiceTool

from npmai_agents import VoiceTool

VoiceTool.speak("Task completed. npmai_agents is ready.")

result = VoiceTool.listen(seconds=5)
if result.success:
    print(result.data)   # recognised speech text

---

👁️ WatcherTool

from npmai_agents import WatcherTool

def on_change(file_path):
    print(f"Changed: {file_path}")

WatcherTool.watch("/home/sonu/incoming", callback=on_change)
# Runs in background thread — ✓ Watching /home/sonu/incoming

---

🧠 RAGTool

from npmai_agents import RAGTool

# Query any document with a natural language question
result = RAGTool.query_document(
    doc_path="/home/sonu/paper.pdf",
    question="What is the main contribution of this paper?",
    chunk_size=500
)
print(result.data)

# Summarise a large file (up to 10 × 3000-char chunks)
summary = RAGTool.summarize_large_file("/home/sonu/thesis.pdf", model="mistral:7b").data
print(summary)

---

🔗 SSHTool

from npmai_agents import SSHTool

# Remote command
print(SSHTool.run("192.168.1.100", "df -h && uptime").data)

# SFTP upload
SSHTool.upload("192.168.1.100", local="/home/sonu/deploy.sh", remote="/home/ubuntu/deploy.sh")

---

🤖 AgentBrain — The Autonomous Core

This is the main event. Configure your credentials with CredStore, then hand AgentBrain any task in plain English. It uses all 21 tool classes automatically — you never call them yourself.

from npmai_agents import AgentBrain

brain = AgentBrain(
    log_cb=print,                        # receives HTML-formatted log lines
    progress_cb=lambda pct: None,        # 0–100 progress value
    status_cb=lambda s: None             # status string
)

Running Tasks

# The agent plans, codes, audits, executes, verifies — all by itself
brain.run_task("Organise my Downloads folder by file type")

brain.run_task("Email [e-mail] that the build passed")

brain.run_task("Scrape article titles from https://example.com/blog and save to CSV")

brain.run_task("Create a GitHub issue in sonuramashishnpm/npmai: Add voice input")

brain.run_task("Read my last 5 emails and give me a summary")

brain.run_task("Generate a QR code for https://npmai.netlify.app and save it to my Desktop")

brain.run_task("Take a screenshot and upload it to the #dev-logs Slack channel")

Chat Mode

response = brain.chat("What is the LARA RAG architecture?")
print(response)

Kill Switch

import threading

killed = [False]

def run():
    brain.run_task("Process 500 PDFs on the server", killed_flag=killed)

t = threading.Thread(target=run)
t.start()

killed[0] = True   # cancel at any time

Task History

from npmai_agents import AgentBrain

for entry in AgentBrain.load_task_history():
    icon = "✓" if entry["success"] else "✗"
    print(f"{icon} [{entry['time']}]  {entry['task']}")

How AgentBrain accesses all 21 tools

The Coder LLM is given this import context for every code generation call:

from npmai_agents import EmailTool, FileTool, WebTool, SpreadsheetTool
from npmai_agents import GitHubTool, SlackTool, PDFTool, ImageTool
from npmai_agents import SystemTool, TelegramTool, QRTool, RAGTool, SSHTool
from npmai_agents import DiscordTool, WhatsAppTool, NotionTool, TwitterTool
from npmai_agents import SchedulerTool, JiraTool, VoiceTool, WatcherTool
from npmai_agents import CredStore, Workspace

---

🛠️ Executor (Standalone)

from npmai_agents import Executor

executor = Executor(log_cb=print, timeout=120)

success, output = executor.run("""
import time
for i in range(5):
    print(f"Step {i+1}")
    time.sleep(0.5)
""")

print(success, output)
executor.kill()   # kill mid-run if needed

---

📋 Version

Version	Status	Notes
0.0.1	🟡 Alpha	Initial public release — all 21 tools stable

---

📜 License

MIT License — free to use, modify, and distribute.

---

Built with ❤️ by Sonu Kumar · npmai.netlify.app

"Promoting AI tools to every nation's village — free and open forever."