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

{gcf_python-2.2.2 → gcf_python-2.3.0}/.github/workflows/ci.yml

@@ -13,7 +13,11 @@ jobs:
       matrix:
         python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
+      # Check out gcf-python and the shared-fixtures gcf repo as SIBLINGS so the
+      # conformance runner's ../gcf/tests/conformance path resolves on CI.
       - uses: actions/checkout@v4
+        with:
+          path: gcf-python
       - uses: actions/checkout@v4
         with:
           repository: blackwell-systems/gcf
@@ -22,9 +26,13 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: pip install -e ".[dev]" || pip install -e . && pip install pytest
+        working-directory: gcf-python
       - name: Unit tests
         run: pytest tests/ -v --ignore=tests/test_conformance_v2.py --ignore=tests/test_roundtrip_v2.py
-      - name: Conformance tests (133 fixtures)
+        working-directory: gcf-python
+      - name: Conformance tests (shared fixtures)
         run: pytest tests/test_conformance_v2.py -v
+        working-directory: gcf-python
       - name: Property-based round-trip (100K random + 100K adversarial)
         run: pytest tests/test_roundtrip_v2.py -v
+        working-directory: gcf-python

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

@@ -1,5 +1,24 @@
 # Changelog
 
+## v2.3.0 (2026-07-12)
+
+### Generic-profile delta encoding (SPEC §10a)
+
+- Full producer + consumer implementation of generic-profile delta, byte-for-byte interoperable with `gcf-go`:
+  - `GenericSet` (keyed record set), `GenericDeltaPayload`
+  - `generic_pack_root` (`gcf-pack-root-v1`, generic profile) with a purpose-built cell canonicalization decoupled from the wire cell encoder: collision-free (null/bool/number bare, strings always quoted) and record-safe. Fields and records sort by UTF-8 byte order to match Go's `sort.Strings`.
+  - `diff_generic_sets` (the blessed producer path; centralizes the keyed-diff invariants), `encode_generic_full`, `encode_generic_delta`
+  - `decode_generic_full`, `decode_generic_delta` (consumer wire parsing)
+  - `verify_generic_delta` (atomic apply + `new_root` verification)
+  - Re-anchor session helper (SPEC §10a.8): `GenericDeltaSession` (`current_full`, `next`) with `ReanchorPolicy` / `fixed_n(n)` / `size_guard()` cadence policies and `DEFAULT_REANCHOR_N = 15`. Producer-side sugar over the primitives; introduces no new wire syntax (every emission is exactly `encode_generic_full` / `encode_generic_delta` output). Re-anchor cadence is byte-for-byte identical to `gcf-go` (size guard uses UTF-8 byte length to match Go's `len(string)`), verified by the shared `generic-delta-session` conformance fixtures.
+- Delta is opt-in and bilateral; the existing `encode_generic` path is unchanged (backward compatible).
+
+### Tests
+
+- Unit suite mirroring `gcf-go`: self-proving round-trip (diff -> encode -> apply -> recomputed root), determinism / row-order invariance, no-type-collision canonicalization, every invariant/error path, full-payload wire round-trip, the complete server -> wire -> consumer end-to-end loop, and malformed-wire-fails-closed.
+- Conformance runner support for `generic-pack-root`, `generic-delta`, `generic-delta-verify`, `generic-delta-decode` (12 shared fixtures); verified to produce identical pack roots and delta wire to `gcf-go`.
+- Session helper suite (`test_generic_delta_session.py`) mirroring `gcf-go`: FixedN cadence pattern, size-guard triggering, schema-change forced full, FixedN(15)-over-30-turns count, and the load-bearing consumer-stays-in-sync check under both policies. Conformance runner support for `generic-delta-session` (3 shared fixtures: fixed-N, size-guard, schema-change).
+
 ## v2.2.2 (2026-07-10)
 
 ### Fixes

gcf_python-2.2.2/README.md → gcf_python-2.3.0/PKG-INFO

@@ -1,3 +1,28 @@
+Metadata-Version: 2.4
+Name: gcf-python
+Version: 2.3.0
+Summary: The AI-native wire format for structured data. 50-92% fewer tokens than JSON, with multi-turn delta encoding for agent loops. 100% comprehension on every frontier model. Zero dependencies.
+Project-URL: Homepage, https://github.com/blackwell-systems/gcf-python
+Project-URL: Documentation, https://gcformat.com/
+Project-URL: Specification, https://github.com/blackwell-systems/gcf
+Author: Blackwell Systems
+License: MIT
+License-File: LICENSE
+Keywords: agents,delta,gcf,graph,llm,mcp,multi-turn,token-efficient,wire-format
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
 <p align="center">
   <a href="https://github.com/blackwell-systems"><img src="https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg" alt="Blackwell Systems"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
@@ -157,6 +182,44 @@ Output:
 
 Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows. Nested dicts use `## key` section headers.
 
+## Generic-Profile Delta (multi-turn)
+
+In an agent loop the same keyed table gets re-queried turn after turn. Instead of re-sending the whole table each time, send only the changed rows (SPEC §10a):
+
+```python
+from gcf import GenericSet, diff_generic_sets, encode_generic_delta, verify_generic_delta
+
+base = GenericSet(key="id", fields=["id", "status"], rows=[
+    {"id": 1001, "status": "pending"},
+    {"id": 1002, "status": "shipped"},
+])
+nxt = GenericSet(key="id", fields=["id", "status"], rows=[
+    {"id": 1001, "status": "shipped"},   # changed
+    {"id": 1003, "status": "pending"},   # added (1002 removed)
+])
+
+d = diff_generic_sets(base, nxt)
+wire = encode_generic_delta(d)                       # ## added / ## changed / ## removed
+held = verify_generic_delta(base, d, d.new_root)     # atomic apply + new_root verification
+```
+
+Opt-in and bilateral, keyed on content-addressed pack roots. By the 5th overlapping call, ~97% fewer tokens than re-sending JSON.
+
+### Re-anchor session helper
+
+`GenericDeltaSession` manages the delta/re-anchor cadence for you: each `next()` returns either a compact delta or, on its cadence, a full re-anchor (which re-grounds the consumer), updating its held base.
+
+```python
+from gcf import GenericDeltaSession, fixed_n, size_guard
+
+sess = GenericDeltaSession(base, tool="orders", policy=size_guard())
+wire = sess.current_full()                # transmit the base once to establish it
+for snapshot in stream:                   # each turn's current GenericSet
+    wire, is_full = sess.next(snapshot)    # a compact delta, or a periodic full re-anchor
+```
+
+`fixed_n(15)` re-anchors every N turns; `size_guard()` (recommended) re-anchors once the cumulative delta reaches a full payload's size. It introduces no new wire syntax and the decoder stays cadence-agnostic, so a re-anchor is just the protocol's "full" outcome on a schedule.
+
 ## API
 
 | Function | Description |
@@ -165,7 +228,11 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 | `encode_generic(data: Any) -> str` | Encode any value to GCF tabular format |
 | `decode(input_text: str) -> Payload` | Parse GCF text back to a Payload |
 | `encode_with_session(p: Payload, s: Session) -> str` | Encode with session deduplication |
-| `encode_delta(d: DeltaPayload) -> str` | Encode a delta (added/removed only) |
+| `encode_delta(d: DeltaPayload) -> str` | Encode a graph delta (added/removed only) |
+| `diff_generic_sets(base, next) -> GenericDeltaPayload` | Diff two keyed record sets (generic profile) |
+| `encode_generic_delta(d) -> str` / `decode_generic_delta(s)` | Generic-profile delta wire (§10a) |
+| `verify_generic_delta(base, d, root) -> GenericSet` | Atomic apply + `new_root` verification |
+| `GenericDeltaSession(base, tool, policy)` | Producer-side re-anchor cadence helper (§10a.8) |
 | `Session()` | Create a new session tracker (thread-safe) |
 
 ## Types
@@ -175,7 +242,9 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 | `Payload` | Full GCF payload: tool, budget, symbols, edges, pack root |
 | `Symbol` | Graph node: qualified name, kind, score, provenance, distance |
 | `Edge` | Directed relationship: source, target, edge type |
-| `DeltaPayload` | Diff between two packs: added/removed symbols and edges |
+| `DeltaPayload` | Diff between two graph packs: added/removed symbols and edges |
+| `GenericSet` / `GenericDeltaPayload` | Keyed record set and its generic-profile diff (§10a) |
+| `GenericDeltaSession` | Stateful producer that schedules delta vs full re-anchor (§10a.8) |
 | `Session` | Thread-safe tracker for multi-call deduplication |
 | `KIND_ABBREV` / `KIND_EXPAND` | Bidirectional kind abbreviation dicts |
 

gcf_python-2.2.2/PKG-INFO → gcf_python-2.3.0/README.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.4
-Name: gcf-python
-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
-Author: Blackwell Systems
-License: MIT
-License-File: LICENSE
-Keywords: gcf,graph,llm,mcp,token-efficient,wire-format
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Typing :: Typed
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
 <p align="center">
   <a href="https://github.com/blackwell-systems"><img src="https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg" alt="Blackwell Systems"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
@@ -182,6 +157,44 @@ Output:
 
 Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows. Nested dicts use `## key` section headers.
 
+## Generic-Profile Delta (multi-turn)
+
+In an agent loop the same keyed table gets re-queried turn after turn. Instead of re-sending the whole table each time, send only the changed rows (SPEC §10a):
+
+```python
+from gcf import GenericSet, diff_generic_sets, encode_generic_delta, verify_generic_delta
+
+base = GenericSet(key="id", fields=["id", "status"], rows=[
+    {"id": 1001, "status": "pending"},
+    {"id": 1002, "status": "shipped"},
+])
+nxt = GenericSet(key="id", fields=["id", "status"], rows=[
+    {"id": 1001, "status": "shipped"},   # changed
+    {"id": 1003, "status": "pending"},   # added (1002 removed)
+])
+
+d = diff_generic_sets(base, nxt)
+wire = encode_generic_delta(d)                       # ## added / ## changed / ## removed
+held = verify_generic_delta(base, d, d.new_root)     # atomic apply + new_root verification
+```
+
+Opt-in and bilateral, keyed on content-addressed pack roots. By the 5th overlapping call, ~97% fewer tokens than re-sending JSON.
+
+### Re-anchor session helper
+
+`GenericDeltaSession` manages the delta/re-anchor cadence for you: each `next()` returns either a compact delta or, on its cadence, a full re-anchor (which re-grounds the consumer), updating its held base.
+
+```python
+from gcf import GenericDeltaSession, fixed_n, size_guard
+
+sess = GenericDeltaSession(base, tool="orders", policy=size_guard())
+wire = sess.current_full()                # transmit the base once to establish it
+for snapshot in stream:                   # each turn's current GenericSet
+    wire, is_full = sess.next(snapshot)    # a compact delta, or a periodic full re-anchor
+```
+
+`fixed_n(15)` re-anchors every N turns; `size_guard()` (recommended) re-anchors once the cumulative delta reaches a full payload's size. It introduces no new wire syntax and the decoder stays cadence-agnostic, so a re-anchor is just the protocol's "full" outcome on a schedule.
+
 ## API
 
 | Function | Description |
@@ -190,7 +203,11 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 | `encode_generic(data: Any) -> str` | Encode any value to GCF tabular format |
 | `decode(input_text: str) -> Payload` | Parse GCF text back to a Payload |
 | `encode_with_session(p: Payload, s: Session) -> str` | Encode with session deduplication |
-| `encode_delta(d: DeltaPayload) -> str` | Encode a delta (added/removed only) |
+| `encode_delta(d: DeltaPayload) -> str` | Encode a graph delta (added/removed only) |
+| `diff_generic_sets(base, next) -> GenericDeltaPayload` | Diff two keyed record sets (generic profile) |
+| `encode_generic_delta(d) -> str` / `decode_generic_delta(s)` | Generic-profile delta wire (§10a) |
+| `verify_generic_delta(base, d, root) -> GenericSet` | Atomic apply + `new_root` verification |
+| `GenericDeltaSession(base, tool, policy)` | Producer-side re-anchor cadence helper (§10a.8) |
 | `Session()` | Create a new session tracker (thread-safe) |
 
 ## Types
@@ -200,7 +217,9 @@ Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows.
 | `Payload` | Full GCF payload: tool, budget, symbols, edges, pack root |
 | `Symbol` | Graph node: qualified name, kind, score, provenance, distance |
 | `Edge` | Directed relationship: source, target, edge type |
-| `DeltaPayload` | Diff between two packs: added/removed symbols and edges |
+| `DeltaPayload` | Diff between two graph packs: added/removed symbols and edges |
+| `GenericSet` / `GenericDeltaPayload` | Keyed record set and its generic-profile diff (§10a) |
+| `GenericDeltaSession` | Stateful producer that schedules delta vs full re-anchor (§10a.8) |
 | `Session` | Thread-safe tracker for multi-call deduplication |
 | `KIND_ABBREV` / `KIND_EXPAND` | Bidirectional kind abbreviation dicts |
 

{gcf_python-2.2.2 → gcf_python-2.3.0}/pyproject.toml

@@ -4,17 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-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."
+version = "2.3.0"
+description = "The AI-native wire format for structured data. 50-92% fewer tokens than JSON, with multi-turn delta encoding for agent loops. 100% comprehension on every frontier model. Zero dependencies."
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.9"
 authors = [
     { name = "Blackwell Systems" },
 ]
-keywords = ["gcf", "llm", "mcp", "token-efficient", "graph", "wire-format"]
+keywords = ["gcf", "llm", "mcp", "token-efficient", "graph", "wire-format", "delta", "multi-turn", "agents"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
@@ -32,7 +32,7 @@ gcf = "gcf.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/blackwell-systems/gcf-python"
-Documentation = "https://blackwell-systems.github.io/gcf/"
+Documentation = "https://gcformat.com/"
 Specification = "https://github.com/blackwell-systems/gcf"
 
 [tool.hatch.build.targets.wheel]

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

@@ -39,6 +39,23 @@ from .decode import DecodeError, decode
 from .delta import encode_delta
 from .encode import encode
 from .generic import encode_generic, GenericOptions
+from .generic_delta import (
+    GenericSet,
+    GenericDeltaPayload,
+    generic_pack_root,
+    diff_generic_sets,
+    encode_generic_full,
+    encode_generic_delta,
+    decode_generic_full,
+    decode_generic_delta,
+    verify_generic_delta,
+    GenericDeltaSession,
+    ReanchorPolicy,
+    ReanchorMode,
+    fixed_n,
+    size_guard,
+    DEFAULT_REANCHOR_N,
+)
 from .session import Session, encode_with_session
 from .decode_generic import decode_generic
 from .stream import StreamEncoder
@@ -64,6 +81,21 @@ __all__ = [
     "encode_generic",
     "GenericOptions",
     "encode_with_session",
+    "GenericSet",
+    "GenericDeltaPayload",
+    "generic_pack_root",
+    "diff_generic_sets",
+    "encode_generic_full",
+    "encode_generic_delta",
+    "decode_generic_full",
+    "decode_generic_delta",
+    "verify_generic_delta",
+    "GenericDeltaSession",
+    "ReanchorPolicy",
+    "ReanchorMode",
+    "fixed_n",
+    "size_guard",
+    "DEFAULT_REANCHOR_N",
 ]
 
-__version__ = "2.2.2"
+__version__ = "2.3.0"