sigmantic 0.1.0

Sigmantic AI CLI - Intelligent RTL code generation with Claude and workspace management

Sigmantic AI CLI

An intelligent CLI tool for RTL (Register Transfer Level) code generation that follows an agentic workflow with workspace-based project management inspired by the Claude Agent SDK:

1. Workspace Management: Every session starts with workspace creation/attachment
2. Planning Phase: Structured todo planning with RTL specifications
3. Verification First: Generates comprehensive testbenches before RTL code
4. Iterative RTL Generation: Creates and refines RTL code using Verilator feedback
5. Self-Explanation: Documents and explains the generated code functionality

Features

• 🏗️ Workspace-Based Projects: Claude Agent SDK-inspired project structure
• 🤖 Agentic Workflow: AI-driven planning and execution
• 🧪 Verification-First Approach: Testbenches generated before implementation
• 🔄 Iterative Refinement: Uses Verilator feedback to improve code quality
• 📝 Self-Documenting: Explains generated code and design decisions
• 🎯 RTL-Focused: Specialized for hardware description languages (Verilog/SystemVerilog)
• 🛠️ Tool Integration: Built-in Verilator integration for compilation and verification
• 📊 Rich CLI Interface: Beautiful terminal interface with progress tracking
• 🔍 File System Context: Uses workspace structure for agent context management

Quick Start

1. Setup:

   ./setup.sh
   

2. Configure:

   cp env.example .env
   # Edit .env and add your Anthropic API key to key.cfg
   

3. Create your first RTL project:

   sigmantic "Create a 32-bit ALU with add, subtract, and, or operations"
   # The system will prompt you to create or attach to a workspace
   

Workspace Management

Workspace Structure

Each RTL project workspace follows the Claude Agent SDK pattern:

my_rtl_project/
├── CLAUDE.md                    # Project context for Claude
├── .claude/                     # Agent configuration
│   ├── settings.json           # Project settings
│   ├── agents/                 # Specialized RTL agents
│   │   ├── rtl_designer.md     # RTL design specialist
│   │   └── verification_specialist.md
│   └── commands/               # Custom slash commands
│       ├── simulate.md         # /simulate command
│       └── lint.md            # /lint command
├── rtl/                        # Generated RTL modules
├── testbenches/                # Verification testbenches  
├── docs/                       # Design documentation
└── sim/                        # Simulation results

Workspace Commands

# List available workspaces
sigmantic --list-workspaces

# Show current workspace info
sigmantic --workspace-info

# Generate RTL in a specific workspace
sigmantic "Create a FIFO" --workspace /path/to/workspace

Installation

Option 1: Install from PyPI (Recommended)

pip install sigmantic

Option 2: Install from Source

git clone https://github.com/sigmantic-ai/sigmantic-cli.git
cd sigmantic-cli
pip install -e .

Option 3: Quick Setup Script

git clone https://github.com/sigmantic-ai/sigmantic-cli.git
cd sigmantic-cli
./install.sh

Configuration

After installation, configure your API key:

# Create config directory
mkdir -p ~/.sigmantic

# Add your Anthropic API key
echo "ANTHROPIC_API_KEY=your_api_key_here" > ~/.sigmantic/key.cfg

Verify Installation

sigmantic --help
sigmantic --list-workspaces

Usage

Basic Usage

python3 rtl_agent.py "Your RTL design description"

Options

• --non-interactive, -n: Run without interactive prompts
• --workspace, -w: Specify workspace directory (default: ./workspace)
• --help: Show help message

Examples

# Simple counter
python3 rtl_agent.py "Create an 8-bit up counter with enable and reset"

# ALU design
python3 rtl_agent.py "Design a 16-bit ALU supporting add, subtract, AND, OR"

# FIFO buffer
python3 rtl_agent.py "Implement a synchronous FIFO with 32-bit width and 16 entries"

# State machine
python3 rtl_agent.py "Create a traffic light controller state machine"

Interactive Examples

python3 examples.py

Workflow Details

1. Planning Phase

• Analyzes user requirements
• Creates structured task breakdown
• Defines RTL specification (inputs, outputs, parameters)
• Plans verification strategy

2. Verification Phase

• Generates comprehensive testbench
• Creates test cases for all scenarios
• Defines coverage goals
• Explains verification strategy

3. RTL Generation Phase

• Generates initial RTL code
• Compiles with Verilator
• Iteratively fixes compilation errors
• Runs verification tests
• Optimizes based on feedback

4. Explanation Phase

• Documents design decisions
• Explains code functionality
• Creates comprehensive documentation
• Highlights key learning points

Architecture

SigmanticAICLi/
├── rtl_agent.py           # Main CLI interface
├── models.py              # Data models and types
├── verilator_utils.py     # Verilator integration
├── agents/                # Individual agent modules
│   ├── planning_agent.py      # Task planning and specification
│   ├── verification_agent.py  # Testbench generation
│   ├── rtl_generation_agent.py # RTL code generation
│   └── explanation_agent.py   # Code explanation
├── templates/             # RTL and testbench templates
├── workspace/             # Generated files (created at runtime)
├── examples.py            # Example usage scenarios
├── test_installation.py   # Installation verification
└── setup.sh              # Automated setup script

Output Files

For each RTL generation, the tool creates:

• {module_name}.v - Generated RTL code
• {module_name}_tb.v - Verification testbench
• {module_name}_documentation.md - Comprehensive documentation
• Verilator compilation and simulation results

Configuration

Environment variables (set in .env):

• OPENAI_API_KEY - Your OpenAI API key (required)
• VERILATOR_PATH - Path to Verilator executable (optional)
• WORKSPACE_DIR - Workspace directory for generated files

Testing

Run the installation test:

python3 test_installation.py

This verifies:

• All dependencies are installed
• Imports work correctly
• CLI help functionality
• Environment setup

Examples and Use Cases

Digital Design Education

• Generate examples for learning RTL concepts
• Create testbenches for verification practice
• Understand design patterns and best practices

Rapid Prototyping

• Quickly generate RTL modules for system integration
• Create verification infrastructure
• Iterate on designs with AI feedback

Design Documentation

• Generate comprehensive design documentation
• Explain complex RTL designs
• Create educational materials

Limitations

• Requires OpenAI API access (costs apply)
• Generated code may need manual review for production use
• Verilator integration is optional but recommended
• Complex designs may require multiple iterations

Contributing

This is a demonstration project showcasing agentic AI workflows for RTL design. Feel free to extend and modify for your specific needs.

License

MIT License - See LICENSE file for details