API
Manifest Schema

Manifest Schema

The NudgeLang manifest schema defines the structure and configuration of autonomous agents. This document provides a comprehensive reference for all available options and their usage.

Basic Structure 

name: string                 # Required: Unique identifier for the agent
version: string             # Required: Semantic version (e.g., "1.0.0")
description: string         # Required: Brief description of the agent
author: string             # Optional: Author information
license: string            # Optional: License information

# Configuration
config:
  timeout: number          # Optional: Global timeout in seconds
  retry_attempts: number   # Optional: Number of retry attempts
  max_iterations: number   # Optional: Maximum iteration count
  debug: boolean          # Optional: Enable debug mode

# State Definitions
states:
  - id: string            # Required: Unique state identifier
    type: string          # Required: State type (initial, llm, tool, etc.)
    next: string          # Required: Next state ID
    transitions:          # Optional: Conditional transitions
      - when: string      # Required: Condition expression
        next: string      # Required: Next state ID
    input:                # Optional: Input mapping
      key: string         # Required: Input key
      value: string       # Required: Value expression
    output:               # Optional: Output mapping
      key: string         # Required: Output key
      value: string       # Required: Value expression

# Tool Definitions
tools:
  - name: string          # Required: Tool name
    type: string          # Required: Tool type
    description: string   # Required: Tool description
    parameters:           # Required: Parameter definitions
      - name: string      # Required: Parameter name
        type: string      # Required: Parameter type
        required: boolean # Required: Is parameter required
        description: string # Required: Parameter description

# Model Definitions
models:
  - name: string          # Required: Model name
    type: string          # Required: Model type
    provider: string      # Required: Model provider
    version: string       # Required: Model version
    parameters:           # Optional: Model parameters
      key: value          # Provider-specific parameters

# Context Definitions
context:
  variables:              # Optional: Global variables
    - name: string        # Required: Variable name
      type: string        # Required: Variable type
      default: any        # Optional: Default value
  persistence:            # Optional: Context persistence
    type: string          # Required: Storage type
    config: object        # Required: Storage configuration

State Types

Initial State 

states:
  - id: start
    type: initial
    next: next_state

LLM State 

states:
  - id: process
    type: llm
    model: model_name
    prompt: |
      Your prompt template here
      {variable}      
    input:
      variable: "${context.value}"
    next: next_state

Tool State 

states:
  - id: execute
    type: tool
    tool: tool_name
    parameters:
      param1: "${input.value}"
      param2: "${context.value}"
    next: next_state

Output State 

states:
  - id: end
    type: output
    value: "${context.result}"

Transitions

Basic Transition 

states:
  - id: process
    type: llm
    next: next_state

Conditional Transition 

states:
  - id: process
    type: llm
    transitions:
      - when: "${output.status === 'success'}"
        next: success_state
      - when: "${output.status === 'error'}"
        next: error_state
      - next: default_state

Input/Output Mapping

Input Mapping 

states:
  - id: process
    type: llm
    input:
      user_input: "${input.message}"
      context_data: "${context.data}"
      previous_result: "${previous.output}"

Output Mapping 

states:
  - id: process
    type: llm
    output:
      result: "${output.data}"
      status: "${output.status}"

Tool Configuration

Basic Tool 

tools:
  - name: send_message
    type: http
    description: "Send a message to a channel"
    parameters:
      - name: message
        type: string
        required: true
        description: "Message content"
      - name: channel
        type: string
        required: true
        description: "Target channel"

Custom Tool 

tools:
  - name: custom_tool
    type: custom
    description: "Custom tool implementation"
    parameters:
      - name: input
        type: object
        required: true
        description: "Input parameters"
    implementation: "path/to/implementation"

Model Configuration

LLM Model 

models:
  - name: gpt4
    type: llm
    provider: openai
    version: "4.0"
    parameters:
      temperature: 0.7
      max_tokens: 1000

Custom Model 

models:
  - name: custom_model
    type: custom
    provider: custom
    version: "1.0"
    parameters:
      custom_param: value

Context Configuration

Global Variables 

context:
  variables:
    - name: max_retries
      type: number
      default: 3
    - name: timeout
      type: number
      default: 30

Persistence 

context:
  persistence:
    type: redis
    config:
      host: localhost
      port: 6379
      db: 0

Best Practices

  1. Naming Conventions

    • Use descriptive names
    • Follow consistent patterns
    • Avoid reserved words
    • Use lowercase with underscores

  2. State Management

    • Keep states focused
    • Use clear transitions
    • Handle errors properly
    • Document state purposes

  3. Tool Usage

    • Define clear parameters
    • Provide descriptions
    • Handle errors
    • Validate inputs

  4. Model Configuration

    • Set appropriate parameters
    • Monitor usage
    • Handle rate limits
    • Cache when possible

Common Patterns

  1. Error Handling
states:
  - id: process
    type: llm
    transitions:
      - when: "${output.error}"
        next: handle_error
      - next: continue
  1. Retry Logic
states:
  - id: process
    type: tool
    retry:
      attempts: 3
      delay: 1000
    next: next_state
  1. Conditional Flow
states:
  - id: process
    type: llm
    transitions:
      - when: "${output.value > 0}"
        next: positive
      - when: "${output.value < 0}"
        next: negative
      - next: zero

Next Steps

Last updated on
State Types