sigmantic 0.2.0
Sigmantic AI CLI - Intelligent RTL code generation with Claude and workspace management
License: MIT
Requires Python: >=3.8
Keywords: sigmantic, rtl, verilog, systemverilog, fpga, asic, hardware, ai, claude, agent, cli, code-generation, verification

# 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](https://docs.claude.com/en/api/agent-sdk/overview):

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**:
   ```bash
   ./setup.sh
   ```

2. **Configure**:
   ```bash
   cp env.example .env
   # Edit .env and add your Anthropic API key to key.cfg
   ```

3. **Create your first RTL project**:
   ```bash
   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
```bash
# 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)
```bash
pip install sigmantic
```

### Option 2: Install from Source
```bash
git clone https://github.com/sigmantic-ai/sigmantic-cli.git
cd sigmantic-cli
pip install -e .
```

### Option 3: Quick Setup Script
```bash
git clone https://github.com/sigmantic-ai/sigmantic-cli.git
cd sigmantic-cli
./install.sh
```

### Configuration
After installation, configure your API key:
```bash
# Create config directory
mkdir -p ~/.sigmantic

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

### Verify Installation
```bash
sigmantic --help
sigmantic --list-workspaces
```

## Usage

### Basic Usage
```bash
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
```bash
# 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
```bash
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:
```bash
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