Widget Project Structure

Every Abyss Widget follows a standard project structure. Here is the minimal setup:

Copymy-widget/
├── run.py
├── requirements.txt
└── output/

Key Files in Your Python Project

run.py (Entry Point File): This file must be in the root directory. It serves as the main script that will be executed.

Copyimport os

def run():
    input_value = os.environ.get('input_value', 'default_value')
    result = perform_task(input_value)
    with open('output/result.txt', 'w') as f:
        f.write(result)

if __name__ == "__main__":
    run()

requirements.txt (Python Dependencies)

List all Python packages your project requires in this file.

Copyopenai
numpy

requirements.system (Optional System‑Level Dependencies)

If your Widget requires system-level packages, list them here.

Copypoppler-utils
libffi-dev

Input and Output Handling

Input: Environment variables handle inputs. For example, use os.environ.get() to access input data passed by the end-user.

Copyuser_input = os.environ.get('user_input')

Output: All output files must be saved in the output folder. This is crucial for the Widget to return outputs to the user when run.

Copywith open('output/message.txt', 'w') as f:
    f.write("Task completed successfully!")

Memory and Compute Limits

Memory: Your project must use 512 MB or less.
Compute: Your project must use no more than 4 vCPUs and 4 GB RAM.

When creating your Widget, you will design a simple interface for users to interact with. Abyss provides a range of input fields:

Text Field: A single-line input field for short text entries. Suitable for brief information
(e.g., First Name).

Text Area: A multi-line input field for longer text entries. Suitable for detailed information
(e.g., Instructions).

Number Field: An input field accepting numerical values only. Perfect for quantities, measurements, or any data that requires numeric input (e.g., Age or Quantity).

Radio Group: A set of radio buttons where users can select only one option from a predefined list. Suitable for single-choice questions (e.g., Select a country).

Checkbox: A versatile input, which allows users to select one or multiple options from a list. Suitable for both single and multiple-choice questions (e.g., Hobbies).

Select: A dropdown menu where users can choose one option from a list. Useful for selecting items from a long list without cluttering the interface (e.g., Profession title).

Date: An input field for selecting a date. Suitable for picking day/month/year conveniently (e.g., Deadline date).

File: An input area that allows users to upload a file. You can specify the accepted file extensions (e.g., .pdf, .docx).

Setting Up the File Input

When creating the file input field in your Widget's interface, you must specify the file path (excluding the extension). This path determines how the uploaded file will be saved in your Widget's project directory.

Example: If you specify the file name as data, and a user uploads a file named resume.pdf, the file will be saved in your Widget's environment as data.pdf.

After uploading your widget and creating the interface, fill in the inputs and test run your widget. During test run, pay close attention to the logs, verifying correct installation of your dependencies and python logs of the run.py execution. When your run successfully finishes, all files in the output folder will be presented to you.

To deploy your widget, you must provide a successful test run as an example run of your widget. Users will see the inputs and outputs of this run to better understand what the widget does.

If you need to make changes to your widget you can easily do so from the widget's page by pressing the more button (ellipses). If you change the widget’s files or interface, test run the new version of the widget and deploy it for changes to take effect.

Here are some common errors users face and how to troubleshoot them:

Missing Dependencies: Double-check your requirements.txt and requirements.system to ensure all necessary packages are listed.
No Output Generated: Ensure your project is writing output files to the output folder. The Widget needs at least one file to return to the user.
Memory Exceeded: Ensure your project’s memory footprint is under 512 MB. Consider optimizing or removing unnecessary files.

Copyimport os

def run():
    user_input = os.environ.get('user_input', 'default_input')
    result = f"You entered: {user_input}"
    with open('output/result.txt', 'w') as f:
        f.write(result)

if __name__ == "__main__":
    run()

Make sure your requirements.txt includes all necessary libraries and your run.py file is in the root folder. Your python project can have multiple Python files, the run.py file will just serve as the entry point for Widget execution.