README.md

metadata

title: Grux2
emoji: 🦀
colorFrom: green
colorTo: purple
sdk: gradio
sdk_version: 5.36.2
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480
license: apache-2.0

Grux2 🦀

Grux2 is an advanced, modular, and extensible AI agent framework designed for complex problem-solving and research tasks. It leverages the latest in LLM orchestration (LangChain, LangGraph) and a rich set of tools for web search, code execution, file analysis, and multimodal reasoning. Grux2 is built to run as a Hugging Face Space with OAuth integration, but can also be run locally.

Features

• Adaptive Router Agent: Dynamically selects the best tools and strategies to answer user questions.
• Toolbelt: Includes web search (Google, DuckDuckGo, Tavily), Wikipedia, YouTube transcript, Arxiv, code execution (Python, Bash, SQL, C, Java), file analysis (CSV, Excel, images, PDFs, audio), and more.
• Multimodal Support: Analyze images, audio, and PDFs using state-of-the-art models.
• Safe Web Tools: Rate-limited, secure web and Wikipedia search utilities.
• Configurable and Extensible: Easily add new tools or modify agent behavior.
• OAuth & Hugging Face Integration: Secure login and submission for evaluation tasks.
• Robust Logging & Cleanup: Handles async, signal, and resource cleanup gracefully.

Installation

1. Clone the repository:

   git clone https://huggingface.co/spaces/BladeSzaSza/Grux2
   cd Grux2
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up environment variables:
   • Copy .env.example to .env and fill in your API keys (see Configuration below).

Usage

Local Development

Run the app locally (requires Python 3.9+):

python app.py

As a Hugging Face Space

• Push your repo to Hugging Face Spaces.
• The app will use Gradio Blocks and Hugging Face OAuth for user login and evaluation submission.

Evaluation Workflow

1. Log in with your Hugging Face account.
2. Click "Run Evaluation & Submit All Answers" to fetch questions, run the agent, and submit answers.
3. View your score and results in the UI.

Configuration

Grux2 uses environment variables for API keys and settings. The main configuration options (see src/utils/config.py) include:

• CLAUDE_API_KEY (required, main coordinator): Anthropic Claude API key
• GPT_KEY: OpenAI GPT API key (multimodal Whisper)
• HF_KEY (required): Hugging Face API key
• LANGSMITH_API_KEY: LangSmith tracing (optional)
• GOOGLE_API_KEY: Google Generative AI (for video analysis)
• SCORER_URL: Scoring server URL (default provided)
• LOG_LEVEL: Logging level (default: INFO)

Other settings (see src/utils/config.py):

• Model selection, timeouts, caching, retries, and more.

Toolbelt Overview

The agent can use the following tools (see src/tools/toolbelt.py):

• Web search: Google, DuckDuckGo, Tavily
• Wikipedia (with section search)
• YouTube transcript and video analysis
• Arxiv search
• Code execution: Python, Bash, SQL, C, Java
• File analysis: CSV, Excel, images, PDFs, audio
• Image processing: OCR, drawing, transformations
• Multimodal reasoning (OpenAI, Gemini)

Contributing

Contributions are welcome! To add a new tool or feature:

1. Fork the repo and create a new branch.
2. Add your tool in src/tools/ and register it in src/tools/toolbelt.py.
3. Update the agent logic or prompts as needed.
4. Test your changes locally.
5. Submit a pull request.

License

Apache 2.0

---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference