Skip to main content

​
What We’re Building

In this tutorial, we’ll turn a Python data processing script into a governed tool that:
  • Has a clear input/output contract
  • Runs in a sandboxed environment
  • Produces downloadable artifacts
  • Can be shared with anyone via a link — no local setup required

​
Prerequisites

  • A Constants account (sign up here)
  • A script or GitHub repository you want to turn into a Tool
  • About 10 minutes of your time

​
Step 1: Import Your Script

From your dashboard, click Create new Tool. You have three options:

​
Option A: Import from GitHub

Paste a GitHub URL pointing to your script: 
https://github.com/your-org/analytics/blob/main/scripts/generate_report.py
Constants will:
  1. Clone the repository
  2. Analyze the script structure
  3. Identify the entrypoint and dependencies

​
Option B: Upload Directly

Drag and drop your script file into the composer, or click the upload button to select files.

​
Option C: Describe What You Need

If you don’t have an existing script, describe what you want: 
Create a tool that takes a CSV file, filters rows where status = 'active',
and outputs a new CSV with only those rows.
For this tutorial, we’ll use a GitHub import since it provides version pinning and provenance.

​
Step 2: Review the Detected Spec

After import, Constants analyzes your code and presents the detected spec:

​
Input Schema

{
  "input_file": {
    "type": "file",
    "description": "CSV file to process",
    "required": true
  },
  "filter_column": {
    "type": "string",
    "description": "Column name to filter on",
    "default": "status"
  }
}

​
Output Schema

{
  "result_file": {
    "type": "file",
    "description": "Filtered CSV output"
  },
  "row_count": {
    "type": "integer",
    "description": "Number of rows in output"
  }
}
You can edit these schemas to match your exact requirements.

​
Step 3: Configure Runtime Settings

Set the execution environment:
  • CPU: 1-4 cores
  • Memory: 512MB - 4GB
  • Timeout: 30s - 30min
These prevent runaway executions and ensure fair resource usage.
If your script needs API keys or database credentials:
  1. Add them in the Secrets section
  2. They’re injected as environment variables at runtime
  3. Receivers never see the actual values
Your Tool is pinned to a specific Git SHA. This ensures:
  • Reproducible executions
  • Clear provenance
  • No surprise changes when the repo updates

​
Step 4: Create the Tool

Click Create Tool. Constants will:
  1. Set up the sandboxed runtime
  2. Generate the UI form based on your input schema
  3. Initialize run history tracking
This typically takes 30-60 seconds.

​
Step 5: Run Your Tool

Once created, you’ll see your Tool’s interface:
  1. Upload your input CSV file
  2. Configure any optional parameters
  3. Click Run
Watch as the execution progresses:
  • Real-time logs appear in the console
  • Status updates show current progress
  • Artifacts appear when complete

​
Step 6: Access Artifacts

After the run completes, you can:
  • Download the output file
  • View the logs and execution metrics
  • Replay the run with the same inputs
  • Share the run results with teammates

​
Step 7: Share Your Tool

Your Tool is now ready to share: Click Share to get a link. Recipients can:
  • View the Tool interface
  • Enter their own parameters
  • Run the Tool without any local setup

​
Share with Specific Users

Enter email addresses to share with specific teammates. They’ll get:
  • Access to run the Tool
  • Their own run history
  • Injected secrets (they never see the values)

​
Understanding the Interface

Executes your Tool in the sandboxed environment. Each run is logged with full inputs, outputs, and metrics.
View all past executions with:
  • Inputs used
  • Outputs produced
  • Execution time and resource usage
  • Artifacts generated
You can replay any historical run.
See the Git SHA your Tool is pinned to. Update to a newer SHA when you want to pull in source changes.

​
Best Practices

Pin to SHA

Always pin production Tools to a specific Git SHA for reproducibility and auditability.

Define Clear Schemas

Well-defined input/output schemas make Tools easier to use for both humans and agents.

Set Resource Limits

Configure appropriate CPU, memory, and timeout limits to prevent runaway executions.

Use Secrets Properly

Never hardcode credentials. Use the Secrets feature to inject them at runtime.

​
Next Steps

Features Overview

Learn about all Constants primitives

API Reference

Programmatic access for automation