FlatLand: A Constraint-based Logic Engine for LLM-driven Simulations

FlatLand is a Python library that provides a constraint-based logic engine for creating and running simulations, particularly those generated by Large Language Models (LLMs).

Features

• Rule-based Logic Engine: Define and evaluate rules with conditions and actions
• State Management: Track and manage simulation state with history and diffing
• Built-in Functions: Common utility functions for grid-based environments
• LLM Integration: Generate environments from natural language descriptions using OpenAI's API
• Validation: Schema validation for environments and rules
• Conflict Detection: Identify and report conflicts between rules
• Dependency Resolution: Analyze and resolve dependencies between rules

Installation

pip install flatland

Quick Start

from flatland import LogicEngine, generate_environment

# Generate an environment from a description
env = generate_environment("Create a simple maze with a player and a goal")

# Or load from a JSON file
import json
with open('examples/sokoban.json', 'r') as f:
    env_data = json.load(f)

# Create a logic engine and load the environment
engine = LogicEngine()
engine.load_environment(env_data)

# Process player input
result = engine.process_input("right")
print(result["state"])  # Show the new state
print(result["changes"])  # Show what changed

# Run a simulation step
result = engine.step()

Environment Definition

Environments in FlatLand are defined using a JSON structure:

{
  "metadata": {
    "name": "Simple Maze",
    "description": "A simple maze environment"
  },
  "initial_state": {
    "grid": {
      "width": 5,
      "height": 5,
      "cells": [
        [1, 1, 1, 1, 1],
        [1, 0, 0, 0, 1],
        [1, 0, 2, 0, 1],
        [1, 0, 0, 0, 1],
        [1, 1, 1, 1, 1]
      ]
    },
    "entities": [
      {
        "id": "player",
        "type": "player",
        "position": [2, 2],
        "properties": {
          "movable": true
        }
      }
    ]
  },
  "rules": [
    {
      "name": "player_movement",
      "type": "conditional",
      "priority": 1,
      "when": {
        "condition": "entity.type == 'player' && can_move_to(target_x, target_y)",
        "entities": ["player"]
      },
      "then": {
        "action": "move",
        "parameters": {
          "position": ["target_x", "target_y"]
        }
      }
    }
  ]
}

Core Components

LogicEngine

The main engine that evaluates rules and manages state transitions.

from flatland import LogicEngine

engine = LogicEngine()
engine.load_environment(env_data)

Rule

Represents a single rule in the logic system.

from flatland import Rule

rule = Rule(
    name="player_movement",
    type="conditional",
    priority=1,
    when={
        "condition": "entity.type == 'player' && can_move_to(target_x, target_y)",
        "entities": ["player"]
    },
    then={
        "action": "move",
        "parameters": {
            "position": ["target_x", "target_y"]
        }
    }
)

StateManager

Manages the simulation state and history.

from flatland import StateManager

state_manager = StateManager()
state_manager.set_initial_state(initial_state)
current_state = state_manager.get_current_state()

SchemaValidator

Validates environment definitions and rules.

from flatland import SchemaValidator

validator = SchemaValidator()
is_valid, errors = validator.validate_environment(env_data)

BuiltInFunctions

Provides utility functions for grid-based environments.

from flatland import BuiltInFunctions

# Check if a position is valid for movement
can_move = BuiltInFunctions.check_movement(state, x, y)

# Create a context with all built-in functions
context = BuiltInFunctions.create_function_context(state)

LLM Integration

FlatLand integrates with OpenAI's API to generate environments from natural language descriptions.

from flatland import generate_environment, set_api_key

# Set your OpenAI API key
set_api_key("your-api-key")

# Generate an environment
env = generate_environment(
    "Create a Sokoban-like puzzle with a player, two boxes, and two goals",
    style_guidance="minimalist, 8x8 grid"
)

Examples

Check out the examples/ directory for sample environments and usage:

• examples/sokoban.json: A Sokoban puzzle environment
• examples/snake.json: A Snake game environment
• examples/run_sokoban.py: Run a Sokoban environment
• examples/run_llm_env.py: Generate and run an environment using LLM
• examples/generate_custom_env.py: Generate a custom environment

License

This project is licensed under the BSD License - see the LICENSE file for details.