Predicate Evaluator

Purpose

VCollab applications frequently need to evaluate conditions — "is this value greater than X?", "does this string contain Y?", "does this list include Z?" These checks appear in filtering, validation, workflow conditionals, and routing logic.

The vcti-predicate package provides two entry points — check() and evaluate() — that resolve the right comparison logic based on the operand types, apply type-appropriate normalization, and support extensible operators with group-level and operator-specific options.

This package has zero external dependencies.

Installation

pip install vcti-predicate

In requirements.txt

vcti-predicate>=1.0.7

In pyproject.toml dependencies

dependencies = [
    "vcti-predicate>=1.0.7",
]

Quick Start

from vcti.predicate import check

# ── Binary: check(lhs, symbol, rhs) ──

# String (case-insensitive by default)
check("Hello", "==", "hello")         # True
check("filename.pdf", "$=", "pdf")    # True
check("filename", "?=", "name")       # True

# Integer (exact)
check(5, ">", 3)     # True
check(5, "==", 5)    # True

# Float (with tolerance)
check(1.0, "==", 1.001, tolerance=0.01)   # True

# Case-sensitive via modifier or suffix
check("Hello", "==", "hello", case_sensitive=True)  # False
check("Hello", "^=cs", "Hello")                     # True

# Collection operations
check(2, "@=", [1, 2, 3])                  # True
check(["a", "b"], "all", ["a", "b", "c"])  # True

# Regex matching with options
check("test123", "~=", r"\d+")                          # True
check("line1\nline2", "~=", r"^line2", multiline=True)  # True

# Negation
check("hello", "!^=", "xyz")    # True (does not start with)
check("hello", "!~=", r"\d+")   # True (no digits)
check(4, "!@=", [1, 2, 3])     # True (not in list)

# Range (rhs is a tuple of bounds)
check(5, "between", (1, 10))       # True
check(0, "!between", (1, 10))      # True

# ── Unary: check(value, symbol) ──

check("", "is_empty")           # True
check(None, "exists")           # False
check("/tmp/f.txt", "is_file")  # True (if file exists)
check("/tmp", "is_dir")         # True (if directory exists)

Entry Points

Both use the same resolution, normalization, and dispatch engine.

Symbol Summary

Comparison

String

Regex

Unary

Range

Modifier Suffixes

Append cs or ic to string symbols for case control: ^=cs, $=ic, ?=cs, @=ic, ~=cs

For the complete symbol reference, see the Symbol Reference.

Modifiers

Pass modifiers as keyword arguments to control behavior:

check("Hello", "==", "hello", case_sensitive=True)   # False
check(1.0, "==", 1.001, tolerance=0.01)              # True
check(5, "between", (1, 10), inclusive=False)         # True
check("text", "~=", r"^line", multiline=True)        # regex option

Documentation

• Usage Patterns — Real-world recipes and integration patterns
• Design — Concepts, architecture decisions, and trade-offs
• Source Guide — Execution flow traces for developers
• Extension Guide — How to add operators, groups, and symbols
• Symbol Reference — Complete symbol tables
• API Reference — Autodoc for all modules