Add: beginner-friendly file analyzer example

[itsroshanharry]

Description

Add a beginner-friendly file analyzer example to help new users understand HUD SDK core concepts.

Problem

Currently, the examples jump from very basic (00_agent_env.py - just one tool call) to advanced production-ready agents (01_codex, 02_opencode). There's no intermediate example for beginners learning the SDK.

Solution

This example fills that gap by demonstrating:

• Creating environments with custom tools (@env.tool())
• Defining evaluation scenarios (@env.scenario())
• Running agents with different models
• Understanding automatic tool usage
• Reward-based evaluation

Why This Is Valuable

1. Fills a gap: Provides progression path from basic to advanced
2. Beginner-friendly: Uses simple, relatable tools (file operations)
3. Educational: Extensive comments and helpful output explaining what happened
4. Complete: Shows full workflow from setup to evaluation
5. Flexible: Includes command-line options for different models

Example Output

======================================================================
FILE ANALYZER AGENT
======================================================================

🤖 Model: gpt-4o-mini
📋 Task: Analyze README.md file
🔧 Tools: list_files, read_file, count_words

======================================================================

✅ Task completed!
📊 Reward: 1.0
🔢 Steps taken: 0

📝 Agent's response:
The **README.md** file exists, and here are the details:
- **Word Count:** 70 words
- **Lines:** 14
- **Characters:** 1000
- **Average Word Length:** 14.3 characters

Testing

• Tested with gpt-4o-mini (default)
• Tested with gpt-4o
• Verified all tools work correctly
• Confirmed evaluation scenario works
• Checked code formatting with ruff format
• Verified linting with ruff check
• Added documentation to examples/README.md

Checklist

• Code follows project style guidelines
• Added documentation to examples/README.md
• Tested the example works
• Includes clear usage instructions
• Has helpful comments and docstrings
• Includes shebang and proper imports
• Follows existing example patterns

Additional Context

This is my first contribution to the HUD SDK. I created this example while learning the framework and thought it would help other beginners understand the core concepts. The example is self-contained and doesn't modify any existing code.

I'm excited to contribute to the project and help make it more accessible to new users!

---

Note

Low Risk
Adds a new standalone example script and documentation without modifying library/runtime code; risk is limited to example usability (e.g., path handling and tool output).

Overview
Adds a new beginner example examples/05_file_analyzer_agent.py that defines simple file tools (list_files, read_file, count_words), an analyze-readme scenario with basic reward scoring, and a CLI to run the agent against different models.

Updates examples/README.md to document how to run the new example (including --model and --verbose) and position it as an intermediate learning step.

^{Written by Cursor Bugbot for commit c8923aa. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}