ISLAM-PO/alfred-gala-agent

Alfred - Gala Host Agent (Agentic RAG Use Case)

Unit 3 - Use Cases project for the Hugging Face AI Agents Course.

Alfred is an AI agent that helps host an extravagant gala. He can look up guest information, check the weather for outdoor events (e.g. fireworks), search the web for up-to-date facts, and report Hugging Face Hub model statistics. The project demonstrates Agentic RAG (Retrieval-Augmented Generation) plus tool use across three frameworks: smolagents, LangGraph, and LlamaIndex.

Table of Contents

• Overview
• Project Structure
• Tools
• Quick Start
• Usage Examples
• Frameworks
• Configuration
• Limitations
• License

Overview

Traditional RAG pipelines retrieve documents and feed them to an LLM in a single step. Agentic RAG gives the agent control over when and how to retrieve, and lets it combine retrieval with other tools (web search, weather, Hub stats). Alfred is built around a small guest dataset (data/guests.json) and three auxiliary tools.

Project Structure

alfred_gala/
├── README.md               # This file
├── requirements.txt        # Python dependencies
├── data/
│   └── guests.json         # Gala guest list (name, relation, description, email)
├── tools.py                # DuckDuckGoSearchTool, WeatherInfoTool, HubStatsTool, GuestInfoTool
├── retriever.py            # Guest-info retrieval tool builder
├── agent.py                # smolagents CodeAgent (primary)
├── agent_langgraph.py      # LangGraph StateGraph variant
├── agent_llamaindex.py     # LlamaIndex AgentWorkflow variant (reference)
└── app.py                  # Gradio chat demo (local run)

Tools

Tool	Description
guest_info	Look up a guest by name; returns relation, description, email.
weather_info	Mock forecast for a city (condition + temperature).
hub_stats	Most-downloaded model on the Hugging Face Hub for an author/org.
web_search	DuckDuckGo search (title, snippet, url).

Quick Start

1. Clone / download

git clone https://huggingface.co/ISLAM-PO/alfred-gala-agent
cd alfred-gala-agent

2. Install dependencies

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

3. Set your Hugging Face token

# Windows (PowerShell)
$env:HF_TOKEN = "hf_..."
# macOS / Linux
export HF_TOKEN="hf_..."

The token needs inference.serverless.write (and repo.read for Hub stats).

4. Run Alfred (smolagents)

python agent.py

5. (Optional) Run the Gradio demo

python app.py

Then open the local URL printed in the terminal.

Usage Examples

from agent import build_alfred

alfred = build_alfred()

# Guest lookup
print(alfred.run("Tell me about 'Lady Ada Lovelace'."))

# Weather check for fireworks
print(alfred.run("What's the weather like in Paris tonight? "
                 "Will it be suitable for our fireworks display?"))

# Hub stats for an AI lab
print(alfred.run("One of our guests is from Qwen. "
                 "What can you tell me about their most popular model?"))

# Multi-tool planning
print(alfred.run("I need to speak with Dr. Nikola Tesla about recent "
                 "advancements in wireless energy. Can you help me prepare?"))

Expected (illustrative) output for the guest lookup:

🎩 Alfred's Response:
Based on the information I retrieved, Lady Ada Lovelace is an esteemed mathematician
and friend. She is renowned for her pioneering work in mathematics and computing,
often celebrated as the first computer programmer due to her work on Charles
Babbage's Analytical Engine. Her email address is ada.lovelace@example.com.

Frameworks

The same toolset is implemented in three frameworks so you can compare them:

Framework	File	Notes
smolagents (primary)	agent.py	CodeAgent with planning_interval=3.
LangGraph	agent_langgraph.py	StateGraph with ToolNode and tools_condition.
LlamaIndex	agent_llamaindex.py	Reference implementation following the course (requires llama-index).

Install the optional framework dependencies as needed:

pip install llama-index llama-index-llms-huggingface-api  # for LlamaIndex variant

Configuration

Environment variable	Required	Description
HF_TOKEN / HUGGINGFACEHUB_API_TOKEN	Yes	Hugging Face token with inference + Hub read access.
MODEL_ID	No	Override the default LLM (Qwen/Qwen2.5-Coder-32B-Instruct).

Limitations

• weather_info returns mock data (no real weather API). Swap in a real provider (e.g. OpenWeatherMap) for production.
• hub_stats requires network access to the Hugging Face Hub.
• The guest list is small and static (data/guests.json); replace it with your own dataset for a real event.
• Gradio Spaces on the free tier do not support the Gradio SDK; run app.py locally or use a Docker Space.

License

MIT License. See LICENSE.

Acknowledgements

Built as the Unit 3 use-case assignment of the Hugging Face AI Agents Course, following the official "Agentic RAG" unit. Guest data sourced from agents-course/unit3-invitees.