gcf-python 2.2.0__py3-none-any.whl → 2.2.2__py3-none-any.whl

gcf/__init__.py

@@ -38,7 +38,7 @@ from .constants import KIND_ABBREV, KIND_EXPAND
 from .decode import DecodeError, decode
 from .delta import encode_delta
 from .encode import encode
-from .generic import encode_generic
+from .generic import encode_generic, GenericOptions
 from .session import Session, encode_with_session
 from .decode_generic import decode_generic
 from .stream import StreamEncoder
@@ -62,7 +62,8 @@ __all__ = [
     "encode",
     "encode_delta",
     "encode_generic",
+    "GenericOptions",
     "encode_with_session",
 ]
 
-__version__ = "1.0.0"
+__version__ = "2.2.2"

gcf/decode_generic.py

@@ -360,6 +360,14 @@ def _parse_attachment(
         arr, consumed = _parse_array_from_header(lines, line_idx, depth, after_name)
         return name, arr, consumed, None
 
+    # Scalar: =value (field names containing ">" excluded from tabular columns).
+    if after_name.startswith("="):
+        val_str = after_name[1:]
+        parsed = parse_scalar(val_str, tabular_context=True)
+        if parsed is MISSING:
+            return name, None, 1, None
+        return name, parsed, 1, None
+
     raise ValueError(f"invalid attachment form: {after_name}")
 
 
@@ -423,7 +431,11 @@ def _parse_tabular_body(
     path_column_map: dict[str, list[str]] = {}
     for f in fields:
         if ">" in f:
-            path_column_map[f] = f.split(">")
+            parts = f.split(">")
+            # Only treat as a path column if all segments are non-empty.
+            # A literal key like ">" would split into ["", ""].
+            if all(p for p in parts):
+                path_column_map[f] = parts
 
     # Track inline schemas and shared array schemas.
     inline_schemas: dict[str, list[str]] = {}
@@ -506,10 +518,10 @@ def _parse_tabular_body(
         all_att_fields = traditional_att_fields + inline_att_fields
         attachment_values: dict[str, Any] = {}
 
-        if row_has_id and all_att_fields:
+        if row_has_id:
             inline_idx = 0
 
-            while i < len(lines) and len(attachment_values) < len(all_att_fields):
+            while i < len(lines):
                 a_line = lines[i]
                 a_content: str | None = None
                 if depth == 0 or a_line.startswith(ind):
@@ -601,13 +613,6 @@ def _parse_tabular_body(
                     if extra_name in attachment_values:
                         raise ValueError(f"duplicate_attachment: {extra_name}")
 
-        if not row_has_id or not all_att_fields:
-            att_indent = ind + "  "
-            if i < len(lines) and lines[i].startswith(att_indent):
-                peek = lines[i][len(att_indent):]
-                if peek.startswith("."):
-                    raise ValueError(f"orphan_attachment: {peek}")
-
         row: dict[str, Any] = {}
         for f in fields:
             if f in missing_fields:
@@ -616,6 +621,10 @@ def _parse_tabular_body(
                 row[f] = cell_values[f]
             elif f in attachment_values:
                 row[f] = attachment_values[f]
+        # Also add any orphan attachment values (fields excluded from column list, e.g. ">" fields).
+        for k, v in attachment_values.items():
+            if k not in row:
+                row[k] = v
         # Unflatten path columns into nested objects.
         if path_column_map:
             nested = _unflatten_paths(path_column_map, flat_values, flat_absent)

gcf/generic.py

@@ -2,42 +2,55 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Any
 
 from .scalar import format_scalar, format_key
 
 
-def encode_generic(data: Any) -> str:
+@dataclass
+class GenericOptions:
+    """Options for controlling generic encoding behavior."""
+    no_flatten: bool = False
+    """When True, disables promotion of fixed-shape nested objects to path
+    columns (e.g. "customer>name"). Nested objects use attachment syntax
+    instead. Open-weight models currently comprehend the expanded form
+    better; this gap is expected to close."""
+
+
+def encode_generic(data: Any, opts: GenericOptions | None = None) -> str:
+    if opts is None:
+        opts = GenericOptions()
     out: list[str] = ["GCF profile=generic"]
-    _encode_root_value(data, out)
+    _encode_root_value(data, out, opts)
     return "\n".join(out) + "\n"
 
 
-def _encode_root_value(v: Any, out: list[str]) -> None:
+def _encode_root_value(v: Any, out: list[str], opts: GenericOptions) -> None:
     if v is None:
         out.append("=-")
     elif isinstance(v, dict):
-        _encode_object(v, out, 0)
+        _encode_object(v, out, 0, opts)
     elif isinstance(v, list):
-        _encode_root_array(v, out)
+        _encode_root_array(v, out, opts)
     else:
         out.append(f"={format_scalar(v)}")
 
 
-def _encode_object(d: dict, out: list[str], depth: int) -> None:
+def _encode_object(d: dict, out: list[str], depth: int, opts: GenericOptions) -> None:
     prefix = _indent(depth)
     for key, value in d.items():
         fk = format_key(key)
         if isinstance(value, dict):
             out.append(f"{prefix}## {fk}")
-            _encode_object(value, out, depth + 1)
+            _encode_object(value, out, depth + 1, opts)
         elif isinstance(value, list):
-            _encode_named_array(fk, value, out, depth)
+            _encode_named_array(fk, value, out, depth, opts)
         else:
             out.append(f"{prefix}{fk}={format_scalar(value)}")
 
 
-def _encode_root_array(arr: list, out: list[str]) -> None:
+def _encode_root_array(arr: list, out: list[str], opts: GenericOptions) -> None:
     if not arr:
         out.append("## [0]")
         return
@@ -47,12 +60,12 @@ def _encode_root_array(arr: list, out: list[str]) -> None:
         return
     fields = _tabular_fields(arr)
     if fields is not None:
-        _encode_tabular("## ", arr, fields, out, 0)
+        _encode_tabular("## ", arr, fields, out, 0, opts)
         return
-    _encode_expanded("## ", arr, out, 0)
+    _encode_expanded("## ", arr, out, 0, opts)
 
 
-def _encode_named_array(name: str, arr: list, out: list[str], depth: int) -> None:
+def _encode_named_array(name: str, arr: list, out: list[str], depth: int, opts: GenericOptions) -> None:
     prefix = _indent(depth)
     if not arr:
         out.append(f"{prefix}## {name} [0]")
@@ -63,9 +76,9 @@ def _encode_named_array(name: str, arr: list, out: list[str], depth: int) -> Non
         return
     fields = _tabular_fields(arr)
     if fields is not None:
-        _encode_tabular(f"{prefix}## {name} ", arr, fields, out, depth)
+        _encode_tabular(f"{prefix}## {name} ", arr, fields, out, depth, opts)
         return
-    _encode_expanded(f"{prefix}## {name} ", arr, out, depth)
+    _encode_expanded(f"{prefix}## {name} ", arr, out, depth, opts)
 
 
 def _tabular_fields(arr: list) -> list[str] | None:
@@ -152,10 +165,21 @@ def _analyze_flattenable(
     arr: list[dict], field_name: str, parent_path: str
 ) -> list[dict] | None:
     """Analyze whether a field can be flattened. Returns list of leaf descriptors or None."""
+    # Field names containing ">" cannot be flattened (would create ambiguous paths).
+    if ">" in field_name:
+        return None
     canonical_shape: dict[str, str] | None = None  # key -> "scalar" | "nested"
 
     for item in arr:
-        if field_name not in item or item[field_name] is None:
+        if field_name not in item:
+            continue
+        # A nested (non-top-level) null cannot be flattened losslessly: its leaves
+        # would encode as absent ("~") and unflatten back to a missing key, not None.
+        # Bail to the attachment path. A top-level None is fine (emits "-" and
+        # reconstructs via the all-null rule), so just skip the row from shape analysis.
+        if item[field_name] is None:
+            if parent_path != "":
+                return None
             continue
         v = item[field_name]
         if not isinstance(v, dict):
@@ -249,26 +273,39 @@ def _resolve_key_chain(item: Any, keys: list[str]) -> tuple[Any, bool]:
 
 
 def _encode_tabular(
-    header_prefix: str, arr: list[dict], fields: list[str], out: list[str], depth: int
+    header_prefix: str, arr: list[dict], fields: list[str], out: list[str], depth: int, opts: GenericOptions
 ) -> None:
     prefix = _indent(depth)
 
     # Phase 0: Analyze fields for flattening.
     flatten_map: dict[str, list[dict]] = {}
-    for f in fields:
-        leaves = _analyze_flattenable(arr, f, "")
-        if leaves and len(leaves) > 0:
-            flatten_map[f] = leaves
+    if not opts.no_flatten:
+        for f in fields:
+            leaves = _analyze_flattenable(arr, f, "")
+            if leaves and len(leaves) > 0:
+                flatten_map[f] = leaves
+
+    # Fields whose names contain ">" must not appear as tabular columns
+    # because the decoder would interpret them as flattened path columns.
+    # Track them for per-row attachment emission (spec rule 7.4.6.1.4).
+    gt_fields = {f for f in fields if f not in flatten_map and ">" in f}
 
     # Build expanded column list.
     columns: list[dict] = []
     for f in fields:
+        if f in gt_fields:
+            continue
         if f in flatten_map:
             for leaf in flatten_map[f]:
                 columns.append({"header": format_key(leaf["path"]), "type": "flat", "field": f, "keys": leaf["keys"]})
         else:
             columns.append({"header": format_key(f), "type": "original", "field": f, "keys": []})
 
+    # If all fields were excluded (all contain ">"), fall back to expanded.
+    if not columns:
+        _encode_expanded(header_prefix, arr, out, depth, opts)
+        return
+
     # Pre-compute inline schemas and shared array schemas (skip flattened fields).
     inline_schemas: dict[str, list[str]] = {}
     shared_arr_schemas: dict[str, list[str]] = {}
@@ -333,6 +370,15 @@ def _encode_tabular(
             else:
                 cells.append(format_scalar(v, "|"))
 
+        # Emit fields with ">" in their names as per-row attachments.
+        for f in fields:
+            if f not in gt_fields:
+                continue
+            if f not in item:
+                continue
+            row_has_attachment = True
+            attachments.append((f, item[f], False, None))
+
         row = "|".join(cells)
         if row_has_attachment:
             out.append(f"{prefix}@{i} {row}")
@@ -351,17 +397,25 @@ def _encode_tabular(
             elif isinstance(att_val, list):
                 sas = shared_arr_schemas.get(att_name)
                 if sas and i > 0:
-                    _encode_attachment_array_shared(prefix, fk, att_val, out, depth + 2, sas)
+                    _encode_attachment_array_shared(prefix, fk, att_val, out, depth + 2, sas, opts)
                 else:
-                    _encode_attachment_array(prefix, fk, att_val, out, depth + 2)
+                    _encode_attachment_array(prefix, fk, att_val, out, depth + 2, opts)
             elif isinstance(att_val, dict):
                 out.append(f"{prefix}.{fk} {{}}")
-                _encode_object(att_val, out, depth + 2)
+                _encode_object(att_val, out, depth + 2, opts)
+            else:
+                # Scalar attachment (e.g. field names containing ">").
+                if att_val is None:
+                    out.append(f"{prefix}.{fk} =-")
+                else:
+                    out.append(f"{prefix}.{fk} ={format_scalar(att_val)}")
 
 
 def _encode_attachment_array(
-    att_prefix: str, fk: str, arr: list, out: list[str], depth: int
+    att_prefix: str, fk: str, arr: list, out: list[str], depth: int, opts: GenericOptions | None = None
 ) -> None:
+    if opts is None:
+        opts = GenericOptions()
     if not arr:
         out.append(f"{att_prefix}.{fk} [0]")
     elif _all_primitives(arr):
@@ -370,13 +424,13 @@ def _encode_attachment_array(
     else:
         fields = _tabular_fields(arr)
         if fields is not None:
-            _encode_tabular(f"{att_prefix}.{fk} ", arr, fields, out, depth)
+            _encode_tabular(f"{att_prefix}.{fk} ", arr, fields, out, depth, opts)
         else:
-            _encode_expanded(f"{att_prefix}.{fk} ", arr, out, depth)
+            _encode_expanded(f"{att_prefix}.{fk} ", arr, out, depth, opts)
 
 
 def _encode_attachment_array_shared(
-    att_prefix: str, fk: str, arr: list, out: list[str], depth: int, shared_fields: list[str]
+    att_prefix: str, fk: str, arr: list, out: list[str], depth: int, shared_fields: list[str], opts: GenericOptions | None = None
 ) -> None:
     if not arr:
         out.append(f"{att_prefix}.{fk} [0]")
@@ -403,25 +457,29 @@ def _encode_attachment_array_shared(
             out.append(f"{prefix}{'|'.join(cells)}")
     else:
         # Fields don't match: fall back to full encoding.
-        _encode_attachment_array(att_prefix, fk, arr, out, depth)
+        _encode_attachment_array(att_prefix, fk, arr, out, depth, opts)
 
 
-def _encode_expanded(header_prefix: str, arr: list, out: list[str], depth: int) -> None:
+def _encode_expanded(header_prefix: str, arr: list, out: list[str], depth: int, opts: GenericOptions | None = None) -> None:
+    if opts is None:
+        opts = GenericOptions()
     prefix = _indent(depth)
     out.append(f"{header_prefix}[{len(arr)}]")
     for i, item in enumerate(arr):
         if isinstance(item, dict):
             out.append(f"{prefix}@{i} {{}}")
-            _encode_object(item, out, depth + 1)
+            _encode_object(item, out, depth + 1, opts)
         elif isinstance(item, list):
-            _encode_expanded_array_item(prefix, i, item, out, depth)
+            _encode_expanded_array_item(prefix, i, item, out, depth, opts)
         else:
             out.append(f"{prefix}@{i} ={format_scalar(item)}")
 
 
 def _encode_expanded_array_item(
-    prefix: str, idx: int, arr: list, out: list[str], depth: int
+    prefix: str, idx: int, arr: list, out: list[str], depth: int, opts: GenericOptions | None = None
 ) -> None:
+    if opts is None:
+        opts = GenericOptions()
     if not arr:
         out.append(f"{prefix}@{idx} [0]")
     elif _all_primitives(arr):
@@ -430,9 +488,9 @@ def _encode_expanded_array_item(
     else:
         fields = _tabular_fields(arr)
         if fields is not None:
-            _encode_tabular(f"{prefix}@{idx} ", arr, fields, out, depth + 1)
+            _encode_tabular(f"{prefix}@{idx} ", arr, fields, out, depth + 1, opts)
         else:
-            _encode_expanded(f"{prefix}@{idx} ", arr, out, depth + 1)
+            _encode_expanded(f"{prefix}@{idx} ", arr, out, depth + 1, opts)
 
 
 def _all_primitives(arr: list) -> bool:

{gcf_python-2.2.0.dist-info → gcf_python-2.2.2.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 2.2.0
-Summary: Drop-in JSON replacement for AI pipelines. 79% fewer tokens. 90.7% comprehension across 10 models. Zero dependencies.
+Version: 2.2.2
+Summary: The AI-native wire format for structured data. 50-92% fewer tokens than JSON. 100% comprehension on every frontier model. Zero dependencies.
 Project-URL: Homepage, https://github.com/blackwell-systems/gcf-python
 Project-URL: Documentation, https://blackwell-systems.github.io/gcf/
 Project-URL: Specification, https://github.com/blackwell-systems/gcf
@@ -32,7 +32,7 @@ Description-Content-Type: text/markdown
 
 Python implementation of [GCF](https://gcformat.com/) — the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
 
-**100% comprehension on every frontier model tested. 25.5% fewer tokens than TOON, 53% fewer than JSON across 15 datasets. 90.7% on structurally complex code graphs (vs TOON 68.5%, JSON 53.6%). 1,700+ LLM evaluations. Zero training.**
+**100% comprehension on every frontier model tested. 29% fewer tokens than TOON, 56% fewer than JSON across 16 datasets. 91.2% on structurally complex code graphs (vs TOON 68.8%, JSON 54.1%). 2,400+ LLM evaluations. Zero training.**
 
 Docs: [gcformat.com](https://gcformat.com/) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
 
@@ -206,16 +206,16 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 
 ## Benchmarks
 
-1,700+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.
+2,400+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.
 
 | | GCF | TOON | JSON |
 |---|---|---|---|
-| **Comprehension** (23 runs, 10 models) | **90.7%** | 68.5% | 53.6% |
+| **Comprehension** (23 runs, 10 models) | **91.2%** | 68.8% | 54.1% |
 | **Generation** (28 runs, 9 models) | **5/5** | 1.0/5 | 5.0/5 |
 | **Input tokens** (500 symbols) | **11,090** | 16,378 | 53,341 |
 | **Output tokens** (100 symbols) | **5,976** | 8,937 | 16,121 |
 
-GCF wins 13/15 datasets on the expanded [token efficiency benchmark](https://github.com/blackwell-systems/toon/tree/gcf-comparison). Full results: [gcformat.com/guide/benchmarks](https://gcformat.com/guide/benchmarks.html)
+GCF wins 15/16 datasets on the expanded [token efficiency benchmark](https://github.com/blackwell-systems/toon/tree/gcf-comparison). Full results: [gcformat.com/guide/benchmarks](https://gcformat.com/guide/benchmarks.html)
 
 ## Implementations
 
@@ -236,7 +236,11 @@ GCF wins 13/15 datasets on the expanded [token efficiency benchmark](https://git
 
 **Zero runtime dependencies. Permanently.** All six implementations depend only on their language's standard library. No transitive dependencies. No supply chain risk. This is a permanent commitment: GCF will never take on external runtime dependencies. MIT licensed. All implementations support both generic profile (`encodeGeneric`) and graph profile (`encode`). CLI included in all 6 languages.
 
-**Specification:** [SPEC v3.1 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 157 conformance fixtures, 33,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.1.0+ (Go v1.2.0). Cross-language 6x6 matrix verified.
+**Specification:** [SPEC v3.2 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 174 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.2.1+ (Go v1.3.1). Cross-language 6x6 matrix verified.
+
+## Adopted by
+
+[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) (46K stars, Google Chrome DevTools team) · [Speakeasy](https://speakeasy.com) (API tooling, customers include Google, Verizon, Mistral AI, DocuSign, Vercel) · [OmniRoute](https://omniroute.online) (6.1K stars) · [NetClaw](https://github.com/automateyournetwork/netclaw) (556 stars) · [ctx](https://github.com/stevesolun/ctx) (510 stars) · [NeuroNest](https://neuronest.cc) · [Open Data Products SDK](https://opendataproducts.org/sdk/) (Linux Foundation) · [Raycast](https://raycast.com/blackwell-systems/json-to-gcf-converter) · [and more](https://gcformat.com/ecosystem/adopters.html)
 
 ## License
 

{gcf_python-2.2.0.dist-info → gcf_python-2.2.2.dist-info}/RECORD

@@ -1,19 +1,19 @@
-gcf/__init__.py,sha256=UBJ5UmpO1oG8bCZnO1jlPngUL65Gg1yL9sfArC9ed2g,1738
+gcf/__init__.py,sha256=ZPd4iye7cr6HgIsFoe6Lq7Qd3mmIAyVhfjjn5AwID2E,1776
 gcf/__main__.py,sha256=EpvBz1yc8H0D5OJ1zy2tYke-kRzvudKa4DEbfeW14ao,71
 gcf/cli.py,sha256=UEe1CAZn-rKGNIo_ap8-oez3ucl6DSRbsdv6RDnzygY,5256
 gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
 gcf/decode.py,sha256=nD8bXYhoeHQQ3LCeAJQOAgFuob-V_6us4mcBYtL_bBc,5978
-gcf/decode_generic.py,sha256=QdwXIPZhTTJsfaYInYKW0TKr8Ln5cufmRE2kl40_kpY,26034
+gcf/decode_generic.py,sha256=ZlFZqwenOzCnvbJijKscb6aQHoHQ81qoHBkaalVbqqo,26381
 gcf/delta.py,sha256=f90UC6zejXH-ujyU_OViWDCqnxLXk3i6Qion-RJGHY4,1670
 gcf/encode.py,sha256=CcqMSNmojrQAAw2X3MNfw8YR6l4rNw9hWDqwmf846oA,2929
-gcf/generic.py,sha256=7cSwYT_U3ySTZy8yLY_GtQrzzGIRkhHOE1SEIGmhdrg,15458
+gcf/generic.py,sha256=t0Px1fAoWsmFFeICbL65LL8UTGFfnbh4PCanvMMKqYs,18198
 gcf/scalar.py,sha256=MZay-KIROvaFHet-g2-pBghahT1bf_5bxZjG4yTZkSo,9329
 gcf/session.py,sha256=6-wytNGaBkgqH7uTar7ojUFYNwIMeEVAZhuV-s-upZM,4704
 gcf/stream.py,sha256=1Kt_a2daKpYHlWP1lnDJ4g549pUt9rc-U0xbARbXRKQ,5174
 gcf/stream_generic.py,sha256=RnqqiPSu5joJa-7e58QbbzSGfvxBICA587A3aArjZvE,3250
 gcf/types.py,sha256=AWm-LQoSqLHAYtEjcAxWQZqJ4JXqNreLUKO2mJFgNMA,1465
-gcf_python-2.2.0.dist-info/METADATA,sha256=Kc-fEX3jOtbvgBPwEiQL0gRf4hibJYlGJu4ea05kGfw,9781
-gcf_python-2.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-gcf_python-2.2.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
-gcf_python-2.2.0.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
-gcf_python-2.2.0.dist-info/RECORD,,
+gcf_python-2.2.2.dist-info/METADATA,sha256=J-3Wr4vqhMqAucwtl4rhHBWBYUYCr3itkFla6FhLuqU,10489
+gcf_python-2.2.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+gcf_python-2.2.2.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-2.2.2.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
+gcf_python-2.2.2.dist-info/RECORD,,

{gcf_python-2.2.0.dist-info → gcf_python-2.2.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any