Skip to content

README.md

Latest commit

 

History

History
203 lines (163 loc) · 7.48 KB

README.md

File metadata and controls

203 lines (163 loc) · 7.48 KB
Raw

Hensu DSL

Kotlin DSL for defining AI agent workflows with type-safe builders.

Overview

The hensu-dsl module provides:

  • Kotlin DSL - Type-safe workflow definitions with workflow { } builder syntax
  • Kotlin Script Parser - Compiles .kt workflow files at runtime via embedded Kotlin compiler
  • Simple Runner - Standalone workflow execution for development and testing
  • Working Directory - Convention-based file resolution for rubrics and resources

Quick Start

Define a Workflow

fun myWorkflow() = workflow("ContentPipeline") {
    state {
        input("topic", VarType.STRING)
        variable("article", VarType.STRING, "the full written article text")
    }

    agents {
        agent("writer") {
            role = "Content Writer"
            model = Models.CLAUDE_SONNET_4_5
        }
        agent("reviewer") {
            role = "Quality Reviewer"
            model = Models.GEMINI_3_1_PRO
        }
    }

    graph {
        start at "write"

        node("write") {
            agent = "writer"
            prompt = "Write a short article about {topic}"
            writes("article")
            onSuccess goto "review"
        }

        node("review") {
            agent = "reviewer"
            prompt = "Review this article: {article}"
            rubric = "content-quality.md"
            writes("article")

            onScore {
                whenScore greaterThanOrEqual 80.0 goto "end_success"
                whenScore lessThan 80.0 goto "write"
            }
        }

        end("end_success")
    }
}

Run Directly

# Via Gradle task
./gradlew hensu-dsl:runWorkflow -Pworkflow=path/to/workflow.kt -Pargs="--stub --verbose"

# Via CLI (recommended)
hensu run my-workflow -d working-dir

Compile to JSON

The DSL compiles workflows to JSON for server deployment:

# Compile DSL → JSON
hensu build my-workflow -d working-dir

# Push compiled JSON to server
hensu push my-workflow --server http://localhost:8080

DSL Reference

See DSL Reference for the complete syntax reference including:

  • Workflow structure and configuration
  • Agent definitions and model constants
  • Node types (standard, parallel, fork/join, action, generic, sub-workflow, end)
  • Transition rules (success, failure, score-based, condition-based, approval, consensus)
  • Condition-based routing (onCondition with typed value predicates, otherwise else-arm, bounded revise loops)
  • State variables (writes() + {placeholder} syntax), branch outputs (yields()), join boundary filter (exports())
  • State schema (state { } block with typed input/variable declarations and load-time validation)
  • Approval routing (onApproval goto / onRejection goto)
  • Rubric-driven quality gates
  • Human review configuration
  • External prompt files (.md from prompts/ directory)

Module Structure

hensu-dsl/src/main/kotlin/io/hensu/dsl/
├── HensuDSL.kt                   # Top-level `workflow { }` entry point
├── WorkingDirectory.kt            # Convention-based file resolution
├── builders/
│   ├── WorkflowBuilder.kt        # Root workflow builder
│   ├── WorkflowConfigBuilder.kt  # Workflow-level configuration
│   ├── GraphBuilder.kt           # Graph definition (`start at`, nodes, edges)
│   ├── AgentBuilder.kt           # Agent configuration builder
│   ├── StandardNodeBuilder.kt    # Standard LLM node builder
│   ├── ParallelNodeBuilder.kt    # Parallel execution builder
│   ├── ForkJoinBuilders.kt       # Fork/join node builders
│   ├── ActionNodeBuilder.kt      # Action node builder
│   ├── GenericNodeBuilder.kt     # Custom node type builder
│   ├── SubWorkflowNodeBuilder.kt # Sub-workflow delegation builder
│   ├── EndNodeBuilder.kt         # Terminal node builder
│   ├── BaseNodeBuilder.kt        # Shared node builder base
│   ├── StateSchemaBuilder.kt     # Typed state schema builder (`state { }` block)
│   ├── TransitionBuilder.kt      # Transition rule builders
│   ├── ScoreTransitionBuilder.kt # Score-based routing
│   ├── ScoreConditionBuilder.kt  # Score condition expressions
│   ├── ConditionTransitionBuilder.kt # Condition-based routing (`onCondition` arms)
│   ├── ArmIntervals.kt           # Overlap detection across transition arms
│   ├── ReviseBuilder.kt          # Bounded `revise` retry/escalation chain builder
│   ├── RetryBuilder.kt           # Retry configuration
│   ├── ReviewConfigBuilder.kt    # Human review settings
│   ├── ObservabilityBuilder.kt   # Logging and tracing config
│   ├── Models.kt                 # Model constants (CLAUDE_SONNET_4_5, GPT_4O, etc.)
│   └── DslMarkers.kt             # DSL scope markers
├── extensions/
│   └── DslHelpers.kt             # Extension functions for DSL sugar
├── parsers/
│   └── KotlinScriptParser.kt     # .kt file → Workflow compilation
├── runners/
│   └── SimpleRunner.kt           # Standalone execution entry point
└── internal/
    └── DSLContext.kt             # Internal DSL state management

Key Concepts

Client-Side Compilation

The DSL module contains the Kotlin compiler — this runs on the client (CLI), never on the server. The compilation flow:

workflow.kt → KotlinScriptParser → Workflow object → JSON (via hensu-serialization) → Server

The server receives pre-compiled JSON and has no Kotlin compiler dependency.

Working Directory

Workflows reference external files (rubrics, resources) relative to a working directory:

working-dir/
├── workflows/
│   └── my-workflow.kt
├── prompts/
│   └── agent-prompt.md
├── rubrics/
│   └── content-quality.md
└── build/
    └── my-workflow.json    # Compiled output

Available Models

The Models object provides constants for supported AI models:

Constant Model ID
Models.CLAUDE_OPUS_4_6 claude-opus-4-6
Models.CLAUDE_OPUS_4_5 claude-opus-4-5
Models.CLAUDE_SONNET_4_6 claude-sonnet-4-6
Models.CLAUDE_SONNET_4_5 claude-sonnet-4-5
Models.CLAUDE_HAIKU_4_5 claude-haiku-4-5
Models.GPT_4 gpt-4
Models.GPT_4_TURBO gpt-4-turbo
Models.GPT_4O gpt-4o
Models.GEMINI_3_1_FLASH_LITE gemini-3.1-flash-lite
Models.GEMINI_3_1_PRO gemini-3.1-pro-preview
Models.GEMINI_2_5_FLASH gemini-2.5-flash
Models.GEMINI_2_5_PRO gemini-2.5-pro
Models.DEEPSEEK_V4_FLASH deepseek-v4-flash
Models.DEEPSEEK_V4_PRO deepseek-v4-pro

Documentation

Document Description
DSL Reference Complete Kotlin DSL syntax and examples

Dependencies

  • hensu-core - Core workflow data model and execution engine
  • Kotlin Stdlib + Reflect - Kotlin standard library
  • Kotlin Scripting - Runtime .kt file compilation (2.3.0)
  • Kotlin Compiler Embeddable - Embedded Kotlin compiler