FormConv AI

This tool generates XLSForm files using AI and converts them to JSON format using the formconv service.

Features

• Generates valid XLSForm files with proper structure using AI
• Handles survey, choices, and settings sheets
• Avoids conversion issues by not using complex constraints
• Automatically converts XLSX to JSON format with timestamped filenames
• Handles file path issues with the excel-mcp-server
• Uses environment variables for configuration
• Generates timestamped filenames to avoid overwriting previous results
• All generated files are saved in the output_files directory
• Available as both a command-line script and a web API
• Provides a Gradio web interface for easy interaction

How it works

1. The user provides a description of the survey they want to create
2. The tool uses an LLM (through smolagents) to generate a proper XLSForm structure
3. The XLSForm is created using the excel-mcp-server
4. The XLSForm is then converted to JSON using the formconv service

Environment Variables

The tool uses the following environment variables, which should be set in a .env file:

• DEEPINFRA_API_KEY: Your DeepInfra API key (optional but recommended)
• MODEL_ID: The model ID to use (defaults to deepinfra/Qwen/Qwen3-Next-80B-A3B-Instruct)

Example .env file:

DEEPINFRA_API_KEY=your_api_key_here
MODEL_ID=deepinfra/Qwen/Qwen3-Next-80B-A3B-Instruct

Filename Convention

Files are saved with timestamped names to avoid conflicts in the output_files directory:

• XLSForm files: output_files/xlsform_survey_YYYYMMDD_HHMMSS.xlsx
• JSON result files: output_files/form_result_YYYYMMDD_HHMMSS.json

Usage - Command Line Script

python main.py "Create a survey to collect user feedback with name, email, rating (1-5), and comments fields"

Usage - Web API

1. Start the Flask server:

python app.py

2. Send a POST request to /responseAI.json:

curl -X POST http://localhost:5000/responseAI.json \
  -H "Content-Type: application/json" \
  -d '{"query": "Create a survey to collect user feedback with name, email, rating (1-5), and comments fields"}'

Usage - Gradio Web Interface

1. Start the Flask server (required for the Gradio interface):

python app.py

2. In a separate terminal, start the Gradio interface:

python interface.py

3. Open your browser and navigate to http://localhost:7860

The Gradio interface provides a user-friendly way to generate surveys:

• Enter your survey requirements in natural language
• Click "Generate Survey"
• Download the generated XLSX and JSON files

Requirements

• Python 3.8+
• smolagents
• excel-mcp-server (installed via uvx)
• requests
• pandas
• flask
• gradio

Installation

pip install -r requirements.txt

Example - Command Line

python main.py "Create a medical clinic survey to collect patient information including name, age, gender, symptoms, and preferred treatment. Include a rating question for overall satisfaction."

This will generate an XLSForm file and convert it to JSON format, saving both files in the output_files directory with timestamped filenames.

Example - Web API

curl -X POST http://localhost:5000/responseAI.json \
  -H "Content-Type: application/json" \
  -d '{"query": "Create a medical clinic survey to collect patient information including name, age, gender, symptoms, and preferred treatment. Include a rating question for overall satisfaction."}'

This will return the generated JSON form in the response.

Project Structure

• main.py: Command-line interface
• app.py: Flask web API
• interface.py: Gradio web interface
• formconv/: Core functionality as a Python package
• xlsform_prompt.txt: Prompt template for XLSForm generation
• output_files/: Directory where generated files are saved