gcf-python 0.5.1__tar.gz → 1.0.1__tar.gz

gcf_python-1.0.1/.github/FUNDING.yml

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

gcf_python-1.0.1/.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.1 → gcf_python-1.0.1}/.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.1 → gcf_python-1.0.1}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v1.0.1 (2026-06-10)
+
+- CLI: `encode-generic` and `decode-generic` subcommands for generic profile
+- CLI now supports both graph and generic profiles
+- `python -m gcf` entry point
+
+## 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.1 → gcf_python-1.0.1}/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.1 → gcf_python-1.0.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 0.5.1
-Summary: Python implementation of GCF (Graph Compact Format): token-optimized wire format for LLM tool responses
+Version: 1.0.1
+Summary: Drop-in JSON replacement for AI pipelines. 79% fewer tokens. 90.7% 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. 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.**
+**79% fewer input tokens than JSON. 63% fewer output tokens. 90.7% 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)
 
@@ -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) | **90.5%** | 68.5% | 53.6% |
+| **Comprehension** (23 runs, 10 models) | **90.7%** | 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 |
@@ -228,6 +228,16 @@ GCF wins all 6 datasets on [TOON's own benchmark](https://github.com/blackwell-s
 - [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.1 → gcf_python-1.0.1}/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. 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.**
+**79% fewer input tokens than JSON. 63% fewer output tokens. 90.7% 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)
 
@@ -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) | **90.5%** | 68.5% | 53.6% |
+| **Comprehension** (23 runs, 10 models) | **90.7%** | 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 |
@@ -203,6 +203,16 @@ GCF wins all 6 datasets on [TOON's own benchmark](https://github.com/blackwell-s
 - [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.1 → gcf_python-1.0.1}/pyproject.toml

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

{gcf_python-0.5.1 → gcf_python-1.0.1}/src/gcf/__init__.py

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

gcf_python-1.0.1/src/gcf/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m gcf`."""
+
+from .cli import main
+
+main()

{gcf_python-0.5.1 → gcf_python-1.0.1}/src/gcf/cli.py

@@ -5,19 +5,25 @@ import sys
 
 from .decode import decode
 from .encode import encode
+from .decode_generic import decode_generic
+from .generic import encode_generic
 from .types import Edge, Payload, Symbol
 
 USAGE = """gcf - token-optimized wire format for LLM tool responses
 
 Usage:
-  gcf encode [file]    Encode JSON payload to GCF (stdin if no file)
-  gcf decode [file]    Decode GCF text to JSON (stdin if no file)
-  gcf stats  [file]    Compare token counts: JSON vs GCF (stdin if no file)
-  gcf version          Print version
+  gcf encode          [file]  Encode JSON graph payload to GCF (stdin if no file)
+  gcf decode          [file]  Decode GCF graph text to JSON (stdin if no file)
+  gcf encode-generic  [file]  Encode JSON to GCF generic profile (stdin if no file)
+  gcf decode-generic  [file]  Decode GCF generic text to JSON (stdin if no file)
+  gcf stats           [file]  Compare token counts: JSON vs GCF (stdin if no file)
+  gcf version                 Print version
 
 Examples:
   gcf encode < payload.json
   gcf decode < payload.gcf
+  echo '{"name":"Alice"}' | gcf encode-generic
+  echo 'GCF profile=generic\\nname=Alice' | gcf decode-generic
   gcf stats payload.json
 """
 
@@ -37,11 +43,18 @@ def main() -> None:
     elif cmd == "decode":
         data = _read_input(file_args)
         _do_decode(data)
+    elif cmd == "encode-generic":
+        data = _read_input(file_args)
+        _do_encode_generic(data)
+    elif cmd == "decode-generic":
+        data = _read_input(file_args)
+        _do_decode_generic(data)
     elif cmd == "stats":
         data = _read_input(file_args)
         _do_stats(data)
     elif cmd == "version":
-        print("gcf 0.1.0")
+        from . import __version__
+        print(f"gcf {__version__}")
     else:
         print(f"unknown command: {cmd}\n", file=sys.stderr)
         print(USAGE, file=sys.stderr, end="")
@@ -115,6 +128,20 @@ def _payload_to_json(p: Payload) -> str:
     return json.dumps(obj, indent=2)
 
 
+def _do_encode_generic(data: str) -> None:
+    try:
+        obj = json.loads(data)
+    except json.JSONDecodeError as e:
+        print(f"error: invalid JSON: {e}", file=sys.stderr)
+        sys.exit(1)
+    print(encode_generic(obj), end="")
+
+
+def _do_decode_generic(data: str) -> None:
+    result = decode_generic(data)
+    print(json.dumps(result))
+
+
 def _do_encode(data: str) -> None:
     try:
         p = _payload_from_json(data)

{gcf_python-0.5.1 → gcf_python-1.0.1}/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]