NLP Flow Interpreter Engine

Relevant source files

The following files were used as context for generating this wiki page:

• packages/flows/src/interpreter/interpreter.ts
• packages/flows/README.md
• CLAUDE.md
• AGENTS.md
• README.md

The NLP Flow Interpreter Engine is a core component of Phase 1 of the SweepBot project, responsible for converting natural language user input into executable automation scripts. It resides in the @sweepbot/flows package and serves as the translation layer between plain English descriptions and a structured Flow Definition Abstract Syntax Tree (AST). This engine allows sweepstakes casino players to define complex cross-platform routines—such as daily bonus collection or specific spinning strategies—without writing code.

Sources: README.md:16-18, packages/flows/README.md:3-5

Engine Pipeline Architecture

The engine utilizes a 4-pass interpretation pipeline to process user requests. This structured approach ensures that entities are accurately extracted, user intent is classified, and mandatory responsible play guardrails are enforced before any automation is scheduled or executed.

Interpretation Pipeline Steps

1. Pass 1: Entity Extraction: Uses the EntityRecognizer to identify platforms, games, actions, conditions, schedules, and amounts from the raw text.
2. Pass 2: Intent Classification: Categorizes the request into types like bonus_collection, play_strategy, or redemption.
3. Pass 3: Logic Structuring (AST Building): Constructs the FlowDefinition AST consisting of various node types (Actions, Conditions, Loops, etc.).
4. Pass 4: Validation: Applies mandatory responsible play guardrails via the ResponsiblePlayValidator.

Sources: packages/flows/src/interpreter/interpreter.ts:11-14, packages/flows/README.md:7-10

The following diagram illustrates the high-level data flow through the interpreter engine:

Key Components

FlowInterpreter Class

The FlowInterpreter is the primary service class that orchestrates the interpretation process. Its main method, interpret, takes a FlowInterpretationRequest (containing the user ID and raw input) and returns a FlowInterpretationResult which includes the generated AST, a confidence score, and a human-readable summary.

Sources: packages/flows/src/interpreter/interpreter.ts:22-26, packages/flows/README.md:126-140

Method / Component	Description
interpret()	The entry point for processing natural language into a FlowDefinition.
classifyIntent()	Heuristic-based method to determine automation type (e.g., searching for "bonus" or "spin").
buildFlowAST()	Logic to transform recognized entities into a sequence of FlowNodes.
calculateConfidence()	Heuristic scoring (0-1) based on the number of recognized entities.
generateSummary()	Creates a human-readable description with emoji indicators for user feedback.

Sources: packages/flows/src/interpreter/interpreter.ts:68-80, packages/flows/src/interpreter/interpreter.ts:220-227, packages/flows/src/interpreter/interpreter.ts:232-254

Flow Definition AST (Abstract Syntax Tree)

The output of the interpreter is a FlowDefinition object. The core of this object is the rootNode, which represents the automation logic as a tree of FlowNode objects. FlowNode is a discriminated union supporting nine distinct types.

Sources: CLAUDE.md:92-94, packages/flows/README.md:173-195

Node Type	Purpose
FlowActionNode	Performs a specific task like login, claim_bonus, or spin.
FlowConditionNode	Branches logic based on comparisons (e.g., profit > 5).
FlowLoopNode	Repeats actions with safety caps for iterations and duration.
FlowSequenceNode	Executes a list of child nodes in linear order.
FlowParallelNode	Executes multiple branches simultaneously.
FlowWaitNode	Pauses execution for a specified duration.
FlowStopNode	Terminates the current flow execution.

Sources: packages/flows/src/interpreter/interpreter.ts:114-126, packages/flows/README.md:197-207

Logical Intent Classification

The engine classifies intent based on keywords within the raw text to guide AST construction. For example, if the text includes "bonus," it is tagged as bonus_collection; if "spin" or "play" is present, it is tagged as play_strategy. This classification helps the buildFlowAST method determine which platform or game actions should be prioritized in the sequence.

Sources: packages/flows/src/interpreter/interpreter.ts:71-79

Responsible Play Guardrails

A critical output of the FlowInterpreter is the attachment of mandatory guardrails to every FlowDefinition. These are generated during Pass 4 by the ResponsiblePlayValidator. These guardrails ensure that automation does not exceed safe limits, even if the user does not specify them in their natural language input.

Sources: packages/flows/src/interpreter/interpreter.ts:36-41, AGENTS.md:231-236

Mandatory System Guardrails

• max_duration: Default session cap (e.g., 2 hours).
• cool_down_check: Mandatory check to block execution during user-configured cool-down periods.
• Loop caps: Every FlowLoopNode must have maxIterations ≤ 100 and maxDuration ≤ 30 minutes.

Sources: CLAUDE.md:118-125, packages/flows/src/interpreter/interpreter.ts:205-207

Implementation Example

The following snippet demonstrates how the FlowInterpreter is invoked within the @sweepbot/flows package to interpret a user request for a daily bonus routine.

import { FlowInterpreter } from '@sweepbot/flows'

const interpreter = new FlowInterpreter()
const result = await interpreter.interpret({
  userId: 'user-123',
  rawInput: 'Every day at 3:30, open Chumba and grab my daily bonus'
})

// result.flow.trigger -> { type: 'scheduled', cron: '30 3 * * *', ... }
// result.flow.rootNode -> SequenceNode containing open_platform and claim_bonus actions

Sources: packages/flows/src/interpreter/interpreter.ts:27-58, packages/flows/README.md:143-169

Conclusion

The NLP Flow Interpreter Engine is the primary intelligence layer of SweepBot's automation suite. By successfully mapping natural language to a rigid, validatable AST, it enables users to create powerful casino routines while the system automatically maintains safety and compliance through mandatory responsible play guardrails. This engine provides the foundation for Phase 2 automation execution and subsequent scheduling components.

Sources: README.md:16-18, packages/flows/README.md:3-5