Script

Scripts are executable code that perform work.

Purpose

Scripts contain runnable implementations in Python, JavaScript, SQL, or any executable language. They define what inputs they expect and what outputs they produce.

When referenced in a plan, scripts receive inputs and return outputs that subsequent steps can use.

YAML Schema

id: bullet://example/script-sentiment-analyzer@2.0.0
 
# ... standard bullet metadata (see bullets.mdx) ...
# type: script
 
payload:
  # Programming language
  language: python
  
  # Package dependencies with exact versions
  packages:
    - transformers==4.30.0
    - torch==2.0.1
  
  # Input specification - what this script accepts
  inputs:
    documents:
      type: array
      description: Array of text documents to analyze
      required: true
    model:
      type: string
      description: Name of the sentiment analysis model to use
      required: false
      default: "distilbert-base-uncased"
    threshold:
      type: float
      description: Confidence threshold for sentiment classification
      required: false
      default: 0.5
  
  # The executable code
  content: |
    from transformers import pipeline
    
    def execute(input):
        """
        Analyze sentiment in text documents.
        
        Args:
            input: Dict with 'documents' (array of strings) and optional 'config'
        
        Returns:
            Dict with 'sentiments' (array of scores) and 'summary'
        """
        documents = input['documents']
        config = input.get('config', {})
        
        # Load sentiment analysis model
        analyzer = pipeline("sentiment-analysis", 
                          model=config.get('model', 'distilbert-base-uncased'))
        
        # Analyze each document
        results = []
        for doc in documents:
            sentiment = analyzer(doc)[0]
            results.append({
                'text': doc,
                'label': sentiment['label'],
                'score': sentiment['score']
            })
        
        # Generate summary
        positive = sum(1 for r in results if r['label'] == 'POSITIVE')
        negative = len(results) - positive
        
        return {
            'sentiments': results,
            'summary': {
                'positive_count': positive,
                'negative_count': negative,
                'positive_ratio': positive / len(results) if results else 0
            }
        }

The script payload contains the language, package dependencies, and the executable code itself. The code should have a clear entry point (like execute) that accepts inputs and returns outputs.

Input Specification

When scripts are referenced in plans, inputs guide the AI executor on what context to assemble. Each input is either a literal value or a natural language description.

Important: There are no deterministic references like $refs[0] or $steps[2].output. The AI executor uses context assembly to intelligently resolve inputs from available context.

Literal Values

Provide known values directly:

- script: bullet://example/sentiment-analyzer@2.0
  inputs:
    threshold:
      value: 0.7
    model_name:
      value: "distilbert"
    batch_size:
      value: 32

Use literal values when:

The value is known at plan creation time
The value is a configuration constant
You want to explicitly specify a parameter

Context-Based Descriptions

Provide natural language descriptions that the AI executor interprets using available context:

- script: bullet://example/sentiment-analyzer@2.0
  inputs:
    documents:
      description: The customer feedback texts from the data analysis step
    model:
      description: Use the sentiment model specified in the user's preferences
    
- script: bullet://example/send-notification@1.0
  inputs:
    count:
      description: The number of high-priority items found
    message:
      description: A summary of the analysis results suitable for email

Use descriptions when:

The value depends on prior execution context
The AI executor should select or compute the value intelligently
You want flexibility in how the input is resolved

Context Assembly, Not Deterministic Linking: The AI executor assembles context from previous steps, available data, and the execution environment to resolve descriptions. You cannot use deterministic references like $refs[0] or variable names - instead, describe what you need in natural language and the executor finds it from available context.

Guidance Data