gcf-python 2.6.0__tar.gz → 2.7.0__tar.gz

{gcf_python-2.6.0 → gcf_python-2.7.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v2.7.0 (2026-08-15)
+
+- Decode: quoted-key/array-value round-trip (SPEC 4.2).
+- Added: `gcf.fastmcp.GcfResponseMiddleware`, opt-in GCF encoding for FastMCP responses.
+
 ## v2.6.0 (2026-08-14)
 
 - **Numeric domain (spec v3.5.3, SPEC 2.3.2).** Specifies the canonical numeric domain as signed `int64` for integers and IEEE-754 double for non-integers. Earlier versions left integers beyond the double-exact range (2^53) to the host numeric type; this version parses integer literals to an exact `int64` on decode and on the JSON-to-value bridge, returns an out-of-range error for a value outside `int64` on both decode and encode, and models larger values (unsigned-64 identifiers, exact decimals) as strings. Canonical number formatting aligns to the domain: a double at or above 2^53 renders in exponent notation. Verified against new `numbers/017-024` and `errors-v2/041-042` conformance fixtures and the cross-SDK differential fuzz. An out-of-range value raises `ValueError`.

{gcf_python-2.6.0 → gcf_python-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gcf-python
-Version: 2.6.0
+Version: 2.7.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/
@@ -21,6 +21,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp>=2.11.0; extra == 'fastmcp'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -244,6 +246,22 @@ for snapshot in stream:                   # each turn's current GenericSet
 
 `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.
 
+## FastMCP middleware
+
+A drop-in middleware for [FastMCP](https://gofastmcp.com) servers that re-encodes JSON tool results as GCF, opt-in. It requires the `fastmcp` extra (the core package stays zero-dependency):
+
+```bash
+pip install "gcf-python[fastmcp]"
+```
+
+```python
+from gcf.fastmcp import GcfResponseMiddleware
+
+mcp.add_middleware(GcfResponseMiddleware())
+```
+
+When `RESPONSE_FORMAT=gcf` is set in the environment, each tool result whose model-facing content is a single JSON text block is returned as a GCF generic wire instead of JSON. It is opt-in (nothing changes unless the variable is set), lossless and fail-safe (on any encoding error the original result is returned), and non-destructive: only a lone JSON text block is re-encoded, and the tool's `structuredContent` is preserved so output-schema validation and non-model clients keep receiving JSON.
+
 ## API
 
 | Function | Description |
@@ -304,7 +322,7 @@ 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.5.2 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 269 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. Current versions: Go v1.6.2, TypeScript v2.5.2, Python v2.5.3, Rust v2.5.3, Swift v2.6.2, Kotlin v2.5.2, .NET v0.1.2. Cross-language conformance verified across all seven SDKs.
+**Specification:** [SPEC v3.5.3 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 279 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. Current versions: Go v1.7.0, TypeScript v2.6.0, Python v2.6.0, Rust v3.0.0, Swift v2.7.0, Kotlin v2.6.0, .NET v0.2.0. Cross-language conformance verified across all seven SDKs.
 
 ## Adopted by
 

{gcf_python-2.6.0 → gcf_python-2.7.0}/README.md

@@ -219,6 +219,22 @@ for snapshot in stream:                   # each turn's current GenericSet
 
 `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.
 
+## FastMCP middleware
+
+A drop-in middleware for [FastMCP](https://gofastmcp.com) servers that re-encodes JSON tool results as GCF, opt-in. It requires the `fastmcp` extra (the core package stays zero-dependency):
+
+```bash
+pip install "gcf-python[fastmcp]"
+```
+
+```python
+from gcf.fastmcp import GcfResponseMiddleware
+
+mcp.add_middleware(GcfResponseMiddleware())
+```
+
+When `RESPONSE_FORMAT=gcf` is set in the environment, each tool result whose model-facing content is a single JSON text block is returned as a GCF generic wire instead of JSON. It is opt-in (nothing changes unless the variable is set), lossless and fail-safe (on any encoding error the original result is returned), and non-destructive: only a lone JSON text block is re-encoded, and the tool's `structuredContent` is preserved so output-schema validation and non-model clients keep receiving JSON.
+
 ## API
 
 | Function | Description |
@@ -279,7 +295,7 @@ 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.5.2 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 269 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. Current versions: Go v1.6.2, TypeScript v2.5.2, Python v2.5.3, Rust v2.5.3, Swift v2.6.2, Kotlin v2.5.2, .NET v0.1.2. Cross-language conformance verified across all seven SDKs.
+**Specification:** [SPEC v3.5.3 Stable](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) with 279 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. Current versions: Go v1.7.0, TypeScript v2.6.0, Python v2.6.0, Rust v3.0.0, Swift v2.7.0, Kotlin v2.6.0, .NET v0.2.0. Cross-language conformance verified across all seven SDKs.
 
 ## Adopted by
 

{gcf_python-2.6.0 → gcf_python-2.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-version = "2.6.0"
+version = "2.7.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"}
@@ -27,6 +27,13 @@ classifiers = [
     "Typing :: Typed",
 ]
 
+# The core package is zero-dependency. The optional 'fastmcp' extra pulls FastMCP
+# only for the gcf.fastmcp integration middleware (import gcf.fastmcp requires it).
+[project.optional-dependencies]
+fastmcp = [
+    "fastmcp>=2.11.0",
+]
+
 [project.scripts]
 gcf = "gcf.cli:main"
 

{gcf_python-2.6.0 → gcf_python-2.7.0}/src/gcf/__init__.py

@@ -102,4 +102,4 @@ __all__ = [
     "DEFAULT_REANCHOR_N",
 ]
 
-__version__ = "2.6.0"
+__version__ = "2.7.0"

{gcf_python-2.6.0 → gcf_python-2.7.0}/src/gcf/decode_generic.py

@@ -171,7 +171,7 @@ def _parse_object_body(
 
         # Inline array (e.g. items[3]: a,b,c). Only reached if no = found.
         if not content.startswith("@") and not content.startswith("##"):
-            bracket_idx = content.find("[")
+            bracket_idx = _find_array_bracket(content)
             if bracket_idx > 0:
                 rest = content[bracket_idx:]
                 close_idx = rest.find("]")
@@ -196,6 +196,26 @@ def _parse_object_body(
     return i - start
 
 
+def _find_array_bracket(s: str) -> int:
+    """Index of the '[' that opens a named-array marker (``key[N]: ...``).
+
+    A quoted key is scanned first so a '[' inside the key name is not mistaken
+    for the array bracket (bare keys cannot contain '['). Returns -1 when the
+    key is a quoted string not immediately followed by '['.
+    """
+    if s and s[0] == '"':
+        i = 1
+        while i < len(s):
+            if s[i] == "\\":
+                i += 2
+                continue
+            if s[i] == '"':
+                return i + 1 if i + 1 < len(s) and s[i + 1] == "[" else -1
+            i += 1
+        return -1
+    return s.find("[")
+
+
 def _find_kv_split(s: str) -> int:
     if not s:
         return -1

gcf_python-2.7.0/src/gcf/fastmcp.py

@@ -0,0 +1,131 @@
+"""Optional FastMCP middleware for opt-in GCF response encoding.
+
+This is a small integration helper for `FastMCP <https://gofastmcp.com>`_ servers.
+It requires the ``fastmcp`` extra; the core ``gcf`` package stays
+zero-dependency::
+
+    pip install "gcf-python[fastmcp]"
+
+Register it once on a FastMCP server::
+
+    from gcf.fastmcp import GcfResponseMiddleware
+
+    mcp.add_middleware(GcfResponseMiddleware())
+
+When ``RESPONSE_FORMAT=gcf`` is set in the environment, each tool result whose
+model-facing content is a single JSON text block is re-encoded as a GCF generic
+wire, so the response uses fewer tokens when it crosses the LLM boundary. It is:
+
+- **Opt-in** — nothing changes unless ``RESPONSE_FORMAT=gcf`` is set (or
+  ``enabled=True`` is passed).
+- **Lossless and fail-safe** — on any encoding error the original result is
+  returned, so a tool call is never dropped over formatting.
+- **Non-destructive** — only a lone JSON text block is re-encoded; a result
+  carrying an image or any second block is left untouched, and the tool's
+  ``structuredContent`` (if any) is preserved so output-schema validation and
+  non-model clients keep receiving JSON.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Optional
+
+try:
+    from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+    from fastmcp.tools.tool import ToolResult
+    from mcp.types import TextContent
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(
+        "gcf.fastmcp requires the optional 'fastmcp' dependency: "
+        'pip install "gcf-python[fastmcp]"'
+    ) from exc
+
+from .decode_generic import decode_generic
+from .generic import encode_generic
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_ENV_VAR = "RESPONSE_FORMAT"
+
+
+def gcf_response_enabled(env_var: str = DEFAULT_ENV_VAR) -> bool:
+    """Return True when ``env_var`` is set to ``gcf`` in the environment."""
+    return os.environ.get(env_var, "").strip().lower() == "gcf"
+
+
+class GcfResponseMiddleware(Middleware):
+    """FastMCP middleware that re-encodes JSON tool results as GCF, opt-in.
+
+    Args:
+        env_var: Environment variable that gates encoding. Defaults to
+            ``RESPONSE_FORMAT``; encoding is on when its value is ``gcf``.
+        enabled: Force encoding on or off, bypassing the environment gate.
+            ``None`` (the default) reads the environment on each call.
+    """
+
+    def __init__(
+        self,
+        *,
+        env_var: str = DEFAULT_ENV_VAR,
+        enabled: Optional[bool] = None,
+    ) -> None:
+        self._env_var = env_var
+        self._enabled = enabled
+
+    def _is_enabled(self) -> bool:
+        if self._enabled is not None:
+            return self._enabled
+        return gcf_response_enabled(self._env_var)
+
+    async def on_call_tool(
+        self,
+        context: "MiddlewareContext",
+        call_next: "CallNext",
+    ) -> "ToolResult":
+        result = await call_next(context)
+
+        if not self._is_enabled():
+            return result
+
+        payload = _json_payload(result)
+        if payload is None:
+            return result
+
+        try:
+            wire = encode_generic(payload)
+            # Verify the wire decodes back to the same value before shipping it, so a
+            # result is never replaced with an unparseable or lossy encoding.
+            if decode_generic(wire) != payload:
+                return result
+        except Exception as exc:  # noqa: BLE001 - liveness over correctness of format
+            logger.debug("GCF encoding skipped: %s", exc)
+            return result
+
+        return ToolResult(
+            content=[TextContent(type="text", text=wire)],
+            structured_content=result.structured_content,
+        )
+
+
+def _json_payload(result: "ToolResult") -> Optional[Any]:
+    """The JSON value to encode, or None if the result is not a single JSON body.
+
+    Only a result whose content is exactly one text block is re-encoded, so an
+    image or other block sent alongside it is never dropped. ``structuredContent``
+    (the tool's typed value) is preferred as the payload; otherwise the lone text
+    block is parsed as JSON.
+    """
+    content = result.content or []
+    if len(content) != 1 or not isinstance(content[0], TextContent):
+        return None
+
+    if result.structured_content is not None:
+        return result.structured_content
+
+    try:
+        return json.loads(content[0].text)
+    except (json.JSONDecodeError, ValueError):
+        return None

gcf_python-2.7.0/tests/test_fastmcp.py

@@ -0,0 +1,181 @@
+"""Tests for the optional gcf.fastmcp integration middleware.
+
+Skipped cleanly when the 'fastmcp' extra is not installed.
+"""
+
+import asyncio
+import json
+import random
+from types import SimpleNamespace
+
+import pytest
+
+pytest.importorskip("fastmcp")
+
+from fastmcp.tools.tool import ToolResult  # noqa: E402
+from mcp.types import TextContent  # noqa: E402
+
+from gcf import decode_generic  # noqa: E402
+from gcf.fastmcp import GcfResponseMiddleware, gcf_response_enabled  # noqa: E402
+
+
+def _run(middleware, result):
+    async def call_next(_context):
+        return result
+
+    return asyncio.run(middleware.on_call_tool(SimpleNamespace(), call_next))
+
+
+def _result(*content, structured_content=None):
+    return ToolResult(content=list(content), structured_content=structured_content)
+
+
+def _text(result):
+    return result.content[0].text
+
+
+def _docs(n):
+    return [{"id": i, "name": f"n{i}", "role": "admin" if i % 2 else "user"} for i in range(n)]
+
+
+def test_gcf_response_enabled_reads_env(monkeypatch):
+    monkeypatch.delenv("RESPONSE_FORMAT", raising=False)
+    assert gcf_response_enabled() is False
+    for value in ("gcf", "GCF", " gcf "):
+        monkeypatch.setenv("RESPONSE_FORMAT", value)
+        assert gcf_response_enabled() is True
+    monkeypatch.setenv("RESPONSE_FORMAT", "json")
+    assert gcf_response_enabled() is False
+
+
+def test_encodes_structured_content_as_gcf():
+    data = {"rows": _docs(20)}
+    result = _result(TextContent(type="text", text=json.dumps(data)), structured_content=data)
+
+    out = _run(GcfResponseMiddleware(enabled=True), result)
+
+    assert _text(out).startswith("GCF profile=generic")
+    assert decode_generic(_text(out)) == data  # lossless round-trip
+    assert out.structured_content == data  # preserved for non-model clients
+
+
+def test_encodes_json_text_when_no_structured_content():
+    data = _docs(20)
+    result = _result(TextContent(type="text", text=json.dumps(data)))
+
+    out = _run(GcfResponseMiddleware(enabled=True), result)
+
+    assert _text(out).startswith("GCF profile=generic")
+    assert decode_generic(_text(out)) == data
+
+
+def test_disabled_leaves_result_unchanged():
+    text = json.dumps(_docs(20))
+    result = _result(TextContent(type="text", text=text))
+
+    out = _run(GcfResponseMiddleware(enabled=False), result)
+
+    assert _text(out) == text
+
+
+def test_env_gate(monkeypatch):
+    text = json.dumps(_docs(20))
+    monkeypatch.delenv("RESPONSE_FORMAT", raising=False)
+    out = _run(GcfResponseMiddleware(), _result(TextContent(type="text", text=text)))
+    assert _text(out) == text  # env not set -> unchanged
+
+    monkeypatch.setenv("RESPONSE_FORMAT", "gcf")
+    out = _run(GcfResponseMiddleware(), _result(TextContent(type="text", text=text)))
+    assert _text(out).startswith("GCF profile=generic")
+
+
+def test_non_json_text_unchanged():
+    result = _result(TextContent(type="text", text="a plain non-JSON message"))
+    out = _run(GcfResponseMiddleware(enabled=True), result)
+    assert _text(out) == "a plain non-JSON message"
+
+
+def test_multiple_content_blocks_unchanged():
+    text = json.dumps(_docs(20))
+    result = _result(
+        TextContent(type="text", text=text),
+        TextContent(type="text", text="second block"),
+    )
+
+    out = _run(GcfResponseMiddleware(enabled=True), result)
+
+    assert len(out.content) == 2
+    assert out.content[0].text == text  # not rewritten (would drop the second block)
+
+
+def test_encode_error_falls_back_to_json():
+    # 2**63 is outside GCF's canonical int64 domain, so encode_generic raises and
+    # the middleware returns the original JSON result rather than dropping the call.
+    data = {"seq": 2**63}
+    text = json.dumps(data)
+    result = _result(TextContent(type="text", text=text), structured_content=data)
+
+    out = _run(GcfResponseMiddleware(enabled=True), result)
+
+    assert _text(out) == text
+
+
+# --- fuzz: the safety invariant on arbitrary JSON ---
+
+# Characters that stress GCF's delimiter/quoting rules and unicode handling.
+_CHARS = "abc 0|,\"\\\n\t\r:{}[]<>é☕日本語—"
+
+
+def _rand_str(rng, lo=0, hi=12):
+    return "".join(rng.choice(_CHARS) for _ in range(rng.randint(lo, hi)))
+
+
+def _rand_scalar(rng):
+    kind = rng.randint(0, 5)
+    if kind == 0:
+        return rng.randint(-1_000_000, 1_000_000)
+    if kind == 1:
+        return rng.choice([True, False, None])
+    if kind == 2:
+        return round(rng.uniform(-1e6, 1e6), 4)
+    if kind == 3:
+        # occasionally an integer outside the int64 domain -> encode must decline safely
+        return rng.choice([2**63, -(2**63) - 1, 10**25])
+    return _rand_str(rng)
+
+
+def _rand_json(rng, depth=0):
+    if depth >= 4 or rng.random() < 0.35:
+        return _rand_scalar(rng)
+    kind = rng.randint(0, 2)
+    if kind == 0:
+        return [_rand_json(rng, depth + 1) for _ in range(rng.randint(0, 5))]
+    if kind == 1:
+        return {_rand_str(rng, 1, 8): _rand_json(rng, depth + 1) for _ in range(rng.randint(0, 5))}
+    # array of uniform records (GCF's favorable shape)
+    keys = [_rand_str(rng, 1, 6) for _ in range(rng.randint(1, 5))]
+    return [{k: _rand_json(rng, depth + 2) for k in keys} for _ in range(rng.randint(0, 8))]
+
+
+def test_fuzz_middleware_never_grows_corrupts_or_crashes():
+    rng = random.Random(20260815)
+    middleware = GcfResponseMiddleware(enabled=True)
+
+    for _ in range(5000):
+        payload = _rand_json(rng)
+        text = json.dumps(payload)
+        structured = payload if isinstance(payload, dict) else None
+        result = _result(TextContent(type="text", text=text), structured_content=structured)
+
+        out = _run(middleware, result)
+
+        # Always exactly one text block; never dropped or multiplied.
+        assert len(out.content) == 1
+        got = out.content[0].text
+
+        if got == text:
+            continue  # declined -> original JSON kept (always safe)
+
+        # Otherwise it MUST be a GCF wire that round-trips to the exact payload.
+        assert got.startswith("GCF profile=generic")
+        assert decode_generic(got) == payload