⚡ Nexus — Multi-Tool Groq AI Agent

A fully agentic AI assistant powered by Groq's ultra-fast LPU inference with a beautiful Streamlit UI.

This agent uses a ReAct (Reason + Act) architecture, allowing it to autonomously decide when to search the web, calculate math, or read local files to answer complex user queries.

🛠️ Tools

Tool	Description
🔍 Web Search	Searches the internet via Google (powered by SerpAPI for rate-limit protection and clean JSON data)
🧮 Calculator	Evaluates math expressions (arithmetic, trig, logs, etc.) in a safe Python namespace
📄 File Reader	Reads local files: .txt, .pdf, .csv, .docx, .py, .json

---

🚀 Setup & Run

1. Clone / copy all files into a folder

nexus-agent/
├── app.py
├── agent.py
├── tools.py
├── requirements.txt
├── .env
└── README.md

2. Install dependencies

Run the following command in your terminal:

pip install -r requirements.txt

3. Add your API keys

Open .env file and replace the placeholder with your actual keys:

GROQ_API_KEY="your_groq_api_key_here"
SERPAPI_KEY="your_serpapi_key_here"

Get a free GROQ API key at: https://console.groq.com Get a free SerpAPI key at: https://serpapi.com (Provides 100 free searches/month to bypass bot blocks)

4. Run the app

streamlit run app.py

The app will open at http://localhost:8501

---

💬 Example Prompts

• "What are the latest developments in AI this week?"
• "Calculate the compound interest on ₹50,000 at 8% for 5 years"
• "Read and summarize my file ./report.pdf"
• "Search for Python async best practices and explain them"
• "What is sqrt(2^20) + log(1000)?"
• "Read ./data.csv and tell me what columns it has"
• "Search the web for the current population of Tokyo, then calculate 15% of that number."

---

🏗️ Architecture

User Input
    │
    ▼
app.py (Streamlit UI)
    │
    ▼
agent.py (Agentic Loop)
    │  ┌─────────────────────────────┐
    ├──► Groq LLM (Llama 4 Scout 17B) │
    │  └─────────────────────────────┘
    │  ┌─────────────────────────────┐
    ├──► web_search                   │  ← SerpAPI (Google Search)
    │  ├─────────────────────────────┤
    ├──► calculator                   │  ← Python math
    │  ├─────────────────────────────┤
    └──► file_reader                  │  ← Local File System
       └─────────────────────────────┘

The agent runs a ReAct loop:

1. Model decides whether to call a tool or answer directly based on the System Prompt.
2. If tool call is needed, it generates a strict JSON payload.
3. The Python backend executes the tool and feeds the result back to the model.
4. This loop repeats up to a safety cap (8 iterations) until a final answer is synthesized.

---

⚙️ Models Available

Nexus uses Groq's 2026 model roster. The recommended model balances context limits, API speed, and strict JSON tool-calling capabilities.

Model	Description
Llama 4 Scout 17B	(Recommended) The "Goldilocks" model. Highly optimized for flawless tool execution, JSON formatting, and high free-tier rate limits
Llama 3.3 70B	Excellent reasoning capabilities, though requires strict schema definitions to avoid XML hallucination
GPT-OSS 120B	Massive parameter count for complex reasoning. (Note: Consumes tokens rapidly; may hit free-tier rate limits during deep ReAct loops)
Qwen3 32B	A fast, highly capable alternative with excellent multilingual and coding support

---

📁 File Structure

• app.py — Streamlit UI, chat display, tool-event expanders, and input handling
• agent.py — Groq client configuration, system prompt, and the core agentic tool-calling loop
• tools.py — Python tool implementations (SerpAPI requests, safe math evalutations, doc parsing)
• .env — API keys (never commit this!)
• requirements.txt — Python dependencies