gcf-python 2.2.1__tar.gz → 2.2.2__tar.gz

{gcf_python-2.2.1 → gcf_python-2.2.2}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v2.2.2 (2026-07-10)
+
+### Fixes
+
+- **Losslessness (nested null):** a nested object that is null at an intermediate level (e.g. `{"meta": {"owner": None}}`) is no longer flattened. Previously its leaves encoded as absent (`~`) and unflattened to a missing key, silently dropping the null. Such fields now fall back to the attachment mechanism; a top-level `None` still flattens losslessly (emits `-`, reconstructs via the all-null rule). Enforced by the shared conformance fixtures `flatten/017`–`019`. Prototype pollution does not affect Python (dicts have no mutable prototype).
+
+### Tests
+
+- `test_flatten_roundtrip`: aligned arrays whose shared fields are fixed-shape nested objects with a field or an intermediate nested level sometimes null/absent — the shape the prior scalar-only generator never produced, leaving the flatten/unflatten path unexercised. Verified to fail on the pre-fix encoder and pass on the fix.
+
 ## v2.2.1 (2026-06-23)
 
 ### Flatten Opt-Out

{gcf_python-2.2.1 → gcf_python-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 2.2.1
+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/
@@ -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. 29% fewer tokens than TOON, 56% fewer than JSON across 16 datasets. 91.2% on structurally complex code graphs (vs TOON 68.2%, JSON 53.4%). 2,400+ 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)
 
@@ -210,7 +210,7 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 
 | | GCF | TOON | JSON |
 |---|---|---|---|
-| **Comprehension** (23 runs, 10 models) | **91.2%** | 68.2% | 53.4% |
+| **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 |
@@ -236,7 +236,11 @@ GCF wins 15/16 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.2 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 173 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.2.0+ (Go v1.3.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.1 → gcf_python-2.2.2}/README.md

@@ -7,7 +7,7 @@
 
 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. 29% fewer tokens than TOON, 56% fewer than JSON across 16 datasets. 91.2% on structurally complex code graphs (vs TOON 68.2%, JSON 53.4%). 2,400+ 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)
 
@@ -185,7 +185,7 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 
 | | GCF | TOON | JSON |
 |---|---|---|---|
-| **Comprehension** (23 runs, 10 models) | **91.2%** | 68.2% | 53.4% |
+| **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 |
@@ -211,7 +211,11 @@ GCF wins 15/16 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.2 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 173 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.2.0+ (Go v1.3.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.1 → gcf_python-2.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-version = "2.2.1"
+version = "2.2.2"
 description = "The AI-native wire format for structured data. 50-92% fewer tokens than JSON. 100% comprehension on every frontier model. Zero dependencies."
 readme = "README.md"
 license = {text = "MIT"}

{gcf_python-2.2.1 → gcf_python-2.2.2}/src/gcf/__init__.py

@@ -66,4 +66,4 @@ __all__ = [
     "encode_with_session",
 ]
 
-__version__ = "1.0.0"
+__version__ = "2.2.2"

{gcf_python-2.2.1 → gcf_python-2.2.2}/src/gcf/generic.py

@@ -14,8 +14,8 @@ class GenericOptions:
     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. Set when targeting open-weight models that show lower
-    comprehension on flattened encoding."""
+    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:
@@ -171,7 +171,15 @@ def _analyze_flattenable(
     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):

{gcf_python-2.2.1 → gcf_python-2.2.2}/tests/test_roundtrip_v2.py

@@ -214,6 +214,80 @@ def _structural_equal(a, b):
     return a == b
 
 
+def _gen_flat_shape(r, depth, max_depth):
+    """A fixed nested schema: the string "scalar" or a dict of named sub-shapes."""
+    if depth >= max_depth or r.random() < 0.45:
+        return "scalar"
+    shape = {}
+    for _ in range(1 + r.randint(0, 2)):
+        shape[_gen_bare_key(r)] = _gen_flat_shape(r, depth + 1, max_depth)
+    return shape if shape else "scalar"
+
+
+def _materialize_flat_shape(r, shape):
+    if shape == "scalar":
+        return _gen_scalar(r)
+    obj = {}
+    for k, s in shape.items():
+        # A nested sub-object is sometimes None (intermediate null — the case the
+        # pre-fix encoder dropped) instead of a full object.
+        obj[k] = None if s != "scalar" and r.random() < 0.3 else _materialize_flat_shape(r, s)
+    return obj
+
+
+def _gen_flattenable_array(r):
+    schema = {"id": "scalar"}
+    order = ["id"]
+    has_nested = False
+    for _ in range(1 + r.randint(0, 2)):
+        k = _gen_bare_key(r)
+        if k in schema:
+            continue
+        s = _gen_flat_shape(r, 1, 3)
+        schema[k] = s
+        order.append(k)
+        if s != "scalar":
+            has_nested = True
+    if not has_nested:
+        k = _gen_bare_key(r)
+        schema[k] = {_gen_bare_key(r): {_gen_bare_key(r): "scalar"}}
+        order.append(k)
+    arr = []
+    for _ in range(2 + r.randint(0, 5)):
+        row = {}
+        for f in order:
+            x = r.random()
+            if x < 0.12:
+                continue  # field absent this row
+            elif x < 0.24:
+                row[f] = None  # field present-null (top-level null)
+            else:
+                row[f] = _materialize_flat_shape(r, schema[f])
+        arr.append(row)
+    return arr
+
+
+def test_flatten_roundtrip():
+    """Aligned arrays whose shared fields are fixed-shape nested objects with a
+    field or an intermediate nested level sometimes null/absent — the v3.2 flatten
+    path the scalar-only generator never produces, so flatten/unflatten and its
+    null-at-depth losslessness edge would otherwise be unexercised."""
+    r = _rng(7)
+    for i in range(ITERATIONS):
+        val = _gen_flattenable_array(r)
+        for no_flatten in (False, True):
+            gcf = encode_generic(val, GenericOptions(no_flatten=no_flatten))
+            decoded = decode_generic(gcf)
+            a = _json_norm(val)
+            b = _json_norm(decoded)
+            assert _structural_equal(a, b), (
+                f"iteration {i} no_flatten={no_flatten}: round-trip mismatch\n"
+                f"  input:   {json.dumps(val)}\n"
+                f"  decoded: {json.dumps(decoded)}\n"
+                f"  gcf:     {gcf!r}"
+            )
+
+
 def test_random_roundtrip():
     r = _rng(42)
     for i in range(ITERATIONS):

gcf_python-2.2.2/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.9"
+
+[[package]]
+name = "gcf-python"
+version = "2.0.0"
+source = { editable = "." }