Natural Language → FSM → Code

AutoState is an AI-powered tool that converts natural language scenarios into finite state machines (FSMs) and generates production-ready code. Perfect for security systems, safety protocols, workflow automation, and embedded systems.

• Convert plain English scenarios into formal FSM transitions
• GPT-4o integration for intelligent state extraction
• Human-in-the-loop workflow with AI suggestions

• Multiple Layout Algorithms: Hierarchical, Tree, Force-Directed, Circular
• Interactive Controls: Zoom, pan, fit-to-view with animations
• Smart Label Abbreviation: Transition labels
• Export Capabilities: Download diagrams as PNG images

• Determinism checking (no conflicting transitions)
• Completeness analysis (missing state handlers)
• Reachability verification (detect unreachable states)
• Security pattern validation

• Python Classes: Object-oriented FSM with unit tests
• YAML Policies: For RBAC and configuration management
• C State Machines: For embedded and real-time systems
• Template-based: Customizable output formats

• Business Process Automation - Approval workflows, document routing
• Security Systems - Access control, authentication flows
• Industrial Control - Manufacturing processes, safety interlocks
• Embedded Systems - Device state management, protocol implementation
• Game Logic - Character states, game progression
• User Interfaces - Form validation, navigation flows

• Backend: Python 3.8+, OpenAI API key
• Frontend: Node.js 16+, npm

1. Clone the repository

git clone https://github.com/GH05TCREW/autostate.git
cd autostate

2. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Create .env file
echo "OPENAI_API_KEY=your_api_key_here" > .env
echo "DATABASE_URL=sqlite:///./autostate.db" >> .env
echo "SECRET_KEY=your_secret_key_here" >> .env
echo "ENVIRONMENT=development" >> .env

# Start backend
python main.py

3. Frontend Setup

cd frontend
npm install
npm start

4. Access Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Write natural language descriptions of your system behavior:

Given the system is idle, when the start button is pressed, then initialize the system and transition to running state
Given the system is running, when an error occurs, then log the error and transition to error state  
Given the system is in error state, when reset is pressed, then clear errors and transition to idle state

Click "Generate FSM" to create the state machine. The AI will:

• Extract states, events, and actions
• Create transition table
• Build visual graph
• Suggest completeness improvements

• Visual Graph: Use layout controls for best view
  • Hierarchical: Perfect for workflows and processes
  • Tree: Great for decision trees and branching logic
  • Force-Directed: Shows natural relationships
  • Circular: Highlights cyclic patterns
• Interactive Controls: Zoom, pan, export diagrams
• Edit Transitions: Modify directly in the table
• AI Suggestions: Accept/reject proposed improvements

Run automated checks:

• ✅ Deterministic: No conflicting transitions
• ✅ Complete: All states handle necessary events
• ✅ Reachable: No orphaned states
• ⚠️ Warnings: Potential issues and suggestions

Export your FSM as production-ready code:

Python Example:

class SystemStateMachine:
    def __init__(self):
        self.current_state = State.IDLE
        
    def handle_event(self, event):
        # Generated transition logic
        if self.current_state == State.IDLE and event == Event.START_BUTTON:
            self.initialize_system()
            self.current_state = State.RUNNING
            return True
        # ... more transitions

• Hierarchical (Default): Left-to-right flow, perfect for sequential processes
• Tree: Top-down branching, ideal for decision trees
• Force-Directed: Physics-based positioning, shows natural clusters
• Circular: Radial layout, great for highlighting cycles

• Zoom In/Out: Detailed inspection or overview
• Fit to View: Auto-center and scale diagram
• Export PNG: High-quality images for documentation
• Smart Labels: Abbreviated text prevents overlap

• Color-coded elements (blue=initial, green=user, orange=AI)
• Curved edges with proper routing
• Drop shadows and professional typography
• Responsive layout with hover tooltips

Given the door is locked, when valid keycard is presented, then unlock door and log access
Given the door is unlocked, when timeout occurs, then lock door automatically  
Given the door is locked, when invalid keycard is presented, then remain locked and alert security
Given the door is unlocked, when manual lock pressed, then lock door immediately

Given order is submitted, when payment is valid, then confirm order and start processing
Given order is processing, when items are ready, then ship order and notify customer
Given order is shipped, when delivered, then complete order and request feedback
Given order is processing, when item unavailable, then refund payment and cancel order

Given device is off, when power button pressed, then boot system and enter ready state
Given device is ready, when start command received, then begin operation and enter active state
Given device is active, when error detected, then stop operation and enter fault state
Given device is fault, when reset command received, then clear errors and enter ready state

┌────────────────────────────────────┐
│  Frontend (React + TypeScript)     │
│  • Scenario Editor                 │
│  • FSM Visualization               │
│  • Interactive Graph Controls      │
│  • Code Generator Interface        │
└──────────────┬─────────────────────┘
               │ API
┌──────────────▼──────────────────────┐
│  Backend (FastAPI + Python)         │
│  • LLM Parser (OpenAI GPT-4o)       │
│  • FSM Builder (NetworkX)           │
│  • Code Generator (Jinja2)          │
│  • Verification Engine              │
│  • SQLite Database                  │
└─────────────────────────────────────┘

• LLM Parser: Converts natural language to structured transitions
• FSM Builder: Constructs and validates state machines
• Visualization Engine: Advanced graph rendering with vis-network
• Verification Engine: Completeness and correctness checking
• Code Generator: Multi-language template-based generation
• Database Layer: SQLAlchemy ORM with SQLite

• POST /api/scenarios/parse - Parse natural language into FSM
• GET /api/scenarios/{id} - Retrieve FSM by ID
• DELETE /api/scenarios/{id} - Delete FSM

• POST /api/fsm/{id}/suggest-transitions - Get AI improvement suggestions
• POST /api/fsm/{id}/accept-transition - Accept suggested transition
• PUT /api/fsm/{id}/transitions - Update all transitions

• GET /api/verification/{id}/verify - Run completeness checks
• POST /api/verification/{id}/simulate - Simulate event sequences
• GET /api/verification/{id}/graph - Get visualization data

• POST /api/generator/generate - Generate code from FSM
• POST /api/generator/download/{id}/{template} - Download code file

MIT License