Speckle Syntax Automate

speckle-syntax-automate

Quick Reference

Architecture: Functions vs Automations

One Function can be deployed as many Automations across different projects, each with different input configurations.

Trigger Mechanism

The ONLY trigger is version creation -- when a new version (commit) is published to a model. There is NO manual trigger, NO scheduled trigger, and NO webhook-based trigger for Automate functions.

Execution Flow

1. User publishes new version to a model
2. Speckle Server detects version creation event
3. Server finds all Automations bound to that model
4. For each Automation, Speckle spins up a Docker container
5. Function code executes with AutomationContext
6. Results (pass/fail, annotations, files) attach to the version
7. Results visible in web interface and 3D viewer

SDK Packages

Three Outcome States

Critical Warnings

ALWAYS explicitly call mark_run_success() or mark_run_failed() before the function returns. If neither is called and no exception occurs, the run status is ambiguous.

NEVER pass execute_automate_function a function invocation -- pass the function reference WITHOUT parentheses and the FunctionInputs CLASS (not an instance).

NEVER use plain str for sensitive inputs (API keys, tokens). ALWAYS use SecretStr (Python) or [Secret] attribute (C#) to prevent exposure in logs and UI.

NEVER pass an empty list to attach_error_to_objects() -- it produces silent failures with no visible annotations. ALWAYS verify the list contains valid object IDs before calling.

NEVER use .Result or .Wait() in C# Automate functions -- the function is async. ALWAYS use await for all async operations.

NEVER use complex nested types in FunctionInputs -- the Speckle UI renders inputs as a flat form. Keep inputs as simple scalar types (str, int, float, bool).

Python: Function Structure

Entry Point Pattern

Every Python Automate function MUST follow this exact structure:

from speckle_automate import (
    AutomateBase,
    AutomationContext,
    execute_automate_function,
)
from pydantic import Field, SecretStr


class FunctionInputs(AutomateBase):
    """Define inputs with Pydantic Field() -- generates the UI form."""
    param_name: str = Field(title="Human Title", description="Explanation")


def automate_function(
    automate_context: AutomationContext,
    function_inputs: FunctionInputs,
) -> None:
    # 1. Receive the version data
    base = automate_context.receive_version()

    # 2. Process/validate the data
    # ... your logic here ...

    # 3. Report results
    automate_context.mark_run_success("All checks passed.")


# Entry point -- MUST be at module level
if __name__ == "__main__":
    execute_automate_function(automate_function, FunctionInputs)

FunctionInputs (Python -- Pydantic)

AutomateBase inherits from Pydantic's BaseModel. All Pydantic features work:

class FunctionInputs(AutomateBase):
    # Required string
    category_filter: str = Field(
        title="Category Filter",
        description="Only check objects in this category"
    )

    # Numeric with constraints and default
    max_count: int = Field(
        default=100,
        title="Maximum Object Count",
        ge=1, le=10000
    )

    # Secret value (encrypted, hidden in logs/UI)
    api_key: SecretStr = Field(title="External API Key")

    # Boolean toggle with default
    strict_mode: bool = Field(
        default=False,
        title="Strict Mode",
        description="Fail on warnings too"
    )

Rules:

• ALWAYS add title and description to every Field -- without them the Speckle UI shows raw field names
• ALWAYS provide default values for optional inputs -- inputs without defaults are treated as required
• ALWAYS use SecretStr for sensitive values (API keys, tokens, credentials)
• The JSON Schema is auto-generated from the class and rendered as a form in Speckle

AutomationContext API (Python)

Object Traversal Pattern

Flatten the received object hierarchy to inspect individual objects:

from specklepy.objects import Base
from typing import Iterable


def flatten_base(base: Base) -> Iterable[Base]:
    """Recursively flatten a Base object hierarchy."""
    elements = getattr(base, "elements", getattr(base, "@elements", None))
    if elements is not None:
        for element in elements:
            yield from flatten_base(element)
    yield base

This function:

• Uses getattr with fallback to handle both elements and @elements naming
• Yields descendants before the parent (depth-first, bottom-up)
• Returns Iterable[Base] for lazy evaluation (memory-efficient for large models)
• Is included in the official Python template as flatten.py

C#: Function Structure

Project Setup

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.1" />
    <PackageReference Include="Speckle.Automate.Sdk" Version="3.4.0-alpha.20" />
  </ItemGroup>
</Project>

Entry Point (Program.cs)

using Microsoft.Extensions.DependencyInjection;
using Speckle.Automate.Sdk;

var serviceCollection = new ServiceCollection();
serviceCollection.AddAutomateSdk();
serviceCollection.AddSingleton<AutomateFunction>();
var serviceProvider = serviceCollection.BuildServiceProvider();

var runner = serviceProvider.GetRequiredService<IAutomationRunner>();
var function = serviceProvider.GetRequiredService<AutomateFunction>();

return await runner.Main<FunctionInputs>(args, function.Run);

The runner.Main<FunctionInputs>() call:

1. Parses command-line arguments
2. Deserializes function inputs as FunctionInputs
3. Creates the IAutomationContext
4. Invokes function.Run with both

FunctionInputs (C# -- DataAnnotations)

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

public readonly struct FunctionInputs
{
    [Required]
    public string SpeckleTypeToCount { get; init; }

    [DefaultValue(10)]
    [Range(1, 100)]
    [Required]
    public int SpeckleTypeTargetCount { get; init; }

    [Required]
    [Secret]
    public string ExternalServiceKey { get; init; }
}

Rules:

• ALWAYS use readonly struct for immutability
• ALWAYS use System.ComponentModel.DataAnnotations attributes for validation
• ALWAYS use [Secret] attribute for sensitive values (NOT SecretStr)
• ALWAYS use { get; init; } properties

AutomateFunction Class

using Speckle.Automate.Sdk;
using Speckle.Sdk.Models.Extensions;

public class AutomateFunction
{
    public async Task Run(
        IAutomationContext automationContext,
        FunctionInputs functionInputs
    )
    {
        var rootObject = await automationContext.ReceiveVersion();
        var allObjects = rootObject.Flatten().ToList();

        // ... validation logic ...

        automationContext.MarkRunSuccess("All checks passed.");
    }
}

IAutomationContext API (C#)

Python vs C# Comparison

Deployment Workflow

1. Create function via Speckle wizard (Automations tab)
2. Template repo cloned to your GitHub account
3. Modify function code locally
4. Push changes to GitHub
5. Create a GitHub Release
6. GitHub Actions builds Docker image and registers function
7. Function appears in Function Library
8. Users create Automations from the function

ALWAYS create a GitHub Release to publish -- pushing code alone does NOT make the function appear in the Function Library.

NEVER modify or remove SPECKLE_FUNCTION_ID and SPECKLE_FUNCTION_TOKEN environment variables in the auto-generated .github/workflows/main.yml -- removing them breaks the deployment pipeline.

Reference Links

• references/methods.md -- Complete API signatures for AutomationContext (Python) and IAutomationContext (C#)
• references/examples.md -- Working code examples for both Python and C#
• references/anti-patterns.md -- Common mistakes with explanations

Official Sources

• https://docs.speckle.systems/developers/automate/introduction
• https://docs.speckle.systems/developers/automate/quickstart
• https://docs.speckle.systems/developers/automate/create-function
• https://github.com/specklesystems/speckle_automate_python_example
• https://github.com/specklesystems/SpeckleAutomateDotnetExample