context-compiler 0.9.0.dev8__tar.gz → 0.9.0.dev9__tar.gz

{context_compiler-0.9.0.dev8 → context_compiler-0.9.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: context-compiler
-Version: 0.9.0.dev8
+Version: 0.9.0.dev9
 Summary: Deterministic conversational state engine for LLM applications.
 Project-URL: Homepage, https://github.com/rlippmann/context-compiler
 Project-URL: Repository, https://github.com/rlippmann/context-compiler

{context_compiler-0.9.0.dev8 → context_compiler-0.9.0.dev9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "context-compiler"
-version = "0.9.0dev8"
+version = "0.9.0dev9"
 description = "Deterministic conversational state engine for LLM applications."
 readme = "README.md"
 requires-python = ">=3.11"

{context_compiler-0.9.0.dev8 → context_compiler-0.9.0.dev9}/src/context_compiler/engine.py

@@ -19,7 +19,7 @@ from .const import (
     STATE_PREMISE,
     STATE_VERSION,
 )
-from .grammar import CanonicalDirective, _DirectiveKind, decompose_directive
+from .grammar import CanonicalDirective, DirectiveKind, decompose_directive
 
 PolicyValue = Literal["use", "prohibit"]
 
@@ -129,61 +129,26 @@ class Engine:
     ) -> Decision | None:
         candidate_state = self._state if state is None else state
         # Single error path: all error outcomes are detected before any mutation.
-        if directive.kind in {_DirectiveKind.SET_PREMISE, _DirectiveKind.CHANGE_PREMISE}:
-            value = directive.operands["value"]
-            if _sanitize_premise_value(value) == "":
-                if directive.kind is _DirectiveKind.SET_PREMISE:
-                    return _error(
-                        "Premise value cannot be empty.\n"
-                        "Use 'set premise <value>' with a non-empty value."
-                    )
-                return _error(
-                    "Premise value cannot be empty.\n"
-                    "Use 'change premise to <value>' with a non-empty value."
-                )
-
-        if (
-            directive.kind is _DirectiveKind.REMOVE_POLICY
-            and _normalize_item(directive.operands["item"]) == ""
-        ):
-            return _error(
-                "Policy item cannot be empty.\nUse 'remove policy <item>' with a non-empty value."
-            )
-
-        if (
-            directive.kind is _DirectiveKind.USE_ITEM
-            and _normalize_item(directive.operands["item"]) == ""
-        ):
-            return _error("Policy item cannot be empty.\nUse 'use <item>' with a non-empty value.")
-
-        if (
-            directive.kind is _DirectiveKind.PROHIBIT_ITEM
-            and _normalize_item(directive.operands["item"]) == ""
-        ):
-            return _error(
-                "Policy item cannot be empty.\nUse 'prohibit <item>' with a non-empty value."
-            )
-
         if (
-            directive.kind is _DirectiveKind.SET_PREMISE
+            directive.kind is DirectiveKind.SET_PREMISE
             and candidate_state[STATE_PREMISE] is not None
         ):
             return _error("Premise already set.\nUse 'change premise to <value>' to modify it.")
 
         if (
-            directive.kind is _DirectiveKind.CHANGE_PREMISE
+            directive.kind is DirectiveKind.CHANGE_PREMISE
             and candidate_state[STATE_PREMISE] is None
         ):
             return _error("No premise is set.\nUse 'set premise <value>' to define one.")
 
-        if directive.kind is _DirectiveKind.USE_ITEM:
+        if directive.kind is DirectiveKind.USE_ITEM:
             item_key = _normalize_item(directive.operands["item"])
             if candidate_state[STATE_POLICIES].get(item_key) == POLICY_PROHIBIT:
                 return _error(
                     f'"{item_key}" is currently prohibited.\nRemove or replace it before using it.'
                 )
 
-        if directive.kind is _DirectiveKind.PROHIBIT_ITEM:
+        if directive.kind is DirectiveKind.PROHIBIT_ITEM:
             item_key = _normalize_item(directive.operands["item"])
             if candidate_state[STATE_POLICIES].get(item_key) == POLICY_USE:
                 return _error(
@@ -191,7 +156,7 @@ class Engine:
                     "Remove or replace it before prohibiting it."
                 )
 
-        if directive.kind is _DirectiveKind.REPLACE_USE:
+        if directive.kind is DirectiveKind.REPLACE_USE:
             new_item = directive.operands["new_item"]
             old_item = directive.operands["old_item"]
             new_key = _normalize_item(new_item)
@@ -222,27 +187,27 @@ class Engine:
     def _apply_directive(self, directive: CanonicalDirective, *, state: _State) -> _State:
         next_state = deepcopy(state)
 
-        if directive.kind is _DirectiveKind.SET_PREMISE:
+        if directive.kind is DirectiveKind.SET_PREMISE:
             next_state[STATE_PREMISE] = _sanitize_premise_value(directive.operands["value"])
             return next_state
 
-        if directive.kind is _DirectiveKind.CHANGE_PREMISE:
+        if directive.kind is DirectiveKind.CHANGE_PREMISE:
             next_state[STATE_PREMISE] = _sanitize_premise_value(directive.operands["value"])
             return next_state
 
-        if directive.kind is _DirectiveKind.USE_ITEM:
+        if directive.kind is DirectiveKind.USE_ITEM:
             item_key = _normalize_item(directive.operands["item"])
             # Idempotent directives are updates even if state does not change.
             next_state[STATE_POLICIES][item_key] = POLICY_USE
             return next_state
 
-        if directive.kind is _DirectiveKind.PROHIBIT_ITEM:
+        if directive.kind is DirectiveKind.PROHIBIT_ITEM:
             item_key = _normalize_item(directive.operands["item"])
             # Idempotent directives are updates even if state does not change.
             next_state[STATE_POLICIES][item_key] = POLICY_PROHIBIT
             return next_state
 
-        if directive.kind is _DirectiveKind.REPLACE_USE:
+        if directive.kind is DirectiveKind.REPLACE_USE:
             self._apply_replacement_explicit(
                 next_state,
                 directive.operands["new_item"],
@@ -250,16 +215,16 @@ class Engine:
             )
             return next_state
 
-        if directive.kind is _DirectiveKind.REMOVE_POLICY:
+        if directive.kind is DirectiveKind.REMOVE_POLICY:
             item_key = _normalize_item(directive.operands["item"])
             next_state[STATE_POLICIES].pop(item_key, None)
             return next_state
 
-        if directive.kind is _DirectiveKind.CLEAR_PREMISE:
+        if directive.kind is DirectiveKind.CLEAR_PREMISE:
             next_state[STATE_PREMISE] = None
             return next_state
 
-        if directive.kind is _DirectiveKind.RESET_POLICIES:
+        if directive.kind is DirectiveKind.RESET_POLICIES:
             next_state[STATE_POLICIES] = {}
             return next_state
 

{context_compiler-0.9.0.dev8 → context_compiler-0.9.0.dev9}/src/context_compiler/grammar.py

@@ -7,7 +7,7 @@ from enum import StrEnum
 from types import MappingProxyType
 
 
-class _DirectiveKind(StrEnum):
+class DirectiveKind(StrEnum):
     """Enumerate the supported canonical directive families."""
 
     SET_PREMISE = "set_premise"
@@ -21,6 +21,14 @@ class _DirectiveKind(StrEnum):
     CLEAR_STATE = "clear_state"
 
 
+class DirectiveSyntaxFailure(StrEnum):
+    """Enumerate minimal grammar failure categories for directive-shaped input."""
+
+    COMPOUND_DIRECTIVE = "compound_directive"
+    MISSING_REQUIRED_OPERAND = "missing_required_operand"
+    MALFORMED_DIRECTIVE = "malformed_directive"
+
+
 @dataclass(frozen=True, slots=True)
 class CanonicalDirective:
     """Represent one parsed canonical directive and its named operands.
@@ -30,7 +38,7 @@ class CanonicalDirective:
     """
 
     text: str
-    kind: _DirectiveKind
+    kind: DirectiveKind
     operands: MappingProxyType[str, str]
 
 
@@ -38,10 +46,14 @@ class CanonicalDirective:
 class InvalidDirectiveSyntax:
     """Represent directive-shaped input that fails canonical syntax parsing."""
 
+    failure: DirectiveSyntaxFailure = DirectiveSyntaxFailure.MALFORMED_DIRECTIVE
+    directive_kind: DirectiveKind | None = None
+    missing_operand: str | None = None
+
 
 @dataclass(frozen=True, slots=True)
 class _DirectiveSpec:
-    kind: _DirectiveKind
+    kind: DirectiveKind
     operand_names: tuple[str, ...]
     exact_text: str | None
     renderer: Callable[[MappingProxyType[str, str]], str]
@@ -126,56 +138,56 @@ def _render_exact(text: str) -> Callable[[MappingProxyType[str, str]], str]:
 
 _DIRECTIVE_SPECS = MappingProxyType(
     {
-        _DirectiveKind.SET_PREMISE: _DirectiveSpec(
-            kind=_DirectiveKind.SET_PREMISE,
+        DirectiveKind.SET_PREMISE: _DirectiveSpec(
+            kind=DirectiveKind.SET_PREMISE,
             operand_names=("value",),
             exact_text=None,
             renderer=_render_with_prefix(_SET_PREMISE_PREFIX, "value"),
         ),
-        _DirectiveKind.CHANGE_PREMISE: _DirectiveSpec(
-            kind=_DirectiveKind.CHANGE_PREMISE,
+        DirectiveKind.CHANGE_PREMISE: _DirectiveSpec(
+            kind=DirectiveKind.CHANGE_PREMISE,
             operand_names=("value",),
             exact_text=None,
             renderer=_render_with_prefix(_CHANGE_PREMISE_PREFIX, "value"),
         ),
-        _DirectiveKind.USE_ITEM: _DirectiveSpec(
-            kind=_DirectiveKind.USE_ITEM,
+        DirectiveKind.USE_ITEM: _DirectiveSpec(
+            kind=DirectiveKind.USE_ITEM,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_USE_PREFIX, "item"),
         ),
-        _DirectiveKind.PROHIBIT_ITEM: _DirectiveSpec(
-            kind=_DirectiveKind.PROHIBIT_ITEM,
+        DirectiveKind.PROHIBIT_ITEM: _DirectiveSpec(
+            kind=DirectiveKind.PROHIBIT_ITEM,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_PROHIBIT_PREFIX, "item"),
         ),
-        _DirectiveKind.REMOVE_POLICY: _DirectiveSpec(
-            kind=_DirectiveKind.REMOVE_POLICY,
+        DirectiveKind.REMOVE_POLICY: _DirectiveSpec(
+            kind=DirectiveKind.REMOVE_POLICY,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_REMOVE_POLICY_PREFIX, "item"),
         ),
-        _DirectiveKind.REPLACE_USE: _DirectiveSpec(
-            kind=_DirectiveKind.REPLACE_USE,
+        DirectiveKind.REPLACE_USE: _DirectiveSpec(
+            kind=DirectiveKind.REPLACE_USE,
             operand_names=("new_item", "old_item"),
             exact_text=None,
             renderer=_render_replace_use,
         ),
-        _DirectiveKind.CLEAR_PREMISE: _DirectiveSpec(
-            kind=_DirectiveKind.CLEAR_PREMISE,
+        DirectiveKind.CLEAR_PREMISE: _DirectiveSpec(
+            kind=DirectiveKind.CLEAR_PREMISE,
             operand_names=(),
             exact_text=_CLEAR_PREMISE_TEXT,
             renderer=_render_exact(_CLEAR_PREMISE_TEXT),
         ),
-        _DirectiveKind.RESET_POLICIES: _DirectiveSpec(
-            kind=_DirectiveKind.RESET_POLICIES,
+        DirectiveKind.RESET_POLICIES: _DirectiveSpec(
+            kind=DirectiveKind.RESET_POLICIES,
             operand_names=(),
             exact_text=_RESET_POLICIES_TEXT,
             renderer=_render_exact(_RESET_POLICIES_TEXT),
         ),
-        _DirectiveKind.CLEAR_STATE: _DirectiveSpec(
-            kind=_DirectiveKind.CLEAR_STATE,
+        DirectiveKind.CLEAR_STATE: _DirectiveSpec(
+            kind=DirectiveKind.CLEAR_STATE,
             operand_names=(),
             exact_text=_CLEAR_STATE_TEXT,
             renderer=_render_exact(_CLEAR_STATE_TEXT),
@@ -305,11 +317,24 @@ def _parse_replace_use(trimmed_text: str) -> CanonicalDirective | None:
         return None
     return CanonicalDirective(
         text=trimmed_text,
-        kind=_DirectiveKind.REPLACE_USE,
+        kind=DirectiveKind.REPLACE_USE,
         operands=MappingProxyType({"new_item": new_item, "old_item": old_item}),
     )
 
 
+def _invalid_directive_syntax(
+    failure: DirectiveSyntaxFailure,
+    *,
+    directive_kind: DirectiveKind | None = None,
+    missing_operand: str | None = None,
+) -> InvalidDirectiveSyntax:
+    return InvalidDirectiveSyntax(
+        failure=failure,
+        directive_kind=directive_kind,
+        missing_operand=missing_operand,
+    )
+
+
 def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSyntax | None:
     """Parse one canonical directive into its semantic kind and operands.
 
@@ -326,50 +351,76 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
     if not _starts_with_directive_family(trimmed_text):
         return None
     if _contains_multiple_canonical_directives(trimmed_text):
-        return InvalidDirectiveSyntax()
-
-    invalid_result = InvalidDirectiveSyntax()
+        return _invalid_directive_syntax(DirectiveSyntaxFailure.COMPOUND_DIRECTIVE)
 
     normalized = _normalized_for_matching(trimmed_text)
 
     if normalized == _CLEAR_PREMISE_TEXT:
         return CanonicalDirective(
-            text=text, kind=_DirectiveKind.CLEAR_PREMISE, operands=MappingProxyType({})
+            text=text, kind=DirectiveKind.CLEAR_PREMISE, operands=MappingProxyType({})
         )
     if normalized == _RESET_POLICIES_TEXT:
         return CanonicalDirective(
             text=text,
-            kind=_DirectiveKind.RESET_POLICIES,
+            kind=DirectiveKind.RESET_POLICIES,
             operands=MappingProxyType({}),
         )
     if normalized == _CLEAR_STATE_TEXT:
         return CanonicalDirective(
-            text=text, kind=_DirectiveKind.CLEAR_STATE, operands=MappingProxyType({})
+            text=text, kind=DirectiveKind.CLEAR_STATE, operands=MappingProxyType({})
+        )
+
+    if normalized == "set premise":
+        return _invalid_directive_syntax(
+            DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+            directive_kind=DirectiveKind.SET_PREMISE,
+            missing_operand="value",
         )
 
     if normalized.startswith("set premise "):
         match = _SET_PREMISE_RE.fullmatch(trimmed_text)
         if match is None:
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MALFORMED_DIRECTIVE,
+                directive_kind=DirectiveKind.SET_PREMISE,
+            )
         value = match.group("value")
         if not _operand_has_content(value) or _operand_starts_with_token(value, "to"):
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MALFORMED_DIRECTIVE,
+                directive_kind=DirectiveKind.SET_PREMISE,
+            )
         return CanonicalDirective(
             text=text,
-            kind=_DirectiveKind.SET_PREMISE,
+            kind=DirectiveKind.SET_PREMISE,
             operands=MappingProxyType({"value": value}),
         )
 
+    if normalized == "change premise to":
+        return _invalid_directive_syntax(
+            DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+            directive_kind=DirectiveKind.CHANGE_PREMISE,
+            missing_operand="value",
+        )
+
     if normalized.startswith("change premise to "):
         match = _CHANGE_PREMISE_RE.fullmatch(trimmed_text)
         if match is None:
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.CHANGE_PREMISE,
+                missing_operand="value",
+            )
         value = match.group("value")
         if not _operand_has_content(value):
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.CHANGE_PREMISE,
+                missing_operand="value",
+            )
         return CanonicalDirective(
             text=text,
-            kind=_DirectiveKind.CHANGE_PREMISE,
+            kind=DirectiveKind.CHANGE_PREMISE,
             operands=MappingProxyType({"value": value}),
         )
 
@@ -377,58 +428,115 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
     if replacement is not None:
         return replacement
 
+    if normalized == "use":
+        return _invalid_directive_syntax(
+            DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+            directive_kind=DirectiveKind.USE_ITEM,
+            missing_operand="item",
+        )
+
     if normalized.startswith("use "):
         match = _USE_RE.fullmatch(trimmed_text)
         if match is None:
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.USE_ITEM,
+                missing_operand="item",
+            )
         item = match.group("item")
         normalized_item = _normalized_for_matching(item)
-        if (
-            not _operand_has_content(item)
-            or normalized_item.startswith("instead of ")
-            or normalized_item.endswith(" instead of")
-            or _INSTEAD_OF_DELIMITER in normalized_item
-        ):
-            return invalid_result
+        if not _operand_has_content(item):
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.USE_ITEM,
+                missing_operand="item",
+            )
+        if normalized_item == "instead of" or normalized_item.startswith("instead of "):
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.REPLACE_USE,
+                missing_operand="new_item",
+            )
+        if normalized_item.endswith(" instead of"):
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.REPLACE_USE,
+                missing_operand="old_item",
+            )
+        if _INSTEAD_OF_DELIMITER in normalized_item:
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MALFORMED_DIRECTIVE,
+                directive_kind=DirectiveKind.USE_ITEM,
+            )
         return CanonicalDirective(
             text=text,
-            kind=_DirectiveKind.USE_ITEM,
+            kind=DirectiveKind.USE_ITEM,
             operands=MappingProxyType({"item": item}),
         )
 
+    if normalized == "prohibit":
+        return _invalid_directive_syntax(
+            DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+            directive_kind=DirectiveKind.PROHIBIT_ITEM,
+            missing_operand="item",
+        )
+
     if normalized.startswith("prohibit "):
         match = _PROHIBIT_RE.fullmatch(trimmed_text)
         if match is None:
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.PROHIBIT_ITEM,
+                missing_operand="item",
+            )
         item = match.group("item")
         if not _operand_has_content(item):
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.PROHIBIT_ITEM,
+                missing_operand="item",
+            )
         return CanonicalDirective(
             text=text,
-            kind=_DirectiveKind.PROHIBIT_ITEM,
+            kind=DirectiveKind.PROHIBIT_ITEM,
             operands=MappingProxyType({"item": item}),
         )
 
+    if normalized == "remove policy":
+        return _invalid_directive_syntax(
+            DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+            directive_kind=DirectiveKind.REMOVE_POLICY,
+            missing_operand="item",
+        )
+
     if normalized.startswith("remove policy "):
         match = _REMOVE_POLICY_RE.fullmatch(trimmed_text)
         if match is None:
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.REMOVE_POLICY,
+                missing_operand="item",
+            )
         item = match.group("item")
         if not _operand_has_content(item):
-            return invalid_result
+            return _invalid_directive_syntax(
+                DirectiveSyntaxFailure.MISSING_REQUIRED_OPERAND,
+                directive_kind=DirectiveKind.REMOVE_POLICY,
+                missing_operand="item",
+            )
         return CanonicalDirective(
             text=text,
-            kind=_DirectiveKind.REMOVE_POLICY,
+            kind=DirectiveKind.REMOVE_POLICY,
             operands=MappingProxyType({"item": item}),
         )
 
-    return invalid_result
+    return _invalid_directive_syntax(DirectiveSyntaxFailure.MALFORMED_DIRECTIVE)
 
 
-def _render_directive(kind: _DirectiveKind | str, /, **operands: str) -> str:
+def _render_directive(kind: DirectiveKind | str, /, **operands: str) -> str:
     """Produce canonical directive text from a semantic kind and operands."""
     try:
-        normalized_kind = kind if isinstance(kind, _DirectiveKind) else _DirectiveKind(kind)
+        normalized_kind = kind if isinstance(kind, DirectiveKind) else DirectiveKind(kind)
         spec = _DIRECTIVE_SPECS[normalized_kind]
     except (KeyError, ValueError) as exc:
         raise ValueError(f"Unsupported directive kind: {kind!r}") from exc
@@ -462,6 +570,8 @@ def _render_directive(kind: _DirectiveKind | str, /, **operands: str) -> str:
 
 
 __all__ = [
+    "DirectiveKind",
+    "DirectiveSyntaxFailure",
     "CanonicalDirective",
     "InvalidDirectiveSyntax",
     "decompose_directive",