🟢 Nvidia-Agent-Core

[!IMPORTANT]

⭐ STAR-WARE LICENSE — MANDATORY NOTICE

This project is licensed under Star-ware. You are required to ⭐ Star this repository before downloading, cloning, or utilizing the source code for any personal or commercial application. This is a legal condition of the license. Continued use without starring constitutes a license violation.

👉 STAR THE REPO NOW

🟢 Nvidia-Agent-Core

Zero-Cost · Open-Source · Autonomous AI Agent Framework

Run powerful, multi-step autonomous AI agents — entirely for free — powered by Nvidia's hosted NIM API.

🚀 Quick Start · 📖 Documentation · 🛠️ Tools · 🤖 Models · 👤 About the Author

🧠 What is Nvidia-Agent-Core?

Nvidia-Agent-Core is a fully plug-and-play, production-ready autonomous AI agent framework that connects to Nvidia's free hosted NIM API catalog.

Unlike cloud AI services that charge per token, Nvidia provides a generous free tier for state-of-the-art open models including Llama 3.3 70B, Qwen 2.5 Coder, and DeepSeek R1 — all accessible through a standard OpenAI-compatible API interface.

This project gives you a complete, working agent system out of the box:

🔁 ReAct Loop — the agent reasons, acts, observes, and iterates autonomously
🛠️ Tool Calling — real tools the agent can invoke (filesystem, calculator, system info, web search stub)
💬 Stateful Conversations — full conversation history maintained across turns
🎨 Beautiful CLI — coloured terminal output, spinner animations, and structured displays
📁 Session Logging — optional JSONL file logs for every session
🔒 Rate-Limit Resilience — automatic exponential back-off on API rate limits

Note

No API keys are bundled. You bring your own free Nvidia NIM API key. Get one in under 60 seconds at build.nvidia.com — no credit card required.

💡 Why This Project?

Capability	Nvidia-Agent-Core	LangChain	AutoGen	CrewAI
Zero external API cost	✅	❌	❌	❌
No framework overhead	✅	❌	❌	❌
Single-file agent core	✅	❌	❌	❌
Plug-and-play setup	✅	Partial	Partial	Partial
OpenAI-compatible	✅	✅	✅	✅
Production-ready code	✅	✅	✅	✅
Beginner-friendly	✅	❌	❌	❌

This project is intentionally dependency-light and beginner-friendly while still being architecturally sound for production extension.

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         main.py (CLI)                               │
│              Interactive loop · Slash commands · Banner             │
└───────────────────────────┬─────────────────────────────────────────┘
                            │  user message
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      agent.py (NvidiaAgent)                         │
│                                                                     │
│   ┌─────────────┐    ┌──────────────┐    ┌────────────────────┐   │
│   │  User Turn  │───▶│  Nvidia NIM  │───▶│  Tool Call Parser  │   │
│   └─────────────┘    │  API (OpenAI │    └────────┬───────────┘   │
│                       │  compatible) │             │               │
│   ┌─────────────┐    └──────────────┘    ┌────────▼───────────┐   │
│   │  Final Text │◀─────────────────────── │   tools.py         │   │
│   │  Response   │    (ReAct iterations)   │   dispatch_tool()  │   │
│   └─────────────┘                        └────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                            │
           ┌────────────────┼────────────────┐
           ▼                ▼                ▼
    config.py          utils.py         tools.py
    (Config)       (Spinner/Logger)   (Tool Registry)

ReAct Loop Flow:

User Input
    │
    ▼
[Append to History]
    │
    ▼
[Call Nvidia NIM API] ◀──────────────────────────────┐
    │                                                │
    ├─── Tool Call(s) requested? ─── YES ───────────┤
    │                                 │             │
    │                          [Dispatch Tools]     │
    │                          [Append Results]     │
    │                          [Continue Loop] ─────┘
    │
    └─── No Tool Calls (final answer) ─── [Return to User]

🤖 Supported Models

All models below are available on Nvidia's free NIM API tier:

Model ID	Strengths	Best For
`meta/llama-3.3-70b-instruct`	🏆 Best overall reasoning	General tasks, analysis, writing
`qwen/qwen2.5-coder-32b-instruct`	💻 Best code generation	Programming tasks, debugging
`deepseek-ai/deepseek-r1`	🧮 Best multi-step reasoning	Math, logic, complex analysis
`nvidia/llama-3.1-nemotron-70b-instruct`	⚡ High quality + speed	Balanced tasks
`mistralai/mixtral-8x7b-instruct-v0.1`	🌐 Multilingual	Non-English tasks

Set your preferred model in .env:

NVIDIA_MODEL=meta/llama-3.3-70b-instruct

Or override at runtime:

python main.py --model qwen/qwen2.5-coder-32b-instruct

🛠️ Available Tools

The agent has access to 6 built-in tools it can invoke autonomously:

Tool	Description	Example Use Case
`system_info`	CPU, RAM, disk, OS, Python version	"How much RAM does my machine have?"
`read_file`	Read any text file from disk	"Read the contents of config.py"
`write_file`	Write or append text to a file	"Create a TODO list in notes.txt"
`list_directory`	List directory contents with metadata	"What files are in my project?"
`calculate`	Safe arithmetic expression evaluator	"What is √(144) + (6 × 7)?"
`web_search_mock`	Simulated web search stub	"Search for Python best practices"

Tip

The web_search_mock tool returns simulated results. To enable live web search, replace its implementation in tools.py with a Tavily, Serper, or SerpAPI integration. All have generous free tiers.

📁 File Structure

nvidia-agent-core/
│
├── 📄 .env.example          Template for environment variables
├── 📄 .gitignore            Git exclusion rules
├── 📄 requirements.txt      Pinned Python dependencies
├── 📄 LICENSE               Star-ware License
│
├── 🐍 config.py             Config management, validation, logging setup
├── 🐍 utils.py              Spinner, file logger, retry decorator, helpers
├── 🐍 tools.py              Tool schemas + implementations + dispatch registry
├── 🐍 agent.py              Core ReAct autonomous execution loop
├── 🐍 main.py               Interactive CLI entry point
│
├── 🖥️  setup.sh             One-click setup (Linux / macOS)
├── 🪟 setup.bat             One-click setup (Windows)
│
└── 📚 README.md             This documentation

🚀 Quick Start

Prerequisites

Python 3.9+ — Download
Free Nvidia NIM API Key — Get it here (no credit card required)
Git — Download

Step 1 — Clone the Repository

Important

⭐ Star the repository first! This is required by the Star-ware license. Click here to star →

git clone https://github.com/appsfordailyuse/nvidia-agent-core.git
cd nvidia-agent-core

Step 2 — One-Click Setup

Linux / macOS:

chmod +x setup.sh
./setup.sh

Windows:

setup.bat

The setup script will:

✅ Check your Python version
✅ Create a virtual environment
✅ Install all dependencies
✅ Create your .env file from the template

Step 3 — Add Your Nvidia API Key

Open the .env file and add your key:

NVIDIA_API_KEY=nvapi-your-key-here

Get your free key: https://build.nvidia.com

Sign up (no credit card required)
Navigate to any model page
Click "Get API Key"
Copy the key (starts with nvapi-)

Step 4 — Run the Agent

# Activate venv (if not already active)
source venv/bin/activate        # Linux/macOS
# venv\Scripts\activate         # Windows

# Start the agent
python main.py

You should see:

  _   _       _     _ _         _                    _      ____
 | \ | |_   _(_) __| (_) __ _  / \   __ _  ___ _ __ | |_   / ___|___  _ __ ___
 ...

  Zero-Cost · Open-Source · Autonomous AI Agent Framework
  v1.0.0  |  Powered by Nvidia NIM Free API
  Built with ❤  by Sami Bajwa  —  samioutic.com
  ──────────────────────────────────────────────────────────────────────────────

  Model   : meta/llama-3.3-70b-instruct
  Max iter: 10
  Logging : Console only

  Type your question and press Enter.  Type /help for commands.

You ❯

⚙️ Configuration Reference

All configuration is done via the .env file (copy from .env.example):

Variable	Default	Required	Description
`NVIDIA_API_KEY`	(none)	✅ Yes	Your Nvidia NIM API key (`nvapi-...`)
`NVIDIA_MODEL`	`meta/llama-3.3-70b-instruct`	❌ No	Model ID to use
`NVIDIA_BASE_URL`	`https://integrate.api.nvidia.com/v1`	❌ No	NIM API base URL
`AGENT_MAX_ITERATIONS`	`10`	❌ No	Max ReAct loop iterations per query
`LOG_LEVEL`	`INFO`	❌ No	Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`ENABLE_FILE_LOGGING`	`false`	❌ No	Set `true` to write JSONL session logs to `./logs/`

📖 Usage Guide

Basic Conversation

You ❯ What is the capital of France?

  ⠋  Iteration 1 …

╔══ Agent Response ════════════════════════════════════════════════════════════
The capital of France is Paris.
╚══ Done  [1.2 s  ·  1 iteration(s)] ═══════════════════════════════════════════

Tool-Calling Example

You ❯ Show me my system information and calculate how many megabytes are in 4 gigabytes

  ⠙  Iteration 1 …

  ⚙  Tool Call  system_info  {}
  ✔  Result  === System Information ===
OS          : Linux 5.15.0 ...

  ⚙  Tool Call  calculate  {"expression": "4 * 1024"}
  ✔  Result  4096

╔══ Agent Response ═══════════════════════════════════════════════════════════
Here is your system information: ...

And 4 gigabytes equals **4096 megabytes**.
╚══ Done  [4.8 s  ·  1 iteration(s)] ══════════════════════════════════════════

Multi-Step Reasoning

You ❯ Read the file requirements.txt, then create a summary.txt file listing 
       each package and its purpose in plain English.

The agent will:

Call read_file("requirements.txt") to get the contents
Reason about each package's purpose
Call write_file("summary.txt", ...) to create the file
Confirm completion with the file size

💻 CLI Commands

Type these directly at the You ❯ prompt:

Command	Description
`/help`	Display all available commands
`/history`	Print the full conversation history
`/reset`	Clear conversation history (keeps system prompt)
`/model`	Display the currently active model
`/tools`	List all registered tools with descriptions
`/clear`	Clear the terminal screen
`/exit` or `/quit`	Exit the agent gracefully

CLI Flags

python main.py --help

options:
  --model MODEL_ID    Override the Nvidia NIM model ID
  --debug             Enable DEBUG-level logging
  --no-log            Disable file logging for this session
  --reset-each-turn   Reset history after every user turn (single-turn mode)

Examples:

# Use the coding-optimised model
python main.py --model qwen/qwen2.5-coder-32b-instruct

# Debug mode with file logging
python main.py --debug

# Single-turn mode (no conversation memory)
python main.py --reset-each-turn

🔧 Extending the Agent

Adding a Custom Tool

Implement the function in tools.py:

def my_custom_tool(param1: str, param2: int = 10) -> str:
    """Your tool implementation."""
    # Do something useful
    return f"Result: {param1} processed {param2} times"

Add the JSON schema to TOOL_SCHEMAS:

{
    "type": "function",
    "function": {
        "name": "my_custom_tool",
        "description": "Clear description of what this tool does and when to use it.",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Description of param1"
                },
                "param2": {
                    "type": "integer",
                    "description": "Description of param2",
                    "default": 10
                }
            },
            "required": ["param1"]
        }
    }
}

Register it in TOOL_REGISTRY:

TOOL_REGISTRY["my_custom_tool"] = my_custom_tool

That's it. The agent will automatically discover and use your tool.

Swapping the Model at Runtime

from config import load_config
from dataclasses import replace
from agent import NvidiaAgent

config = load_config()
config = replace(config, model="deepseek-ai/deepseek-r1")
agent = NvidiaAgent(config=config)
response = agent.run("Solve this step-by-step: ...")

Integrating into Your Own Application

from config import load_config
from agent import NvidiaAgent

config = load_config()
agent = NvidiaAgent(config=config)

# Single turn
response = agent.run("Summarise this text: ...")
print(response)

# Multi-turn conversation
agent.run("My name is Alice.")
agent.run("What is my name?")  # Agent remembers "Alice"

# Reset between sessions
agent.reset()

🔍 Troubleshooting

Warning

Common Issues and Fixes

Problem	Likely Cause	Fix
`CONFIG ERROR: NVIDIA_API_KEY is not set`	Missing `.env` file or empty key	Copy `.env.example` → `.env`, add your key
`CONFIG ERROR: NVIDIA_API_KEY looks invalid`	Key doesn't start with `nvapi-`	Verify key at build.nvidia.com
`ModuleNotFoundError: No module named 'openai'`	venv not activated or deps not installed	Run `source venv/bin/activate` then `pip install -r requirements.txt`
`RateLimitError`	Free tier limits hit	The retry decorator handles this automatically; wait a few seconds
Spinner doesn't render correctly	Windows terminal without ANSI	Use Windows Terminal or VS Code integrated terminal
`PermissionError` on `setup.sh`	Script not executable	Run `chmod +x setup.sh`

Tip

Run with --debug for detailed diagnostics:

python main.py --debug

This shows every API call, tool dispatch, and iteration in full detail.

🗺️ Roadmap

👤 About the Author

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║                     ✦  SAMI BAJWA  ✦                                        ║
║                                                                              ║
║         Visionary AI Educator · Web Developer · Digital Strategist          ║
║              CEO & Founder — Samioutic Digital Agency                       ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

Sami Bajwa is a globally recognised AI educator, full-stack web developer, and digital entrepreneur based in Pakistan. With a relentless passion for democratising access to cutting-edge AI technology, Sami has built one of the most active and practical AI learning communities in the region.

🏆 Achievements & Credentials

Achievement	Details
📚 160+ AI Publications	Author of over 160 free AI short e-books, guides, and custom Claude integration skills engineered to maximise AI potential for everyday users and developers
🎓 Anthropic Academy	Certified in Claude 101, Claude Code in Action, AI Fluency Framework & Foundations, and Introduction to Agent Skills
🏢 Samioutic Digital Agency	CEO & Founder — delivering premium AI-powered web solutions to clients across the UAE, Georgia, UK, and Pakistan
🌍 International Experience	Full-stack projects delivered for clients in Dubai, Tbilisi, London, and across South Asia
👨‍🏫 AI Community Leader	Runs a highly popular Free AI Education WhatsApp Channel with thousands of Pakistani freelancers, students, and entrepreneurs
💼 Digital Entrepreneur	Runs multiple successful businesses including Zam Zam Gas Agency and Daily Bright alongside his digital services

🎯 Mission

"My mission is to make advanced AI accessible, practical, and profitable for every Pakistani developer and entrepreneur — regardless of their budget or background."

— Sami Bajwa

Sami specialises in building production-ready, zero-cost AI integrations that allow individuals and small businesses to compete with enterprise-level AI capability without enterprise-level budgets. This project is a direct expression of that mission.

📬 Connect with Sami

Platform	Link
🌐 Website	www.samioutic.com
💬 Free AI WhatsApp Community	Join 1000s of AI learners →
📘 Facebook	@samibajwaisking
💼 LinkedIn	Samibajwa106
📸 Instagram	@samibajwaisking

Note

🎁 Join Sami's Free AI Education Community

Sami shares daily AI tips, free tools, prompt engineering hacks, and exclusive guides on his WhatsApp channel — all in plain language accessible to beginners.

👉 Join the Free WhatsApp AI Community

Thousands of Pakistani developers and entrepreneurs are already learning and earning with AI. Don't miss out.

📜 License

This project is released under the Star-ware License — a modified MIT License with one additional, mandatory condition:

You must ⭐ Star this repository before using, cloning, forking, or distributing this software in any form.

See the LICENSE file for full details.

Copyright (c) 2025 Sami Bajwa — samioutic.com

Star-ware condition: You must star https://github.com/appsfordailyuse/nvidia-agent-core
before using this software. All other terms follow the standard MIT License.

Built with ❤️ and lots of ☕ by Sami Bajwa

If this project helped you, please consider:

⭐ Starring the repo · 🐛 Reporting bugs · 🤝 Contributing · 📢 Sharing with friends

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
agent.py		agent.py
config.py		config.py
main.py		main.py
requirements.txt		requirements.txt
setup.bat		setup.bat
setup.sh		setup.sh
tools.py		tools.py
utils.py		utils.py

Folders and files

Latest commit

History

Repository files navigation

⭐ STAR-WARE LICENSE — MANDATORY NOTICE

🟢 Nvidia-Agent-Core

Zero-Cost · Open-Source · Autonomous AI Agent Framework

📋 Table of Contents

🧠 What is Nvidia-Agent-Core?

💡 Why This Project?

🏗️ Architecture Overview

🤖 Supported Models

🛠️ Available Tools

📁 File Structure

🚀 Quick Start

Prerequisites

Step 1 — Clone the Repository

Step 2 — One-Click Setup

Step 3 — Add Your Nvidia API Key

Step 4 — Run the Agent

⚙️ Configuration Reference

📖 Usage Guide

Basic Conversation

Tool-Calling Example

Multi-Step Reasoning

💻 CLI Commands

CLI Flags

🔧 Extending the Agent

Adding a Custom Tool

Swapping the Model at Runtime

Integrating into Your Own Application

🔍 Troubleshooting

🗺️ Roadmap

👤 About the Author

🏆 Achievements & Credentials

🎯 Mission

📬 Connect with Sami

🎁 Join Sami's Free AI Education Community

📜 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages