ahvn.utils.klop module

Unified filter builder for all KL backends.

This module provides a unified filter system that creates backend-agnostic JSON intermediate representation (IR) which can be compiled to different backend formats (SQL, Vector DB, MongoDB).

Architecture: - Stage 1 (Shared): expr(**kwargs) creates JSON IR - Stage 2 (Backend-Specific): Adapters compile JSON IR to target format

• OrmFilterAdapter → SQLAlchemy (SQL)

• VdbFilterAdapter → LlamaIndex MetadataFilters (Vector DB)

• MdbFilterAdapter → MongoDB MQL (MongoDB)

示例

>>> # Stage 1: Create backend-agnostic JSON IR
>>> expr = KLOp.expr(
...     priority=KLOp.BETWEEN(0, 100),
...     status=KLOp.IN(["active", "pending"])
... )
>>> # Result: {'AND': [
...     {'FIELD:priority': {'AND': [{'>=': 0}, {'<=': 100}]}},
...     {'FIELD:status': {'OR': [{'IN': ['active', 'pending']}]}}
... ]}

>>> # Stage 2: Compile to backend-specific format (via adapters)
>>> # sql_clause = OrmFilterAdapter.parse(orms, expr)
>>> # vdb_filters = VdbFilterAdapter.parse(expr)
>>> # mql_query = MdbFilterAdapter.parse(expr)

class ahvn.utils.klop.KLOp

基类：object

Unified filter builder for all KL backends.

This class provides a two-stage architecture: 1. expr(**kwargs) - Creates backend-agnostic JSON IR (shared) 2. parse(expr) - Compiles JSON IR to backend format (via adapters)

Supported backends: - SQL/SQLAlchemy (OrmFilterAdapter) - Vector DB/LlamaIndex (VdbFilterAdapter) - MongoDB/MQL (MdbFilterAdapter)

The JSON IR format uses: - "FIELD:<name>" keys to indicate field context - Operator keys: "==", "!=", "<", "<=", ">", ">=", "LIKE", "ILIKE", "IN" - Logical operators: "AND", "OR", "NOT" - Special operators: "NF", "JSON" - None value: field existence check (MongoDB)

示例

>>> # Create JSON IR
>>> expr = KLOp.expr(
...     priority=KLOp.BETWEEN(0, 100),
...     status=KLOp.IN(["active", "pending"]),
...     description=KLOp.LIKE("%test%")
... )
>>>
>>> # Compile to backend-specific format (via adapters)
>>> # sql_clause = OrmFilterAdapter.parse(orms, expr)
>>> # vdb_filters = VdbFilterAdapter.parse(expr)
>>> # mql_query = MdbFilterAdapter.parse(expr)

LIKE

_LIKE 的别名

ILIKE

_ILIKE 的别名

BETWEEN

_BETWEEN 的别名

LT

_LT 的别名

LTE

_LTE 的别名

GT

_GT 的别名

GTE

_GTE 的别名

AND

_AND 的别名

OR

_OR 的别名

NOT

_NOT 的别名

IN

_OR 的别名

NF

_NF 的别名

JSON

_JSON 的别名

static expr(**kwargs)

Parse multiple filter conditions into a JSON filter structure.

This is the main entry point for creating backend-agnostic filter expressions. The resulting JSON IR can be compiled to any backend format using the appropriate adapter.

参数:

**kwargs -- Filter conditions as key-value pairs.

返回类型:

Dict[str, Any]

返回:

Dictionary containing the parsed filter conditions in JSON IR format. Uses "FIELD:<name>" keys to indicate field context.

示例

>>> # Simple conditions
>>> KLOp.expr(status="active", priority=50)
{'AND': [
    {'FIELD:status': {'==': 'active'}},
    {'FIELD:priority': {'==': 50}}
]}

>>> # Complex conditions
>>> KLOp.expr(
...     description=KLOp.NOT("def"),
...     version="v1.0.0",
...     priority=KLOp.BETWEEN(0, 100)
... )
{
    'AND': [
        {'FIELD:description': {'NOT': {'==': 'def'}}},
        {'FIELD:version': {'==': 'v1.0.0'}},
        {'FIELD:priority': {'AND': [{'>=': 0}, {'<=': 100}]}}
    ]
}

>>> # MongoDB-specific features
>>> KLOp.expr(
...     metadata=KLOp.JSON(role="admin"),
...     tags=KLOp.NF(slot="type", value="security")
... )
{
    'AND': [
        {'FIELD:metadata': {'JSON': {'role': {'==': 'admin'}}}},
        {'FIELD:tags': {'NF': {'slot': 'type', 'value': 'security'}}}
    ]
}

>>> # JSON with multiple fields (AND of all conditions)
>>> KLOp.expr(
...     metadata=KLOp.JSON(type="categorical", status="active", count=KLOp.GT(100))
... )
{
    'AND': [
        {'FIELD:metadata': {'JSON': {
            'type': {'==': 'categorical'},
            'status': {'==': 'active'},
            'count': {'>': 100}
        }}}
    ]
}