context-compiler 0.9.0.dev5__tar.gz → 0.9.0.dev6__tar.gz

{context_compiler-0.9.0.dev5 → context_compiler-0.9.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-compiler
-Version: 0.9.0.dev5
+Version: 0.9.0.dev6
 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.dev5 → context_compiler-0.9.0.dev6}/pyproject.toml

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

{context_compiler-0.9.0.dev5 → context_compiler-0.9.0.dev6}/src/context_compiler/grammar.py

@@ -23,7 +23,12 @@ class DirectiveKind(StrEnum):
 
 @dataclass(frozen=True, slots=True)
 class ValidatedDirective:
-    """Classify text as one canonical directive kind without exposing operands."""
+    """Classify accepted input text as one canonical directive kind.
+
+    ``text`` preserves the accepted input text used for classification rather
+    than a canonical rendered representation, so caller casing and formatting
+    may remain visible here.
+    """
 
     text: str
     kind: DirectiveKind
@@ -31,7 +36,13 @@ class ValidatedDirective:
 
 @dataclass(frozen=True, slots=True)
 class CanonicalDirective:
-    """Represent one parsed canonical directive and its named operands."""
+    """Represent one parsed canonical directive and its named operands.
+
+    ``text`` preserves the original accepted input text. It may retain caller
+    formatting or casing and is not canonical serialized directive text; use
+    :func:`render_directive` to produce canonical directive text from semantic
+    kind and operands.
+    """
 
     text: str
     kind: DirectiveKind
@@ -182,10 +193,11 @@ def _operand_starts_with_token(value: str, token: str) -> bool:
 def match_canonical_directive_start(text: str, start: int) -> int | None:
     """Locate a canonical directive prefix at a given character position.
 
-    This classifies whether canonical directive syntax begins at ``start`` and,
-    when it does, returns the index immediately after the directive keyword
-    prefix. It does not parse operands, validate the full directive payload, or
-    evaluate multi-directive state semantics.
+    This is a shallow syntax-start matcher: it classifies whether canonical
+    directive syntax begins at ``start`` and, when it does, returns the index
+    immediately after the directive keyword prefix. It does not parse operands,
+    validate the full directive payload, or evaluate multi-directive state
+    semantics.
     """
     if start < 0 or start >= len(text):
         return None
@@ -246,10 +258,11 @@ def _match_directive_token(
 def contains_multiple_canonical_directives(text: str) -> bool:
     """Report whether text contains more than one canonical directive start.
 
-    This detects compound directive text by looking for multiple canonical
-    directive prefixes in the same input. It does not parse directive operands,
-    repair malformed text, or determine whether a whole string should be
-    accepted as a single directive.
+    This detects compound directive structure by looking for multiple canonical
+    directive prefixes in the same input. It is not a replacement for full
+    directive validation, and it does not parse directive operands, repair
+    malformed text, or determine whether a whole string should be accepted as a
+    single directive.
     """
     first_start = match_canonical_directive_start(text, 0)
     if first_start is None:
@@ -290,8 +303,10 @@ def decompose_directive(text: str) -> CanonicalDirective | None:
 
     This determines whether ``text`` is a single canonical directive and, when
     it is, returns the directive kind plus canonical operand names with the
-    original operand text preserved. It does not repair input, infer intent, or
-    evaluate directive effects against compiler state.
+    original operand text preserved. Callers can determine whether ``text`` is
+    a complete canonical directive by checking whether this returns a non-`None`
+    result. It does not repair input, infer intent, or evaluate directive
+    effects against compiler state.
     """
     trimmed_text = _trim_ascii_whitespace(text)
     if trimmed_text == "":
@@ -398,9 +413,11 @@ def validate_directive(text: str) -> ValidatedDirective | None:
     """Classify whether text is a canonical directive.
 
     This determines whether ``text`` belongs to one canonical directive family
-    and returns only the normalized semantic kind needed for classification. It
-    does not expose operands, render directives, repair malformed text, or
-    evaluate any state transition.
+    and returns only the normalized semantic kind needed for classification.
+    Callers can determine whether ``text`` is a canonical directive by checking
+    whether this returns a non-`None` result while only receiving
+    classification information. It does not expose operands, render directives,
+    repair malformed text, or evaluate any state transition.
     """
     parsed = decompose_directive(text)
     if parsed is None:
@@ -408,18 +425,8 @@ def validate_directive(text: str) -> ValidatedDirective | None:
     return ValidatedDirective(text=parsed.text, kind=parsed.kind)
 
 
-def is_canonical_directive(text: str) -> bool:
-    """Return whether text is exactly one canonical directive.
-
-    This provides boolean directive classification for callers that only need a
-    yes-or-no answer. It does not parse operands, explain rejection reasons, or
-    perform validation beyond canonical grammar recognition.
-    """
-    return validate_directive(text) is not None
-
-
 def render_directive(kind: DirectiveKind, /, **operands: str) -> str:
-    """Render canonical directive text from a semantic kind and operands.
+    """Produce canonical directive text from a semantic kind and operands.
 
     This determines the exact canonical spelling for an existing grammar
     capability and rejects operand combinations that would not round-trip as the
@@ -466,7 +473,6 @@ __all__ = [
     "ValidatedDirective",
     "contains_multiple_canonical_directives",
     "decompose_directive",
-    "is_canonical_directive",
     "match_canonical_directive_start",
     "render_directive",
     "validate_directive",