GitHub - scriptstar/AIQ-Wiki-Agent: 🤖 Intelligent Wikipedia research assistant powered by NVIDIA's NeMo Agent Toolkit. Features ReAct reasoning, multiple interfaces (CLI, interactive, Python), and comprehensive examples. Get started in minutes with NVIDIA NIM models.

A comprehensive NVIDIA AIQ-powered intelligent Wikipedia search and research assistant. This repository provides multiple ways to interact with AI agents for knowledge discovery, from simple command-line scripts to interactive interfaces.

📋 Table of Contents

🚀 Quick Start

Clone and setup:

git clone https://github.com/scriptstar/AIQ-Wiki-Agent.git
cd AIQ-Wiki-Agent

Install dependencies:

Get NVIDIA API key from build.nvidia.com and setup environment:

# Copy the example environment file
cp .env.example .env

# Edit .env and add your API key
# Replace 'your_api_key_here' with your actual NVIDIA API key

Run your first query:

./run_agent.sh "List five subspecies of Aardvarks"

📦 Installation

Prerequisites

Python 3.11+ - Required for AIQ toolkit
Git - Version control (installation guide)
uv - Package manager (installation guide)
NVIDIA API Key - Get from build.nvidia.com

Step-by-Step Installation

Install uv (if not already installed):

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Clone the repository:

git clone https://github.com/scriptstar/AIQ-Wiki-Agent.git
cd AIQ-Wiki-Agent

Install dependencies:

Setup environment configuration:

# Copy the example environment file
cp .env.example .env

# Edit the .env file with your favorite text editor
nano .env  # or vim .env, or code .env

# Add your NVIDIA API key (replace the placeholder)

Make scripts executable:

chmod +x run_agent.sh run_interactive.sh

⚙️ Configuration

Environment Variables

The project includes a .env.example file with all configuration options. Copy it to create your environment file:

Then edit .env and add your NVIDIA API key:

# Required: Your NVIDIA API key from https://build.nvidia.com
NVIDIA_API_KEY=nvapi-your-actual-key-here

# Optional: Custom settings (see .env.example for all options)
# LOG_LEVEL=INFO
# DEBUG=true

Key environment variables:

NVIDIA_API_KEY - Required: Your NVIDIA API key from build.nvidia.com
LOG_LEVEL - Optional: Logging level (DEBUG, INFO, WARNING, ERROR)
DEBUG - Optional: Enable debug mode for development

Workflow Configuration

The workflow.yaml file configures your AI agent:

functions:
  # Wikipedia search capability
  wikipedia_search:
    _type: wiki_search
    max_results: 2

llms:
  # NVIDIA NIM LLM configuration
  nim_llm:
    _type: nim
    model_name: meta/llama-3.1-70b-instruct
    temperature: 0.0

workflow:
  # ReAct agent that reasons and acts
  _type: react_agent
  tool_names: [wikipedia_search]
  llm_name: nim_llm
  verbose: true
  parse_agent_response_max_retries: 3

Key Configuration Options:

model_name: Choose from available NVIDIA NIM models
temperature: Control response randomness (0.0 = deterministic)
max_results: Number of Wikipedia search results
verbose: Enable detailed agent reasoning output

🎯 Usage Methods

This project provides multiple ways to interact with your AI agent:

1. 🔥 Simple Shell Script (Recommended)

Basic usage:

./run_agent.sh "Your question here"

With options:

./run_agent.sh --help                                    # Show help
./run_agent.sh -c custom.yaml "Custom config question"  # Custom config
./run_agent.sh -e .env.prod "Production question"       # Custom env file

2. 🎮 Interactive Menu Interface

Features:

Menu-driven interface with pre-defined categories
Quick queries for animals, science, history, technology
Configuration management and help system
Colorized output and error handling

3. ⚡ UV Scripts (Fastest)

# Quick query
uv run ask "What causes climate change?"

# Direct agent command (requires manual question formatting)
uv run agent "Explain quantum computing"

4. 🐍 Python CLI (Most Features)

# Basic usage
uv run python aiq_wiki_agent/cli.py "Your question"

# Interactive mode
uv run python aiq_wiki_agent/cli.py --interactive

# With options
uv run python aiq_wiki_agent/cli.py --verbose --config custom.yaml "Question"

# List available configs
uv run python aiq_wiki_agent/cli.py --list-configs

# Show help
uv run python aiq_wiki_agent/cli.py --help

5. 🛠️ Makefile (Development)

# Basic queries
make run QUESTION="What are renewable energy sources?"
make quick                    # Pre-defined aardvark question

# Interactive modes
make interactive             # Shell-based interactive
make cli-interactive        # Python-based interactive

# Examples
make example-animal         # Animal-related query
make example-science        # Science-related query
make example-history        # Historical query
make example-tech          # Technology query

# Development
make install               # Install dependencies
make test                 # Test with simple query
make status              # Show project status
make debug              # Debug information
make help               # Show all commands

📂 Project Structure

AIQ-Wiki-Agent/
├── 📄 README.md                 # This comprehensive guide
├── ⚙️ workflow.yaml            # AIQ agent configuration
├── 🔐 .env                     # Environment variables (create from .env.example)
├── 📋 .env.example             # Environment template with all options
├── 📦 pyproject.toml           # Python project configuration
├── 🔒 uv.lock                  # Dependency lock file
│
├── 🚀 Scripts & Tools
│   ├── run_agent.sh            # Simple shell script runner
│   ├── run_interactive.sh      # Interactive menu interface
│   └── Makefile               # Development commands
│
├── 🐍 Python Package
│   └── aiq_wiki_agent/
│       ├── __init__.py
│       └── cli.py             # Advanced Python CLI
│
├── 📁 Documentation
│   └── docs/
│       └── FRAMEWORK_GUIDE.md   # Advanced framework guide
│
└── 📁 Generated Files
    └── aiq_wiki_agent.egg-info/ # Package metadata (auto-generated)

Key Files Explained

File	Purpose	When to Modify
`workflow.yaml`	Agent configuration, tools, LLM settings	Change models, add tools, adjust behavior
`.env`	API keys and sensitive config	Add API keys, environment-specific settings
`.env.example`	Environment template and documentation	Add new environment variables or options
`run_agent.sh`	Simple command-line runner	Rarely - it's designed to be generic
`run_interactive.sh`	Menu-driven interface	Add new question categories or options
`aiq_wiki_agent/cli.py`	Advanced Python CLI	Add new CLI features or validation
`Makefile`	Development shortcuts	Add new development commands

🔧 Examples

Animal Research

# Subspecies information
./run_agent.sh "List the subspecies of tigers and their conservation status"

# Habitat and behavior
./run_agent.sh "Describe the hunting behavior and habitat of snow leopards"

# Evolution
./run_agent.sh "Explain the evolutionary history of elephants"

Scientific Queries

# Physics
./run_agent.sh "Explain how quantum entanglement works in simple terms"

# Biology
./run_agent.sh "What are the main stages of cellular respiration?"

# Chemistry
./run_agent.sh "How do catalysts speed up chemical reactions?"

Historical Research

# Events
./run_agent.sh "What were the main causes and effects of the French Revolution?"

# Figures
./run_agent.sh "Describe the contributions of Marie Curie to science"

# Civilizations
./run_agent.sh "What were the key achievements of the ancient Maya civilization?"

Technology Topics

# AI/ML
./run_agent.sh "How do neural networks learn and make predictions?"

# Computing
./run_agent.sh "Explain the difference between RAM and storage memory"

# Internet
./run_agent.sh "How does blockchain technology work?"

Interactive Mode Examples

Using the interactive script:

./run_interactive.sh

# Then select:
# 1 → Custom question → "What causes aurora borealis?"
# 2 → Quick queries → 1 (Animals) → 1 (Subspecies) → "polar bears"
# 2 → Quick queries → 2 (Science) → "photosynthesis"

🐛 Troubleshooting

Common Issues

❌ API Key Not Found

Error: [401] Unauthorized - Authentication failed

Solutions:

Create .env from template: cp .env.example .env
Edit .env and add your NVIDIA API key from build.nvidia.com
Verify API key format starts with nvapi-
Try running: make env-check

❌ Missing Dependencies

ModuleNotFoundError: No module named 'langgraph'

Solutions:

Run uv sync to install all dependencies
Ensure aiqtoolkit-langchain>=1.1.0 is in pyproject.toml
Try: make install

❌ Config File Not Found

Error: Config file 'workflow.yaml' not found

Solutions:

Ensure you're in the project root directory
Check workflow.yaml exists and is properly formatted
Try: make status to verify setup

❌ Permission Denied

bash: ./run_agent.sh: Permission denied

Solutions:

chmod +x run_agent.sh run_interactive.sh

❌ uv Command Not Found

Solutions:

Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
Restart terminal or run: source ~/.bashrc

Debug Commands

# Check environment setup
make env-check

# Show debug information
make debug

# Validate configuration
make validate

# Test with simple query
make test

Getting Help

Script help: ./run_agent.sh --help
Python CLI help: uv run python aiq_wiki_agent/cli.py --help
Makefile help: make help
Interactive help: Run ./run_interactive.sh → Option 4

Performance Tips

Use specific questions for better results
Lower temperature (0.0-0.3) for factual queries
Higher temperature (0.7-1.0) for creative tasks
Increase max_results for more comprehensive Wikipedia searches
Enable verbose mode to see agent reasoning

Environment-Specific Configs

Create multiple environment files for different use cases:

# Development
.env.dev
NVIDIA_API_KEY=dev_key_here

# Production  
.env.prod
NVIDIA_API_KEY=prod_key_here

# Testing
.env.test
NVIDIA_API_KEY=test_key_here

Use with:

./run_agent.sh -e .env.prod "Production query"

🔄 Updates and Maintenance

Updating Dependencies

# Update all dependencies
uv lock --upgrade
uv sync

# Update specific package
uv add "agentiq>=1.2.0" --upgrade

Model Updates

Edit workflow.yaml to change models:

llms:
  nim_llm:
    model_name: meta/llama-3.2-90b-instruct  # Newer model
    temperature: 0.1

Adding New Tools

Check available tools: AIQ Toolkit Documentation
Add to workflow.yaml:

functions:
  wikipedia_search:
    _type: wiki_search
    max_results: 2
  # Add new tool here
  code_search:
    _type: code_execution
    timeout: 30

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Test thoroughly: make test
Submit a pull request

Development Setup

# Install in development mode
uv sync --dev

# Run pre-commit checks (if configured)
make validate

# Test all interfaces
make test
./run_agent.sh "Test query"
./run_interactive.sh

📚 Additional Resources

Project Documentation

Framework Guide: docs/FRAMEWORK_GUIDE.md - Comprehensive guide for building agents from scratch with NeMo Agent Toolkit

External Resources

NVIDIA AIQ Toolkit Documentation: https://docs.nvidia.com/aiqtoolkit/
NVIDIA NIM Models: https://build.nvidia.com
UV Package Manager: https://docs.astral.sh/uv/
LangChain Documentation: https://python.langchain.com/

📄 License

This project is provided as an example for educational and development purposes.

🎉 Happy AI Agent Research!

If you encounter any issues or have suggestions for improvements, please open an issue or contribute to the project.