Voice + LLM Interface

Experimental. This feature ships in MockForge but is early. It needs an LLM provider (Ollama, OpenAI, or Anthropic) to interpret commands. Voice input in the admin UI uses the browser’s speech recognition, so it only works in browsers that support it (for example Chrome and Edge). The CLI does not capture from a microphone: it takes typed commands, or a path to an audio file when the CLI is built with the stt-cloud feature and an OpenAI Whisper or Google Speech key is set. Behavior, commands, and configuration may change between releases. Report issues at https://github.com/SaaSy-Solutions/mockforge/issues.

The Voice + LLM Interface allows you to create mock APIs conversationally using natural language commands, powered by LLM interpretation. Generate OpenAPI specifications and mock APIs from voice or text commands.

Overview

The Voice + LLM Interface provides:

  • Voice Command Parsing: Use natural language to describe APIs
  • OpenAPI Generation: Automatically generate OpenAPI 3.0 specifications
  • Conversational Mode: Multi-turn interactions for complex APIs
  • Single-Shot Mode: Complete API generation in one command
  • CLI and Web UI: Use from command line or web interface

Quick Start

CLI Usage

Single-Shot Mode

Create a complete API in one command:

# Create API from text command
mockforge voice create \
  --command "Create a user management API with endpoints for listing users, getting a user by ID, creating users, and updating users" \
  --output api.yaml

# Or use interactive input
mockforge voice create
# Enter your command when prompted

Conversational Mode

Build APIs through conversation:

# Start interactive conversation
mockforge voice interactive

# Example conversation:
# > Create a user management API
# > Add an endpoint to get user by email
# > Add authentication to all endpoints
# > Show me the spec
# > done

Web UI Usage

  1. Navigate to Voice page in Admin UI
  2. Click microphone or type your command
  3. View generated OpenAPI spec
  4. Download or use the spec

Features

Natural Language Commands

Describe your API in plain English:

Create a REST API for an e-commerce store with:
- Product catalog with categories
- Shopping cart management
- Order processing
- User authentication

OpenAPI Generation

Automatically generates complete OpenAPI 3.0 specifications:

openapi: 3.0.0
info:
  title: E-commerce Store API
  version: 1.0.0
paths:
  /products:
    get:
      summary: List products
      responses:
        '200':
          description: List of products
  /cart:
    post:
      summary: Add item to cart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                product_id:
                  type: integer
                quantity:
                  type: integer

Conversational Mode

Build complex APIs through multiple interactions:

> Create a blog API
✓ Created blog API with posts endpoint

> Add comments to posts
✓ Added comments endpoint with post_id relationship

> Add user authentication
✓ Added authentication to all endpoints

> Show me the spec
[Displays generated OpenAPI spec]

> done
✓ Saved to blog-api.yaml

Single-Shot Mode

Generate complete APIs in one command:

mockforge voice create \
  --command "Create a task management API with CRUD operations for tasks, projects, and users" \
  --output task-api.yaml

CLI Commands

Create (Single-Shot)

mockforge voice create \
  --command "<description>" \
  --output <file> \
  --serve --port 3000

Options:

  • -c, --command: Natural language description of API (prompts or reads stdin if omitted)
  • -o, --output: Output file path. The format follows the extension (.yaml/.yml for YAML, otherwise JSON). If omitted, the spec is not saved.
  • --serve: Start a mock server with the generated spec
  • --port: HTTP port used with --serve (default: 3000)

There are no per-command provider or model flags; the LLM provider is configured as described in AI Provider Configuration.

Interactive (Conversational)

mockforge voice interactive --output api.yaml

Options: -o, --output, --serve, and --port (same meaning as for create).

Special Commands:

  • help - Show available commands
  • show spec - Display current OpenAPI spec
  • save <file> - Save spec to file
  • done - Exit and save
  • exit - Exit without saving

Web UI

Voice Input

Use Web Speech API for voice input:

  1. Click microphone button
  2. Speak your command
  3. View real-time transcript
  4. See generated spec

Text Input

Type commands directly:

  1. Enter command in text field
  2. Click “Generate” or press Enter
  3. View generated spec
  4. Download or use spec

Command History

View last 10 commands:

  • Click on history item to reuse
  • Edit before regenerating
  • Save successful commands

Configuration

AI Provider Configuration

voice:
  enabled: true
  ai_provider: "ollama"  # or "openai", "anthropic"
  ai_model: "llama3.2"
  ai_base_url: "http://localhost:11434"  # For Ollama
  ai_api_key: "${AI_API_KEY}"  # For OpenAI/Anthropic

CLI Configuration

The voice + LLM interface uses the shared RAG/LLM env vars rather than dedicated MOCKFORGE_VOICE_* vars:

# Use Ollama (free, local)
export MOCKFORGE_RAG_PROVIDER=ollama
export MOCKFORGE_RAG_MODEL=llama3
export MOCKFORGE_RAG_API_ENDPOINT=http://localhost:11434

# Or OpenAI
export MOCKFORGE_RAG_PROVIDER=openai
export MOCKFORGE_RAG_MODEL=gpt-3.5-turbo
export MOCKFORGE_RAG_API_KEY=sk-...

Voice-specific YAML knobs (voice.ai_provider, etc.) override the shared env vars when both are set.

API Endpoints

Process Voice Command

POST /api/v2/voice/process
Content-Type: application/json

{
  "command": "Create a user management API",
  "mode": "single_shot",  # or "conversational"
  "conversation_id": null  # For conversational mode
}

Response:

{
  "success": true,
  "spec": {
    "openapi": "3.0.0",
    "info": {...},
    "paths": {...}
  },
  "conversation_id": "uuid"  # For conversational mode
}

Continue Conversation

POST /api/v2/voice/process
Content-Type: application/json

{
  "command": "Add authentication",
  "mode": "conversational",
  "conversation_id": "uuid"
}

Use Cases

Rapid Prototyping

Quickly create API prototypes:

mockforge voice create \
  --command "Create a simple todo API with CRUD operations" \
  --output todo-api.yaml

API Design

Design APIs by describing them:

mockforge voice interactive

# > Create a social media API
# > Add posts, comments, and likes
# > Add user profiles
# > Show me the spec

Learning

Learn OpenAPI by example:

# Generate spec
mockforge voice create --command "..."

# Review generated spec
cat generated-api.yaml

Best Practices

  1. Be Specific: Provide clear, detailed descriptions
  2. Iterate: Use conversational mode for complex APIs
  3. Review Generated Specs: Always review and validate generated specs
  4. Use Local LLMs: Use Ollama for faster, free generation
  5. Save Good Examples: Save successful commands for reuse

Troubleshooting

Command Not Understood

  • Be more specific in your description
  • Break complex APIs into smaller parts
  • Use conversational mode for clarification

Spec Generation Fails

  • Check AI provider is accessible
  • Verify API key is set (for OpenAI/Anthropic)
  • Review server logs for errors

Voice Input Not Working

  • Check browser permissions for microphone
  • Verify Web Speech API is supported
  • Use text input as fallback