gem-contract-engine 1.0.0

A declarative, validation-first policy engine for contract-based business rules

Gem Contract Engine

A declarative, validation-first policy engine for contract-based business rules.

Quick Start

Install Gem and validate your first contract in 30 seconds:

# Install via pip
pip install gem-contract-engine

# Create a simple contract
echo 'contract HelloWorld {
  intent: "Validate basic user access"
  inputs: userId, role
  guarantees:
    role in ["admin", "user"]
  constraints:
    userId != 0
}' > hello.gem

# Validate the contract
gem validate hello.gem

# Run validation with input data
echo '{"userId": 123, "role": "admin"}' > input.json
gem run hello.gem input.json

Output:

✓ Contract validation passed (1 contracts)
✓ Execution satisfies contract 'HelloWorld'

What Problem Gem Solves

Most systems embed business rules in application code. This creates tight coupling between policy and implementation, making it difficult to modify rules without changing code. When business logic changes, you must redeploy applications. When validation rules are scattered across codebases, it's hard to audit what rules are enforced. Gem separates policy from implementation, allowing teams to validate business rules before execution.

What Gem Is

Declarative: You specify what rules must hold, not how to enforce them.

Contract-based: Every program defines intent, inputs, guarantees, and constraints.

Validation-first: Contracts validate before execution, catching policy violations early.

Library-first: Embeddable engine with structured APIs, not a standalone language.

What Gem Is NOT

Gem is NOT a general-purpose programming language. It cannot loop, branch, or perform general computation.

Gem is NOT a replacement for Python, JavaScript, or other general-purpose languages. It has no loops, conditionals, variables, or functions.

One Realistic Example

contract UserSubscription {
  intent: "Validate user subscription access"
  inputs: userId, subscriptionType, subscriptionDate, accountStatus
  derived:
    isPremium = subscriptionType == "premium",
    isExpired = subscriptionDate < "2023-01-01",
    isActiveAccount = accountStatus == "active"
  guarantees:
    isActiveAccount == true,
    isPremium == true or subscriptionType == "basic"
  constraints:
    userId in [0, -1]  # userId should NOT be 0 or -1
}

This contract specifies that active accounts with valid subscriptions (premium or basic) can access services, with invalid user IDs explicitly forbidden.

Installation

Install the Gem Contract Engine via pip:

pip install gem-contract-engine

This installs:

• The gem CLI command for contract validation and execution
• The gem Python package for programmatic use
• All required dependencies (colorama only)

Requirements: Python 3.8+

Usage

CLI Commands

Validate contracts:

gem validate <contract-file.gem>

Run execution with JSON input:

gem run <contract-file.gem> <input.json>

Check version:

gem version

Library Usage

Import the public API into your Python applications:

from gem import validate_contract_source, run_execution

# Validate contract syntax and semantics
contract_source = """
contract UserAccess {
  intent: "Control user access"
  inputs: userId, role
  guarantees:
    role in ["admin", "user"]
}
"""

result = validate_contract_source(contract_source)
if result.success:
    print(f"Validated {result.contracts_validated} contracts")
else:
    for error in result.errors:
        print(f"Policy error: {error}")

# Run execution against contract
execution_result = run_execution(contract_source, execution_source)

The API returns structured results with no side effects. All functions return pure data for programmatic processing.

Using Gem as a Library

Import the public API into your Python applications:

from gem import validate_contract_source, run_execution

# Validate contract syntax and semantics
contract_source = """
contract UserAccess {
  intent: "Control user access"
  inputs: userId, role
  guarantees:
    role in ["admin", "user"]
}
"""

result = validate_contract_source(contract_source)
if result.success:
    print(f"Validated {result.contracts_validated} contracts")
else:
    for error in result.errors:
        print(f"Policy error: {error}")

# Run execution against contract
execution_result = run_execution(contract_source, execution_source)

The API returns structured results with no side effects. All functions return pure data for programmatic processing.

Who Should Use Gem

• Backend infrastructure teams managing policy engines
• Platform teams centralizing business rules
• Organizations with complex validation requirements
• Teams needing audit trails for business rule compliance

Who Should NOT Use Gem

• Frontend-heavy applications requiring UI logic
• General-purpose scripting tasks
• Computation-heavy algorithms or data processing
• Projects requiring general programming constructs

Project Status

The core is frozen with backward compatibility guaranteed. The language is small by design - it solves policy validation, nothing more.

Stability & Backward Compatibility

Gem is production-ready with guaranteed backward compatibility:

• Frozen Core: The DSL syntax and runtime semantics are permanently frozen (see CORE_FROZEN.md)
• No Breaking Changes: All future updates maintain API compatibility
• Validation-First: Contracts validate completely before execution
• Security Isolated: Runtime execution is sandboxed with strict context isolation

Organizations can adopt Gem with confidence knowing policies will not break across updates.

Philosophy

• Trust > power: Verifiable contracts over complex logic
• Validation > execution: Catch errors before they cause problems
• Explicit intent > clever logic: Clear policies over implicit behavior