refactor: hint is now presprective

Author: Verdenroz

.pre-commit-config.yaml

@@ -23,11 +23,14 @@ repos:
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
 
-  - repo: https://github.com/DetachHead/basedpyright
-    rev: v1.29.1
+  - repo: local
     hooks:
       - id: basedpyright
-        additional_dependencies: [tiktoken]
+        name: basedpyright (uv)
+        entry: uv run basedpyright
+        language: system
+        args: [src]
+        pass_filenames: false
 
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1

src/agon/core.py

@@ -256,16 +256,48 @@ def project_data(data: list[dict[str, Any]], keep_paths: list[str]) -> list[dict
         return AGONFormat.project_data(data, keep_paths)
 
     @staticmethod
-    def hint() -> str:
-        """Optional short hint for LLMs about AGON format.
+    def hint(result_or_format: AGONEncoding | ConcreteFormat) -> str:
+        """Get a prescriptive hint instructing LLMs how to generate AGON format.
 
-        Most LLMs can understand AGON without any hint since it's self-describing.
-        This hint is ~24 tokens vs ~100+ tokens for traditional schema prompts.
+        NOTE: LLMs have not been trained on AGON, so generation accuracy cannot
+        be guaranteed. Use hints when asking LLMs to return AGON-formatted data,
+        but validate the output. Prefer sending AGON to LLMs (reliable) over
+        asking LLMs to generate AGON (experimental).
+
+        Args:
+            result_or_format: AGONEncoding result or format name ("text", "columns",
+                "struct", "json"). Returns generation instructions for that format.
 
         Returns:
-            A short hint string.
+            A short prescriptive hint instructing how to generate the format.
+
+        Example:
+            >>> result = AGON.encode(data, format="auto")
+            >>> AGON.hint(result)  # Generation instruction for selected format
+            'Return in AGON text format: Start with @AGON text header, encode arrays as name[N]{fields} with tab-delimited rows'
+            >>> AGON.hint("columns")  # Generation instruction for columns format
+            'Return in AGON columns format: Start with @AGON columns header, transpose arrays to name[N] with ├/└ field: val1, val2, ...'
         """
-        return AGONText.hint()
+        # Extract format if AGONEncoding was passed
+        format_name = (
+            result_or_format.format
+            if isinstance(result_or_format, AGONEncoding)
+            else result_or_format
+        )
+
+        # Return hint for specific format
+        match format_name:
+            case "text":
+                return AGONText.hint()
+            case "columns":
+                return AGONColumns.hint()
+            case "struct":
+                return AGONStruct.hint()
+            case "json":
+                return "JSON: Standard compact JSON encoding"
+            case _:
+                msg = f"Unknown format: {format_name}"
+                raise AGONError(msg)
 
     @staticmethod
     def count_tokens(text: str, *, encoding: str = DEFAULT_ENCODING) -> int:

src/agon/formats/columns.py

@@ -53,8 +53,8 @@ class AGONColumns(AGONFormat):
 
     @staticmethod
     def hint() -> str:
-        """Return a short hint describing this format for LLMs."""
-        return "AGON columns: arrays as name[N] with ├/└ field: val1, val2, ..."
+        """Return a short hint instructing LLMs how to generate this format."""
+        return "Return in AGON columns format: Start with @AGON columns header, transpose arrays to name[N] with ├/└ field: val1, val2, ..."
 
     @staticmethod
     def encode(
@@ -69,7 +69,7 @@ def encode(
         Args:
             data: JSON-serializable data to encode.
             delimiter: Value delimiter within columns (default: ", ").
-            include_header: Whether to include @AGON columns v1 header.
+            include_header: Whether to include @AGON columns header.
             use_ascii: Use ASCII tree chars (|, `) instead of Unicode.
 
         Returns:
@@ -210,7 +210,7 @@ def _encode_primitive(val: Any, delimiter: str) -> str:
         return "null"
     if isinstance(val, bool):
         return "true" if val else "false"
-    if isinstance(val, (int, float)):
+    if isinstance(val, int | float):
         if isinstance(val, float):
             if val != val:  # NaN
                 return ""
@@ -267,7 +267,7 @@ def _is_columnar_array(arr: list[Any]) -> tuple[bool, list[str]]:
 
     for obj in arr:
         for v in obj.values():
-            if isinstance(v, (dict, list)):
+            if isinstance(v, dict | list):
                 return False, []
 
     key_order: list[str] = []
@@ -281,7 +281,7 @@ def _is_columnar_array(arr: list[Any]) -> tuple[bool, list[str]]:
 
 def _is_primitive_array(arr: list[Any]) -> bool:
     """Check if array contains only primitives."""
-    return all(not isinstance(x, (dict, list)) for x in arr)
+    return all(not isinstance(x, dict | list) for x in arr)
 
 
 def _encode_value(
@@ -295,7 +295,7 @@ def _encode_value(
     """Encode a value, appending lines."""
     indent = INDENT * depth
 
-    if val is None or isinstance(val, (bool, int, float, str)):
+    if val is None or isinstance(val, bool | int | float | str):
         if name:
             lines.append(f"{indent}{name}: {_encode_primitive(val, delimiter)}")
         else:
@@ -389,7 +389,7 @@ def _encode_list_item_object(
         if isinstance(v, dict):
             lines.append(f"{prefix}{k}:")
             for nk, nv in v.items():
-                if isinstance(nv, (dict, list)):
+                if isinstance(nv, dict | list):
                     _encode_value(nv, lines, depth + 2, delimiter, nk, use_ascii)
                 else:
                     lines.append(f"{indent}    {nk}: {_encode_primitive(nv, delimiter)}")
@@ -417,7 +417,7 @@ def _encode_object(
         indent = INDENT * depth
 
     for k, v in obj.items():
-        if isinstance(v, (dict, list)):
+        if isinstance(v, dict | list):
             _encode_value(v, lines, depth, delimiter, k, use_ascii)
         else:
             lines.append(f"{indent}{k}: {_encode_primitive(v, delimiter)}")

src/agon/formats/struct.py

@@ -64,8 +64,8 @@ class AGONStruct(AGONFormat):
 
     @staticmethod
     def hint() -> str:
-        """Return a short hint describing this format for LLMs."""
-        return "AGON struct: @Struct: fields defines templates, Struct(v1, v2) instantiates"
+        """Return a short hint instructing LLMs how to generate this format."""
+        return "Return in AGON struct format: Start with @AGON struct header, define templates as @Struct: fields, instantiate as Struct(v1, v2)"
 
     @staticmethod
     def encode(
@@ -212,7 +212,7 @@ def _detect_shapes(
     if isinstance(data, dict):
         # Only count shapes with primitive values
         primitive_keys: tuple[str, ...] = tuple(
-            sorted(k for k, v in data.items() if not isinstance(v, (dict, list)))
+            sorted(k for k, v in data.items() if not isinstance(v, dict | list))
         )
         if len(primitive_keys) >= 2:
             shapes[primitive_keys] += 1
@@ -322,7 +322,7 @@ def _can_use_struct(obj: dict[str, Any], fields: list[str], optional: set[str])
     """Check if an object can be encoded as a struct instance."""
     # Object must have only primitive values
     for v in obj.values():
-        if isinstance(v, (dict, list)):
+        if isinstance(v, dict | list):
             return False
 
     # All required fields must be present
@@ -385,7 +385,7 @@ def _encode_primitive(val: Any, *, for_struct_instance: bool = False) -> str:
         return "" if for_struct_instance else "null"
     if isinstance(val, bool):
         return "true" if val else "false"
-    if isinstance(val, (int, float)):
+    if isinstance(val, int | float):
         if isinstance(val, float):
             if val != val:  # NaN
                 return "" if for_struct_instance else "null"
@@ -466,7 +466,7 @@ def _encode_value(
     """Encode a value, appending lines."""
     indent = INDENT * depth
 
-    if val is None or isinstance(val, (bool, int, float, str)):
+    if val is None or isinstance(val, bool | int | float | str):
         lines.append(f"{indent}{_encode_primitive(val)}")
         return
 

src/agon/formats/text.py

@@ -4,12 +4,12 @@
 It uses indentation for hierarchy and tabular format for arrays of objects.
 
 Format structure:
-    @AGON text v1
+    @AGON text
     @D=<delimiter>  # optional, default: \t
     <data>
 
 Example:
-    @AGON text v1
+    @AGON text
 
     products[3]{sku	name	price}
     A123	Widget	9.99
@@ -46,8 +46,8 @@ class AGONText(AGONFormat):
 
     @staticmethod
     def hint() -> str:
-        """Return a short hint describing this format for LLMs."""
-        return "AGON text: key:value pairs, arrays as name[N]{fields} with rows"
+        """Return a short hint instructing LLMs how to generate this format."""
+        return "Return in AGON text format: Start with @AGON text header, encode arrays as name[N]{fields} with tab-delimited rows"
 
     @staticmethod
     def encode(
@@ -61,7 +61,7 @@ def encode(
         Args:
             data: JSON-serializable data to encode.
             delimiter: Field delimiter for tabular data (default: tab).
-            include_header: Whether to include @AGON text v1 header.
+            include_header: Whether to include @AGON text header.
 
         Returns:
             AGONText encoded string.
@@ -207,7 +207,7 @@ def _encode_primitive(val: Any, delimiter: str) -> str:
         return "null"
     if isinstance(val, bool):
         return "true" if val else "false"
-    if isinstance(val, (int, float)):
+    if isinstance(val, int | float):
         # Handle special float values
         if isinstance(val, float):
             if val != val:  # NaN
@@ -272,7 +272,7 @@ def _is_uniform_array(arr: list[Any]) -> tuple[bool, list[str]]:
     # Check all objects have only primitive values
     for obj in arr:
         for v in obj.values():
-            if isinstance(v, (dict, list)):
+            if isinstance(v, dict | list):
                 return False, []
 
     # Return keys in consistent order (first seen order from union)
@@ -287,7 +287,7 @@ def _is_uniform_array(arr: list[Any]) -> tuple[bool, list[str]]:
 
 def _is_primitive_array(arr: list[Any]) -> bool:
     """Check if array contains only primitives."""
-    return all(not isinstance(x, (dict, list)) for x in arr)
+    return all(not isinstance(x, dict | list) for x in arr)
 
 
 def _encode_value(
@@ -300,7 +300,7 @@ def _encode_value(
     """Encode a value, appending lines."""
     indent = INDENT * depth
 
-    if val is None or isinstance(val, (bool, int, float, str)):
+    if val is None or isinstance(val, bool | int | float | str):
         # Primitive value
         if name:
             lines.append(f"{indent}{name}: {_encode_primitive(val, delimiter)}")
@@ -401,7 +401,7 @@ def _encode_list_item_object(
             # Nested object
             lines.append(f"{prefix}{k}:")
             for nk, nv in v.items():
-                if isinstance(nv, (dict, list)):
+                if isinstance(nv, dict | list):
                     _encode_value(nv, lines, depth + 2, delimiter, nk)
                 else:
                     lines.append(f"{indent}    {nk}: {_encode_primitive(nv, delimiter)}")