Metadata-Version: 2.4
Name: npmai_agents
Version: 0.0.1
Summary: A production-grade AI agent framework with 21 integrated tool classes and a four-role autonomous LLM pipeline — built on the NPMAI ECOSYSTEM.
Author-email: Sonu Kumar <sonuramashishnpm@gmail.com>
License: MIT
Project-URL: Homepage, https://npmai.netlify.app
Project-URL: Documentation, https://npmai.netlify.app
Project-URL: Repository, https://github.com/sonuramashishnpm/npmai-agents
Project-URL: Bug Tracker, https://github.com/sonuramashishnpm/npmai-agents/issues
Project-URL: PyPI, https://pypi.org/project/npmai_agents
Keywords: ai,agent,automation,llm,npmai,npmai-ecosystem,desktop-automation,multi-agent,rag,open-source,email-automation,file-automation,github-automation,agentic-ai,free-llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: npmai>=0.1.9
Requires-Dist: requests>=2.31.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: langchain-core>=0.1.0
Provides-Extra: full
Requires-Dist: beautifulsoup4>=4.12.0; extra == "full"
Requires-Dist: playwright>=1.40.0; extra == "full"
Requires-Dist: PyGithub>=2.1.0; extra == "full"
Requires-Dist: slack-sdk>=3.23.0; extra == "full"
Requires-Dist: gspread>=5.12.0; extra == "full"
Requires-Dist: google-auth>=2.23.0; extra == "full"
Requires-Dist: openpyxl>=3.1.0; extra == "full"
Requires-Dist: pandas>=2.1.0; extra == "full"
Requires-Dist: Pillow>=10.0.0; extra == "full"
Requires-Dist: pypdf>=3.17.0; extra == "full"
Requires-Dist: python-docx>=1.1.0; extra == "full"
Requires-Dist: pyttsx3>=2.90; extra == "full"
Requires-Dist: SpeechRecognition>=3.10.0; extra == "full"
Requires-Dist: pyperclip>=1.8.2; extra == "full"
Requires-Dist: schedule>=1.2.0; extra == "full"
Requires-Dist: psutil>=5.9.0; extra == "full"
Requires-Dist: watchdog>=3.0.0; extra == "full"
Requires-Dist: tweepy>=4.14.0; extra == "full"
Requires-Dist: pywhatkit>=5.4; extra == "full"
Requires-Dist: qrcode>=7.4.2; extra == "full"
Requires-Dist: paramiko>=3.3.0; extra == "full"
Requires-Dist: python-dotenv>=1.0.0; extra == "full"
Requires-Dist: pyautogui>=0.9.54; extra == "full"
Requires-Dist: opencv-python>=4.8.0; extra == "full"
Requires-Dist: pytesseract>=0.3.10; extra == "full"
Requires-Dist: yt-dlp>=2023.11.16; extra == "full"
Requires-Dist: discord.py>=2.3.2; extra == "full"
Requires-Dist: telethon>=1.32.0; extra == "full"
Requires-Dist: notion-client>=2.2.1; extra == "full"
Requires-Dist: todoist-api-python>=2.1.3; extra == "full"
Requires-Dist: jira>=3.5.2; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

<div align="center">

<!-- ANIMATED BANNER -->
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:0a0a1a,50:1a0a3a,100:0d1b4a&height=200&section=header&text=npmai_agents&fontSize=72&fontColor=00f5ff&fontAlignY=38&desc=The%20Autonomous%20AI%20Agent%20Suite%20by%20NPMAI%20ECOSYSTEM&descColor=a78bfa&descAlignY=60&animation=twinkling" width="100%"/>

<!-- ANIMATED TYPING HEADLINE -->
<a href="https://npmai.netlify.app">
  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=22&duration=3000&pause=1000&color=00F5FF&center=true&vCenter=true&multiline=false&width=700&lines=21+Integrated+Tool+Classes.+Zero+Paid+APIs.;Plan+%E2%86%92+Code+%E2%86%92+Audit+%E2%86%92+Execute+%E2%86%92+Verify;Built+free%2C+open-source%2C+for+everyone.;Powered+by+NPMAI+ECOSYSTEM+%F0%9F%9A%80" alt="Typing SVG" />
</a>

<br/>

<!-- BADGES ROW 1 -->
<p>
  <img src="https://img.shields.io/badge/PyPI-npmai__agents-00f5ff?style=for-the-badge&logo=pypi&logoColor=white&labelColor=0a0a1a"/>
  <img src="https://img.shields.io/badge/Version-0.0.1-a78bfa?style=for-the-badge&labelColor=0a0a1a"/>
  <img src="https://img.shields.io/badge/Python-3.9%2B-00f5ff?style=for-the-badge&logo=python&logoColor=white&labelColor=0a0a1a"/>
  <img src="https://img.shields.io/badge/License-MIT-2affa0?style=for-the-badge&labelColor=0a0a1a"/>
</p>

<!-- BADGES ROW 2 -->
<p>
  <img src="https://img.shields.io/badge/Tools-21%20Classes-ff6b9d?style=for-the-badge&labelColor=0a0a1a"/>
  <img src="https://img.shields.io/badge/LLMs-45%2B%20Free-a78bfa?style=for-the-badge&labelColor=0a0a1a"/>
  <img src="https://img.shields.io/badge/NPMAI-ECOSYSTEM-00f5ff?style=for-the-badge&labelColor=0a0a1a&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgc3Ryb2tlPSIjMDBmNWZmIiBzdHJva2Utd2lkdGg9IjIiLz48L3N2Zz4="/>
  <img src="https://img.shields.io/badge/Status-Alpha-ffb347?style=for-the-badge&labelColor=0a0a1a"/>
</p>

<br/>

<!-- QUICK LINKS NAV -->
**[`🌐 Website`](https://npmai.netlify.app)** · **[`📦 PyPI`](https://pypi.org/project/npmai_agents)** · **[`🐙 GitHub`](https://github.com/sonuramashishnpm)** · **[`📖 Docs`](#-documentation)** · **[`🤝 Community`](https://npmai.netlify.app)**

</div>

---


## ✦ 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**.

```python
pip install npmai_agents
```

```python
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

<div align="center">

<img src="https://capsule-render.vercel.app/api?type=rect&color=0:0a0a1a,100:1a0a3a&height=3&section=header" width="60%"/>

</div>

**`npmai_agents`** is an official product of the **[NPMAI ECOSYSTEM](https://npmai.netlify.app)** — a free, open-source AI research and development platform serving developers and researchers worldwide.

<table>
<tr>
<td width="50%">

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

</td>
<td width="50%">

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

</td>
</tr>
</table>

<div align="center">

[![GitHub](https://img.shields.io/badge/GitHub-sonuramashishnpm-0a0a1a?style=flat-square&logo=github&logoColor=00f5ff)](https://github.com/sonuramashishnpm)
[![PyPI](https://img.shields.io/badge/PyPI-npmai-0a0a1a?style=flat-square&logo=pypi&logoColor=a78bfa)](https://pypi.org/project/npmai)
[![Website](https://img.shields.io/badge/Website-npmai.netlify.app-0a0a1a?style=flat-square&logo=netlify&logoColor=2affa0)](https://npmai.netlify.app)
[![Email](https://img.shields.io/badge/Email-sonuramashishnpm%40gmail.com-0a0a1a?style=flat-square&logo=gmail&logoColor=ff6b9d)](mailto:sonuramashishnpm@gmail.com)

</div>

---

## ⚡ 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

<div align="center">

```
┌─────────────────────────────────────────────────────────────────────┐
│                    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     ║             │
│   ╚══════════════╝  ╚══════════════╝  ╚══════════════╝             │
└─────────────────────────────────────────────────────────────────────┘
```

</div>

- 🔧 **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

<div align="center">

```
                    ╔═══════════════════════╗
     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.

</div>

---

## 📦 Installation

```bash
pip install npmai_agents
```

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

```bash
pip install npmai_agents[full]
```

**Import styles:**

```python
# 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.

```python
from npmai_agents import CredStore

# ── Save credentials ──────────────────────────────────────────────────
CredStore.save("gmail", {
    "email":     "you@gmail.com",
    "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":     "you@company.com",
    "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

```python
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

```python
from npmai_agents import EmailTool

# Send a single email
result = EmailTool.send(
    to="friend@example.com",
    subject="Hello from npmai_agents",
    body="<h1>Sent by an AI agent!</h1>"
)
print(result)   # ✓ Email sent to friend@example.com

# With attachments
result = EmailTool.send(
    to="boss@company.com",
    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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
from npmai_agents import WhatsAppTool

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

---

### 📝 NotionTool

```python
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

```python
from npmai_agents import TwitterTool

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

---

### ⚙️ SystemTool

```python
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

```python
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

```python
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

```python
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

```python
from npmai_agents import TelegramTool

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

---

### 📷 QRTool

```python
from npmai_agents import QRTool

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

---

### 🎤 VoiceTool

```python
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

```python
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

```python
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

```python
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.

```python
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

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

brain.run_task("Email team@company.com 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

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

### Kill Switch

```python
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

```python
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:

```python
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)

```python
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

<div align="center">

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

</div>

---

## 📜 License

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

---

<div align="center">

<img src="https://capsule-render.vercel.app/api?type=waving&color=0:1a0a3a,50:0a0a1a,100:0d1b4a&height=120&section=footer&text=NPMAI+ECOSYSTEM&fontSize=28&fontColor=00f5ff&fontAlignY=65&desc=Open+Source+AI+Research+%26+Development+%C2%B7+Free+Forever&descColor=a78bfa&descSize=14&descAlignY=85" width="100%"/>

**Built with ❤️ by [Sonu Kumar](https://github.com/sonuramashishnpm) · [npmai.netlify.app](https://npmai.netlify.app)**

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

</div>
