Non-determinism

When to Use

Non-deterministic operations are needed for:

External API calls
LLM and AI model calls
Random number generation
Any operation that might vary between nodes

Equality Principle

GenLayer provides strict_eq for exact-match consensus and custom validator functions (run_nondet_unsafe) for everything else. Convenience wrappers like prompt_comparative and prompt_non_comparative exist for common patterns. For detailed information, see Equivalence Principle.

Strict Equality

Requires exact matches between validator outputs. Use when all nodes can converge on the same normalized value — e.g., fetching objective data from an API and extracting a structured result:

def fetch_current_block():
    response = gl.nondet.web.request("https://api.example.com/block/latest")
    data = json.loads(response)
    return json.dumps({"height": data["height"], "hash": data["hash"]}, sort_keys=True)
 
# All validators must return the exact same string
result = gl.eq_principle.strict_eq(fetch_current_block)

Note: strict_eq is not suitable for random number generation or LLM calls, since those inherently produce different results on each node. Use a custom validator function or one of the convenience wrappers below for those cases.

Comparative (Convenience Shortcut)

A convenience wrapper where both leader and validators perform the same task, then an LLM compares results using your criteria:

def comparative_example():
    return gl.nondet.web.request("https://api.example.com/count")
 
# Results are compared with acceptable margin of error
result = gl.eq_principle.prompt_comparative(
    comparative_example,
    "Results should not differ by more than 5%"
)

Non-Comparative (Convenience Shortcut)

A convenience wrapper where validators evaluate the leader's output against criteria without repeating the task:

result = gl.eq_principle.prompt_non_comparative(
    input="This product is amazing!",
    task="Classify the sentiment as positive, negative, or neutral",
    criteria="""
        Output must be one of: positive, negative, neutral
        Consider context and tone
    """
)

Custom Validator Functions

For full control over consensus logic, write a custom leader/validator pair with run_nondet_unsafe. This is the recommended approach for most contracts:

def custom_consensus_example(self, data: str):
    def leader_fn():
        # Leader performs the operation
        response = gl.nondet.exec_prompt(f"Rate this sentiment 1-10: <data>{data}</data>. Answer only with integer, without reasoning")
        return int(response.strip())
 
    def validator_fn(leader_result):
        own_score = leader_fn()
 
        if isinstance(leader_result, Exception):
            return False
 
        # Accept if within acceptable range
        return abs(own_score - leader_result) <= 2
 
    return gl.vm.run_nondet_unsafe(leader_fn, validator_fn)

Operations

Accessing External Data

Use non-deterministic blocks for external API calls. For more web access examples, see Web Access:

@gl.public.write
def fetch_external_data(self):
    def fetch_data():
        # External API call - inherently non-deterministic
        response = gl.nondet.web.request("https://example.com/data")
        return response
 
    # Consensus ensures all validators agree on the result
    data = gl.eq_principle.strict_eq(fetch_data)
    return data

LLM Integration

Execute AI prompts using comparative principle. For more detailed examples, see Calling LLMs:

@gl.public.write
def ai_decision(self, prompt: str):
    def call_llm():
        response = gl.nondet.exec_prompt(prompt)
        return response.strip()
 
    # Use comparative principle for LLM response consensus
    decision = gl.eq_principle.prompt_comparative(
        call_llm,
        principle="Responses should be semantically equivalent in meaning"
    )
    return decision

Random Calling LLMs