gem-contract-engine 1.0.1
A declarative, validation-first policy engine for contract-based business rules
License: MIT
Requires Python: >=3.8
Keywords: policy, validation, contracts, dsl, business-rules, compliance

# 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:

```bash
# 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

```gem
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:

```bash
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:
```bash
gem validate <contract-file.gem>
```

Run execution with JSON input:
```bash
gem run <contract-file.gem> <input.json>
```

Check version:
```bash
gem version
```

### Library Usage

Import the public API into your Python applications:

```python
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:

```python
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](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