⚡ Nexus Agent

An autonomous AI agent with real tools, real reasoning, and a slick web UI.

Built with the Anthropic API (Claude), Nexus can search the web, execute Python code, evaluate math, check weather, and read/write files — all in one multi-step reasoning loop streamed live to the browser.

---

🎯 What it does

Nexus takes any natural language task and autonomously breaks it into steps, calling the right tools until the job is done:

Tool	Description
🔍 web_search	DuckDuckGo search — no API key needed
🐍 execute_python	Runs arbitrary Python in a sandboxed subprocess
🧮 calculate	Safe math expression evaluator
🌤 get_weather	Live weather via Open-Meteo + Nominatim (free, no key)
📄 read_file / write_file	Read & write files in a local workspace

All tool calls and results stream live to the UI via Server-Sent Events.

---

🚀 Quick Start

1. Clone & install

git clone https://github.com/YOUR_USERNAME/nexus-agent.git
cd nexus-agent
pip install -r requirements.txt

2. Set your API key

cp .env.example .env
# Edit .env and add your Anthropic API key

Or export it directly:

export ANTHROPIC_API_KEY=sk-ant-...

3. Run

python app.py
# Open http://localhost:5000

---

🐳 Docker

docker build -t nexus-agent .
docker run -e ANTHROPIC_API_KEY=sk-ant-... -p 5000:5000 nexus-agent

---

🏗 Architecture

nexus-agent/
├── app.py              # Flask server + SSE streaming endpoint
├── agent/
│   └── core.py         # Autonomous tool-use loop (Anthropic API)
├── tools/
│   ├── registry.py     # Tool schemas + dispatcher
│   ├── web_search.py   # DuckDuckGo search
│   ├── code_exec.py    # Sandboxed Python execution
│   ├── calculator.py   # Safe math eval
│   ├── weather.py      # Open-Meteo weather
│   └── file_ops.py     # Workspace file I/O
├── templates/
│   └── index.html      # Single-page chat UI
├── workspace/          # Agent's file sandbox (gitignored)
├── Dockerfile
└── requirements.txt

Flow:

User message
    ↓
Flask /chat (POST)
    ↓
agent/core.py — Anthropic API with tool_use
    ↓ (loop until end_turn)
tools/registry.py dispatches tool calls
    ↓
Results fed back to Claude
    ↓
SSE stream → browser UI

---

💡 Example queries

• "What's the weather in Mumbai this week?"
• "Write a Python script that generates a fractal and save it to fractal.py"
• "Search for the latest news on large language models"
• "Calculate the present value of $50,000 discounted at 8% over 10 years"
• "Find today's top tech news, summarize it, and save to summary.txt"

---

🔧 Extending Nexus

Adding a new tool takes 3 steps:

1. Create tools/my_tool.py with a function
2. Add the Anthropic schema to tools/registry.py → TOOLS
3. Add a dispatch case in dispatch_tool()

That's it — Claude will automatically decide when to use it.

---

🛡 Security notes

• Python execution runs in a subprocess with a 15-second timeout
• File operations are scoped to ./workspace/ — no path traversal
• Math evaluator uses a whitelist of safe builtins only

---

📄 License

MIT — build on it, ship it, win the hackathon.