gcf-python 0.5.0__tar.gz → 1.0.0__tar.gz

gcf_python-1.0.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [blackwell-systems]

gcf_python-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: blackwell-systems/gcf
+          path: gcf
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]" || pip install -e . && pip install pytest
+      - name: Unit tests
+        run: pytest tests/ -v --ignore=tests/test_conformance_v2.py --ignore=tests/test_roundtrip_v2.py
+      - name: Conformance tests (133 fixtures)
+        run: pytest tests/test_conformance_v2.py -v
+      - name: Property-based round-trip (100K random + 100K adversarial)
+        run: pytest tests/test_roundtrip_v2.py -v

{gcf_python-0.5.0 → gcf_python-1.0.0}/.github/workflows/publish.yml

@@ -8,7 +8,7 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
       id-token: write
     steps:
       - uses: actions/checkout@v4
@@ -22,3 +22,7 @@ jobs:
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

{gcf_python-0.5.0 → gcf_python-1.0.0}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## v1.0.0 (2026-06-10)
+
+SPEC v2.0 implementation. 126/133 conformance fixtures passing (7 skipped: session, delta, binary UTF-8, negative zero, graph encode). 40M property-based round-trips with zero failures.
+
+### Breaking changes from v0.5.0
+
+- `encode_generic` emits `GCF profile=generic` header
+- `decode_generic` requires `GCF profile=` header
+- Strings colliding with typed literals are quoted
+- Full JSON string escaping and number grammar
+- `-` for null, `~` for absent, `^` for nested attachments
+- `##! summary` trailer replaces `## _summary`
+- Graph encoder emits `profile=graph`
+
+### New
+
+- `scalar.py`: common scalar grammar (quoting, escaping, parsing, number formatting)
+- Conformance test runner (133 fixtures)
+- Property-based round-trip tests (40M verified, configurable via `GCF_ITERATIONS`)
+
 ## v0.5.0 (2026-06-06)
 
 - `GenericStreamEncoder`: zero-buffering tabular streaming encode (begin_array/write_row/end_array/write_kv/write_section/write_inline_array)

{gcf_python-0.5.0 → gcf_python-1.0.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Blackwell Systems
+Copyright (c) 2026 Dayna Blackwell
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{gcf_python-0.5.0 → gcf_python-1.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 0.5.0
-Summary: Python implementation of GCF (Graph Compact Format): token-optimized wire format for LLM tool responses
+Version: 1.0.0
+Summary: Drop-in JSON replacement for AI pipelines. 79% fewer tokens. 90.5% comprehension across 10 models. 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.
 
-**79% fewer input tokens than JSON. 75% fewer output tokens. 52% smaller than TOON. 100% LLM comprehension at 500 symbols, where JSON scores 76.9% and TOON scores 92.3%.**
+**79% fewer input tokens than JSON. 63% fewer output tokens. 90.5% average comprehension accuracy across 10 models and 3 providers (four models hit 100%). 1,300+ 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)
 
@@ -204,33 +204,18 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 | `Session` | Thread-safe tracker for multi-call deduplication |
 | `KIND_ABBREV` / `KIND_EXPAND` | Bidirectional kind abbreviation dicts |
 
-## Comprehension Eval
+## Benchmarks
 
-Rigorous 3-way benchmark (GCF vs TOON vs JSON) at 500 symbols, 200 edges. 13 structured extraction questions sent to an LLM with zero format instructions:
+1,300+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.
 
-| Format | Accuracy | Tokens | vs JSON |
-|--------|----------|--------|---------|
-| **GCF** | **100%** (13/13) | **11,090** | **79% fewer** |
-| TOON | 92.3% (12/13) | 16,378 | 69% fewer |
-| JSON | 76.9% (10/13) | 53,341 | baseline |
+| | GCF | TOON | JSON |
+|---|---|---|---|
+| **Comprehension** (23 runs, 10 models) | **90.5%** | 68.5% | 53.6% |
+| **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 is the only format with perfect accuracy at scale, at 32% fewer tokens than TOON.
-
-Reproduce: `git clone https://github.com/blackwell-systems/gcf-go && cd gcf-go/eval && GOWORK=off go test -run TestComprehension -v -timeout 0`
-
-## Token Efficiency (TOON's Own Benchmark)
-
-Running [TOON's benchmark harness](https://github.com/blackwell-systems/toon/tree/gcf-comparison) with GCF inserted (their datasets, their tokenizer):
-
-| Track | GCF | TOON | Result |
-|-------|-----|------|--------|
-| Mixed-structure (nested, semi-uniform) | 170,367 | 227,896 | **GCF 34% smaller** |
-| Flat-only (tabular) | 66,029 | 67,837 | **GCF 3% smaller** |
-| Semi-uniform event logs | 108,158 | 154,032 | **GCF 42% smaller** |
-
-GCF wins all 6 datasets. On semi-uniform data (the most common real-world pattern), GCF uses 42% fewer tokens than TOON.
-
-Reproduce: `git clone https://github.com/blackwell-systems/toon && cd toon && git checkout gcf-comparison && cd benchmarks && pnpm install && pnpm benchmark:tokens`
+GCF wins all 6 datasets on [TOON's own benchmark](https://github.com/blackwell-systems/toon/tree/gcf-comparison). Full results: [gcformat.com/guide/benchmarks](https://gcformat.com/guide/benchmarks.html)
 
 ## Links
 
@@ -243,6 +228,16 @@ Reproduce: `git clone https://github.com/blackwell-systems/toon && cd toon && gi
 - [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
 - [TOON benchmark fork](https://github.com/blackwell-systems/toon/tree/gcf-comparison)
 
+
+<details>
+<summary>More links</summary>
+
+- [betterthanjson.com](https://betterthanjson.com)
+- [jsonalternative.com](https://jsonalternative.com)
+- [betterthantoon.com](https://betterthantoon.com)
+
+</details>
+
 ## License
 
-MIT
+MIT - [Dayna Blackwell](https://github.com/blackwell-systems)

{gcf_python-0.5.0 → gcf_python-1.0.0}/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.
 
-**79% fewer input tokens than JSON. 75% fewer output tokens. 52% smaller than TOON. 100% LLM comprehension at 500 symbols, where JSON scores 76.9% and TOON scores 92.3%.**
+**79% fewer input tokens than JSON. 63% fewer output tokens. 90.5% average comprehension accuracy across 10 models and 3 providers (four models hit 100%). 1,300+ 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)
 
@@ -179,33 +179,18 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 | `Session` | Thread-safe tracker for multi-call deduplication |
 | `KIND_ABBREV` / `KIND_EXPAND` | Bidirectional kind abbreviation dicts |
 
-## Comprehension Eval
+## Benchmarks
 
-Rigorous 3-way benchmark (GCF vs TOON vs JSON) at 500 symbols, 200 edges. 13 structured extraction questions sent to an LLM with zero format instructions:
+1,300+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.
 
-| Format | Accuracy | Tokens | vs JSON |
-|--------|----------|--------|---------|
-| **GCF** | **100%** (13/13) | **11,090** | **79% fewer** |
-| TOON | 92.3% (12/13) | 16,378 | 69% fewer |
-| JSON | 76.9% (10/13) | 53,341 | baseline |
+| | GCF | TOON | JSON |
+|---|---|---|---|
+| **Comprehension** (23 runs, 10 models) | **90.5%** | 68.5% | 53.6% |
+| **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 is the only format with perfect accuracy at scale, at 32% fewer tokens than TOON.
-
-Reproduce: `git clone https://github.com/blackwell-systems/gcf-go && cd gcf-go/eval && GOWORK=off go test -run TestComprehension -v -timeout 0`
-
-## Token Efficiency (TOON's Own Benchmark)
-
-Running [TOON's benchmark harness](https://github.com/blackwell-systems/toon/tree/gcf-comparison) with GCF inserted (their datasets, their tokenizer):
-
-| Track | GCF | TOON | Result |
-|-------|-----|------|--------|
-| Mixed-structure (nested, semi-uniform) | 170,367 | 227,896 | **GCF 34% smaller** |
-| Flat-only (tabular) | 66,029 | 67,837 | **GCF 3% smaller** |
-| Semi-uniform event logs | 108,158 | 154,032 | **GCF 42% smaller** |
-
-GCF wins all 6 datasets. On semi-uniform data (the most common real-world pattern), GCF uses 42% fewer tokens than TOON.
-
-Reproduce: `git clone https://github.com/blackwell-systems/toon && cd toon && git checkout gcf-comparison && cd benchmarks && pnpm install && pnpm benchmark:tokens`
+GCF wins all 6 datasets on [TOON's own benchmark](https://github.com/blackwell-systems/toon/tree/gcf-comparison). Full results: [gcformat.com/guide/benchmarks](https://gcformat.com/guide/benchmarks.html)
 
 ## Links
 
@@ -218,6 +203,16 @@ Reproduce: `git clone https://github.com/blackwell-systems/toon && cd toon && gi
 - [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
 - [TOON benchmark fork](https://github.com/blackwell-systems/toon/tree/gcf-comparison)
 
+
+<details>
+<summary>More links</summary>
+
+- [betterthanjson.com](https://betterthanjson.com)
+- [jsonalternative.com](https://jsonalternative.com)
+- [betterthantoon.com](https://betterthantoon.com)
+
+</details>
+
 ## License
 
-MIT
+MIT - [Dayna Blackwell](https://github.com/blackwell-systems)

{gcf_python-0.5.0 → gcf_python-1.0.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-version = "0.5.0"
-description = "Python implementation of GCF (Graph Compact Format): token-optimized wire format for LLM tool responses"
+version = "1.0.0"
+description = "Drop-in JSON replacement for AI pipelines. 79% fewer tokens. 90.5% comprehension across 10 models. Zero dependencies."
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.9"

{gcf_python-0.5.0 → gcf_python-1.0.0}/src/gcf/__init__.py

@@ -65,4 +65,4 @@ __all__ = [
     "encode_with_session",
 ]
 
-__version__ = "0.1.3"
+__version__ = "1.0.0"

{gcf_python-0.5.0 → gcf_python-1.0.0}/src/gcf/decode.py

@@ -35,7 +35,11 @@ def decode(input_text: str) -> Payload:
     _parse_header(header[4:], p)
 
     if not p.tool:
-        raise DecodeError("header missing required 'tool' field")
+        raise DecodeError("missing_tool: header missing required 'tool' field")
+
+    # Detect delta mode.
+    is_delta = "delta=true" in header
+    valid_delta_sections = {"removed", "added", "edges_removed", "edges_added"}
 
     # Parse body: symbols and edges.
     symbols: list[Symbol] = []
@@ -48,6 +52,10 @@ def decode(input_text: str) -> Payload:
         if not line:
             continue
 
+        # Skip ##! summary trailer.
+        if line.startswith("##! "):
+            continue
+
         # Group header.
         if line.startswith("## "):
             group = line[3:]
@@ -55,6 +63,8 @@ def decode(input_text: str) -> Payload:
             bracket_idx = group.find(" [")
             if bracket_idx >= 0:
                 group = group[:bracket_idx]
+            if is_delta and group not in valid_delta_sections:
+                raise DecodeError(f"malformed_delta: invalid delta section {group!r}")
             in_edges = group == "edges"
             if not in_edges:
                 if group == "targets":
@@ -113,19 +123,19 @@ def _parse_header(fields: str, p: Payload) -> None:
 def _parse_symbol_line(line: str, distance: int) -> tuple[Symbol, int]:
     """Parse a symbol line into a Symbol and its local ID."""
     if not line.startswith("@"):
-        raise DecodeError(f"expected symbol line starting with @, got {line!r}")
+        raise DecodeError(f"invalid_node_line: expected symbol line starting with @, got {line!r}")
 
     parts = line.split()
     if len(parts) < 5:
         raise DecodeError(
-            f"symbol line needs at least 5 fields, got {len(parts)} in {line!r}"
+            f"invalid_node_line: symbol line needs at least 5 fields, got {len(parts)} in {line!r}"
         )
 
     id_str = parts[0][1:]  # strip @
     try:
         sym_id = int(id_str)
     except ValueError as e:
-        raise DecodeError(f"invalid symbol id {id_str!r}: {e}") from e
+        raise DecodeError(f"invalid_symbol_id: invalid symbol id {id_str!r}: {e}") from e
 
     kind = parts[1]
     kind = KIND_EXPAND.get(kind, kind)
@@ -135,7 +145,7 @@ def _parse_symbol_line(line: str, distance: int) -> tuple[Symbol, int]:
     try:
         score = float(parts[3])
     except ValueError as e:
-        raise DecodeError(f"invalid score {parts[3]!r}: {e}") from e
+        raise DecodeError(f"invalid_score: invalid score {parts[3]!r}: {e}") from e
 
     provenance = parts[4]
 
@@ -157,7 +167,7 @@ def _parse_edge_line(line: str, sym_by_id: dict[int, Symbol]) -> Edge:
     ref = parts[0]
     lt_idx = ref.find("<")
     if lt_idx < 0:
-        raise DecodeError(f"edge line missing '<' separator in {ref!r}")
+        raise DecodeError(f"invalid_edge_syntax: edge line missing '<' separator in {ref!r}")
 
     target_id_str = ref[1:lt_idx]  # strip leading @
     source_id_str = ref[lt_idx + 2:]  # strip <@
@@ -176,7 +186,7 @@ def _parse_edge_line(line: str, sym_by_id: dict[int, Symbol]) -> Edge:
     source_sym = sym_by_id.get(source_id)
     if target_sym is None or source_sym is None:
         raise DecodeError(
-            f"edge references unknown symbol id(s): target={target_id} source={source_id}"
+            f"unknown_edge_reference: edge references unknown symbol id(s): target={target_id} source={source_id}"
         )
 
     edge_type = parts[1]