# ArkAssistant - Hugging Face Agents Course Project

This workspace contains the complete implementation for the **Hugging Face Agents Course (Unit 1 & Unit 2)** project, featuring a Hierarchical Multi-Agent System built with `smolagents`.

## System Architecture

- **`ArkAssistant_Manager`** (`app.py`): Top-level orchestrator agent that parses complex user inquiries and coordinates specialist sub-agents.
  - **`web_researcher`** (`research_agent`): Specialist agent equipped with `web_search`, `search_wikipedia`, and `visit_webpage` for deep web querying and documentation browsing.
  - **`local_info_specialist`** (`local_info_agent`): Specialist agent equipped with `get_weather` and `get_current_time_in_timezone`.
  - **`final_answer` & `image_generation_tool`**: Direct manager tools to conclude inquiries or generate visual images.

## Project Structure

- `app.py`: Main entry point and multi-agent pipeline with Gradio UI.
- `test_agent.py`: Fast CLI test runner for direct queries and tool verification without launching a browser.
- `Gradio_UI.py`: Gradio interface with ZeroGPU compatibility and step-by-step agent visualization.
- `prompts.yaml`: System prompts and agent templates.
- `requirements.txt`: Package dependencies for the agent and Hugging Face Space.
- `README.md`: Space card metadata for Gradio on Hugging Face Spaces.
- `deploy_space.py`: Automated deploy script to upload the workspace to `Ark4u/First_agent_template` on Hugging Face.
- `tools/`: Modular tools:
  - `web_search.py`: DuckDuckGo web search.
  - `visit_webpage.py`: Webpage scraper and markdown converter (`VisitWebpageTool`).
  - `search_wikipedia.py`: Wikipedia REST API lookups.
  - `get_weather.py`: Live weather via wttr.in.
  - `get_current_time_in_timezone.py`: IANA timezone local time converter.
  - `final_answer.py`: Final response delivery tool.

## Environment & Commands

Cloud inference only. `HF_TOKEN` and `MODEL_ID` are configured in `.env`;
local Ollama execution is intentionally disabled. Hugging Face Inference
Providers require available credits or a PRO plan; without them the API returns
HTTP 402 before the agent can start.

- **Create the project virtual environment**:
  ```bash
  uv venv .venv
  uv pip install --python .venv/bin/python -r requirements.txt
  ```

- **Sanity Check All Tools (Fast, No LLM)**:
  ```bash
  .venv/bin/python test_agent.py --test-tools
  ```

- **Run CLI Agent Query**:
  ```bash
  .venv/bin/python test_agent.py "What is the capital of Japan and what is the weather there?"
  ```

- **Run Gradio Web UI Locally**:
  ```bash
  .venv/bin/python app.py
  ```

- **Deploy to Hugging Face Spaces**:
  ```bash
  .venv/bin/python deploy_space.py
  ```