npmai-agent

<div align="center"> <img src="https://capsule-render.vercel.app/api?type=waving&color=0:0a0a1a,30:0d0d2b,60:1a0a3a,100:0d1b4a&height=240&section=header&text=npmai_agents&fontSize=82&fontColor=00f5ff&fontAlignY=38&desc=1%2C371%20Tools.%20100%20Classes.%20One%20Package.%20Zero%20Cost.&descColor=a78bfa&descAlignY=60&animation=twinkling" width="100%"/> <a href="https://npmai.netlify.app"> <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&duration=2500&pause=800&color=00F5FF&center=true&vCenter=true&multiline=false&width=800&lines=1%2C371+verified+tools+across+100+classes;5-role+autonomous+LLM+pipeline+%E2%86%92+Plan+%E2%86%92+Select+%E2%86%92+Code+%E2%86%92+Audit+%E2%86%92+Verify;12+LLM+providers+%E2%80%94+NPMAI%2C+OpenAI%2C+Groq%2C+Anthropic%2C+Gemini+%26+more;Built+by+Sonu+Kumar+%C2%B7+NPMAI+ECOSYSTEM+%C2%B7+Free+Forever" alt="Typing SVG"/> </a> <br/> <br/> <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-1.0.2-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"/> <img src="https://img.shields.io/badge/Status-Production%20Stable-2affa0?style=for-the-badge&labelColor=0a0a1a"/> <br/> <img src="https://img.shields.io/badge/Tools-1%2C371-ff6b9d?style=for-the-badge&labelColor=0a0a1a"/> <img src="https://img.shields.io/badge/Classes-100-a78bfa?style=for-the-badge&labelColor=0a0a1a"/> <img src="https://img.shields.io/badge/LLM%20Roles-5-00f5ff?style=for-the-badge&labelColor=0a0a1a"/> <img src="https://img.shields.io/badge/LLM%20Providers-12-ff6b9d?style=for-the-badge&labelColor=0a0a1a"/> <img src="https://img.shields.io/badge/NPMAI-ECOSYSTEM-00f5ff?style=for-the-badge&labelColor=0a0a1a"/> <br/> <br/>

🌐 Website · 📦 PyPI · 🐙 GitHub · 👤 Founder .

</div>

---

✦ What is npmai_agents?

npmai_agents is a production-grade, open-source autonomous AI agent framework with 1,371 verified tools across 100 classes — the largest open-source local tool registry ever built. A 5-role LLM pipeline (Planner → Tool Manager → Coder → Auditor → Verifier) autonomously executes any plain-English task on your computer using 12 supported LLM providers including NPMAI free LLMs, OpenAI, Groq, Anthropic, Gemini, and more.

The core insight: LLMs waste most of their context reverse-engineering API documentation instead of solving your actual problem. Every class in npmai_agents ships a use variable — pre-compiled, structured tool knowledge that the pipeline reads on-demand. The Planner sees a one-line index of all 100 classes. The Tool Manager drills into full documentation only for classes the task actually needs. The Coder receives exact method signatures and call examples. Zero hallucination on API shapes. Maximum intelligence on task logic.

---

🏛️ NPMAI ECOSYSTEM

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

npmai_agents is a product of the NPMAI ECOSYSTEM — a free, open-source AI research and development platform founded by Sonu Kumar (Bihar Viral Boy), a 15-year-old self-taught AI developer, TEDx Speaker, and constitutional researcher from Bihar, India.

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

| Metric | Value | |---|---| | PyPI Downloads | | | Daily Requests | 80,000+ | | Free LLMs | 45+ | | Monthly Cost | ₹0 |

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

| Metric | Value | |---|---| | PyPI Downloads | | | Tools | 1,371 |

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

---

⚡ Installation

# Minimal — agent auto-installs tool dependencies at runtime
pip install npmai_agents

# Full — all 1,371 tool dependencies pre-installed
pip install npmai_agents[full]

Quick Start

# Pull the image
docker pull sonuramashishnpm/npmai-agent:latest

# See available commands
docker run --rm sonuramashishnpm/npmai-agent --help

# Run any task
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  sonuramashishnpm/npmai-agent run "Analyze my sales.csv and create a revenue report"

Tags

• latest — Latest stable version
• v1 — Version 1.0.1

📦 Import System

All 100 tool classes, every LLM backend, and the agent brain itself are exposed from a single top-level namespace: npmai_agents. Internally the code is split across many files by domain (core.py, agent_core.py, Tools_business.py, Tools_creative.py, etc.) — that split is for maintainability on our side. As a user you never need to know or care which file anything actually lives in. The package's __init__.py re-exports every public class at the top level, so a single import line reaches everything:

# Agent brain only
from npmai_agents import AgentBrain

# Specific tools, no matter which internal file they live in
from npmai_agents import StripeTool, GitHubTool, FFmpegTool

# LLM backends
from npmai_agents import GroqBackend, OpenAIBackend, AnthropicBackend

# Core infra
from npmai_agents import CredStore, Workspace, LLMBackend

# Everything at once (not recommended for large projects — namespace gets crowded)
from npmai_agents import *

You will never need to write from Tools_business import StripeTool or from core import LLMBackend yourself — those are internal file paths used only inside the package's own source code. Every public class, from every file, is reachable directly via from npmai_agents import <ClassName>.

---

🖥️ CLI — Complete Reference

Install gives you the npmai terminal command globally.

npmai --help

🛠️ Troubleshooting: CLI Command Not Found (PATH Issue)

If you get a warning during installation stating that the script is installed in a directory which is not on PATH, your terminal will not recognize the command. Follow the solution for your operating system below.

---

🪟 On Windows

If you see a warning referencing AppData\Roaming\Python\...

Solution: Open PowerShell as an Administrator and run:

[Environment]::SetEnvironmentVariable("Path", \$env:Path + ";C:\Users\digiccsammunnat8\AppData\Roaming\Python\Python312\Scripts", "User")

Note: Restart your terminal window after running this command.

---

🐧 On Linux

If you see a warning referencing ~/.local/bin

Solution: Open your terminal and run:

echo 'export PATH="HOME/.local/bin:PATH"' >> ~/.bashrc && source ~/.bashrc

Note: If you use Zsh instead of Bash, replace ~/.bashrc with ~/.zshrc.

---

🍏 On macOS

If you see a warning referencing ~/Library/Python/...

Solution: Open your terminal and run (replace 3.12 with your actual Python version):

echo 'export PATH="HOME/Library/Python/3.12/bin:PATH"' >> ~/.zshrc && source ~/.zshrc

Note: If you use Bash instead of Zsh on older macOS versions, replace ~/.zshrc with ~/.bash_profile.

---

💡 Pro Tip: Avoid PATH Issues Entirely

Use a virtual environment for your project so dependencies and paths are isolated automatically:

# Create and activate the environment
python -m venv venv
source venv/bin/activate  # On Windows PowerShell use: .\venv\Scripts\activate

# Install your package cleanly
pip install npmai-agents

Session model: each npmai <command> invocation is its own standalone process — there is no config file, no state file, and nothing written to disk between commands (by design, so the framework never has to manage extra files on top of everything else it already manages). This means run and chat accept the LLM provider/model for every role directly as flags on the same call, rather than relying on a separate "configure once" step that would silently reset between processes anyway. If you omit the flags, every role defaults to the free NPMAI-hosted models — zero setup, zero cost.

---

npmai run — Execute Any Task

Runs a plain-English task through the full 5-role autonomous pipeline. LLM provider/model for each role can be set per-call; anything left unset falls back to the NPMAI free-tier default for that role.

| Parameter | Type | Default | Required | Description | |---|---|---|---|---| | task | str | — | ✅ | Plain-English description of what to do | | --planner-model | str | llama3.2:3b | ❌ | Model for the Planner role | | --planner-provider | str | npmai | ❌ | Provider for the Planner role | | --tool-manager-provider | str | npmai | ❌ | Provider for Tool_Manager role who select tools | | --tool-manager-model | str | npmai | ❌ | Model for Tool_Manager role who select tools | | --coder-model | str | codellama:7b-instruct | ❌ | Model for the Coder role | | --coder-provider | str | npmai | ❌ | Provider for the Coder role | | --auditor-model | str | qwen2.5-coder:7b | ❌ | Model for the Auditor role | | --auditor-provider | str | npmai | ❌ | Provider for the Auditor role | | --verifier-model | str | llama3.2:3b | ❌ | Model for the Verifier role | | --verifier-provider | str | npmai | ❌ | Provider for the Verifier role | | --chatter-model | str | granite3.3:2b | ❌ | Model for the Chatter role | | --chatter-provider | str | npmai | ❌ | Provider for the Chatter role |

# Zero-config — all roles run on free NPMAI models
npmai run "Scrape the top 10 AI papers from arXiv today, summarise each in 3 sentences, save to Excel, and email it to me"

npmai run "Find all duplicate files in my Downloads folder and delete them"

# Mixing providers per role — Groq for planning/coding, defaults for the rest
npmai run "Pull latest from my GitHub repo, run the tests, and post results to Slack #dev" \
  --planner-provider groq --planner-model llama-3.3-70b-versatile \
  --coder-provider groq --coder-model llama-3.3-70b-versatile

npmai run "Create a Stripe customer for john@example.com and generate an invoice for 5000 rupees" \
  --auditor-provider anthropic --auditor-model claude-sonnet-4-6

Output: Streamed logs showing each pipeline stage — Planning → Tool Selection → Code Generation → Security Audit → Execution → Verification. Final ✓ All steps completed successfully on success.

Provider Reference (same values work for every --*-provider flag above):

| Provider | --*-provider value | Example model | Save credentials first | |---|---|---|---| | NPMAI Free | npmai | llama3.2:3b | Not required | | Local Ollama | local | llama3.2:3b | Not required | | OpenAI | openai | gpt-4o | npmai save-credentials openai '{"api_key":"sk-xxx"}' | | Groq | groq | llama-3.3-70b-versatile | `npmai save-