Introduction
In this tutorial, we'll explore how to implement a hands-free agent framework similar to NVIDIA's HORIZON, which manages RTL (Register Transfer Level) design problems using Git worktrees. This framework automatically evolves solutions by creating isolated repository versions for each problem iteration. We'll build a simplified version that demonstrates core concepts of versioned problem solving and automated evolution.
Prerequisites
- Basic understanding of Git and Git worktrees
- Python 3.8+ installed
- Git installed on your system
- Basic knowledge of RTL design concepts
- Access to a Linux or macOS environment (Windows support available but requires additional setup)
Step-by-Step Instructions
1. Initialize the Base Repository
First, we'll create a base repository that will serve as our starting point for all RTL problems. This repository will contain our problem definitions and solution templates.
mkdir rtl-agent-framework
cd rtl-agent-framework
git init
Why: This creates our foundational repository structure where all future worktrees will be based. The base repository contains the problem templates and agent logic that will be replicated across worktrees.
2. Create Problem Template Structure
Set up the directory structure for our RTL problems and agent code:
mkdir -p problems/rtl_templates agent
Create a basic problem template in problems/rtl_templates/template.v:
module template (
input clk,
input rst_n,
input [31:0] data_in,
output [31:0] data_out
);
// TODO: Implement your RTL logic here
endmodule
Why: This template represents the standard structure for RTL problems. Each worktree will be a copy of this structure with modifications to solve specific problems.
3. Implement the Agent Logic
Create the core agent logic in agent/agent.py:
import os
import subprocess
import shutil
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
class RTLAgent:
def __init__(self, base_repo_path):
self.base_repo_path = base_repo_path
self.worktree_base = os.path.join(base_repo_path, "worktrees")
os.makedirs(self.worktree_base, exist_ok=True)
def create_worktree(self, problem_id):
"""Create a new worktree for a specific problem"""
worktree_path = os.path.join(self.worktree_base, problem_id)
try:
subprocess.run([
'git', 'worktree', 'add', worktree_path, 'HEAD'
], check=True, cwd=self.base_repo_path)
logger.info(f"Created worktree for problem {problem_id}")
return worktree_path
except subprocess.CalledProcessError as e:
logger.error(f"Failed to create worktree: {e}")
return None
def evolve_solution(self, worktree_path, solution_code):
"""Update the solution in the worktree"""
solution_file = os.path.join(worktree_path, 'problems', 'rtl_templates', 'template.v')
try:
with open(solution_file, 'w') as f:
f.write(solution_code)
logger.info(f"Updated solution in {worktree_path}")
return True
except Exception as e:
logger.error(f"Failed to update solution: {e}")
return False
def commit_worktree(self, worktree_path, message):
"""Commit changes in a worktree"""
try:
subprocess.run([
'git', 'add', '.',
], check=True, cwd=worktree_path)
subprocess.run([
'git', 'commit', '-m', message
], check=True, cwd=worktree_path)
logger.info(f"Committed changes in {worktree_path}")
return True
except subprocess.CalledProcessError as e:
logger.error(f"Failed to commit: {e}")
return False
def get_worktree_status(self, worktree_path):
"""Get the status of a worktree"""
try:
result = subprocess.run([
'git', 'status', '--porcelain'
], capture_output=True, text=True, cwd=worktree_path)
return result.stdout.strip()
except Exception as e:
logger.error(f"Failed to get status: {e}")
return None
Why: This class encapsulates the core functionality of our hands-free agent. It manages worktree creation, solution evolution, and commit operations that mirror the NVIDIA HORIZON framework's approach to problem-solving.
4. Set Up Problem Repository
Initialize a problem repository and add our agent:
git add .
git commit -m "Initial commit with template and agent"
Why: This establishes our base repository state with the agent code and problem templates. This will be the reference point for all worktrees.
5. Create and Test the Agent
Create a test script test_agent.py to demonstrate the agent functionality:
from agent.agent import RTLAgent
# Initialize the agent
agent = RTLAgent('./')
# Create a worktree for problem 1
worktree_path = agent.create_worktree('problem_1')
if worktree_path:
# Define a simple solution
solution = '''
module template (
input clk,
input rst_n,
input [31:0] data_in,
output [31:0] data_out
);
assign data_out = data_in;
endmodule
'''
# Evolve the solution
agent.evolve_solution(worktree_path, solution)
# Commit the changes
agent.commit_worktree(worktree_path, 'Add basic pass-through solution')
# Check status
status = agent.get_worktree_status(worktree_path)
print(f"Worktree status: {status}")
Why: This script demonstrates the complete workflow of creating a worktree, implementing a solution, committing changes, and checking status - mimicking the hands-free evolution process.
6. Run the Agent
Execute the test script to see the agent in action:
python test_agent.pyWhy: Running this script will create a worktree, implement a solution, and commit it, demonstrating the core functionality of our hands-free agent framework.
7. Extend for Benchmark Testing
Modify the agent to support benchmark completion tracking:
class BenchmarkTracker:
def __init__(self):
self.benchmarks = {}
def update_benchmark(self, problem_id, completion):
self.benchmarks[problem_id] = completion
def get_completion_rate(self):
if not self.benchmarks:
return 0
total = sum(self.benchmarks.values())
return total / len(self.benchmarks)
# Integrate into agent
agent.benchmark_tracker = BenchmarkTracker()
Why: This extension allows us to track completion rates across multiple problems, similar to how NVIDIA HORIZON tracks benchmark completion.
Summary
In this tutorial, we've built a simplified hands-free agent framework that mimics the core concepts of NVIDIA's HORIZON system. We've implemented Git worktree management, automated solution evolution, and basic benchmark tracking. While this is a simplified version, it demonstrates the fundamental approach of creating isolated problem-solving environments that can be automatically evolved and tracked. This framework provides a foundation for more complex RTL design automation systems that can solve problems without human intervention, similar to the 100% RTL benchmark completion achieved by NVIDIA's HORIZON.
