gcf-python 2.6.0__py3-none-any.whl → 2.7.1__py3-none-any.whl

gcf/__init__.py

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

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/fastmcp.py

@@ -0,0 +1,142 @@
+"""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).
+- **Never-grow** — GCF is used only when the wire is actually smaller than the
+  JSON it would replace; a small result is never enlarged.
+- **Lossless and fail-safe** — the wire must decode back to the same value, and
+  on any encoding error the original result is returned, so a tool call is never
+  grown, dropped, or garbled 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
+
+        # _json_payload guarantees exactly one text block, so this is the JSON text
+        # the client would otherwise receive.
+        original = result.content[0].text
+
+        try:
+            wire = encode_generic(payload)
+            # Never-grow: only replace the JSON when GCF is actually smaller, so a
+            # small result is never enlarged.
+            if len(wire) >= len(original):
+                return result
+            # 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.6.0.dist-info → gcf_python-2.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gcf-python
-Version: 2.6.0
+Version: 2.7.1
 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 281 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. Current versions: Go v1.7.1, TypeScript v2.6.1, Python v2.7.0, Rust v3.0.1, Swift v2.7.1, Kotlin v2.6.1, .NET v0.2.1. Cross-language conformance verified across all seven SDKs.
 
 ## Adopted by
 

{gcf_python-2.6.0.dist-info → gcf_python-2.7.1.dist-info}/RECORD

@@ -1,11 +1,12 @@
-gcf/__init__.py,sha256=QRGOX87aJR1RXZktNnzRgYbqM7Fp9i1ZPIAf97wE-o8,2616
+gcf/__init__.py,sha256=uRYqyGTFSlmnfoj0hh79AZ_KhxiCgZgJt_v-okiK4_k,2616
 gcf/__main__.py,sha256=EpvBz1yc8H0D5OJ1zy2tYke-kRzvudKa4DEbfeW14ao,71
 gcf/cli.py,sha256=UEe1CAZn-rKGNIo_ap8-oez3ucl6DSRbsdv6RDnzygY,5256
 gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
 gcf/decode.py,sha256=TP58_7UBhfeI0o9zpNgtQvAnLQGhNt0RaUjku7Ke75A,7162
-gcf/decode_generic.py,sha256=OTNhryeAFfE5izpP6dD0DtBzcC_Jht1-vLg51gjnZ28,30510
+gcf/decode_generic.py,sha256=X59J2tV_ybZdWupVIVRtfLiqdxko2wfIn78Kkm5lNls,31170
 gcf/delta.py,sha256=oviQ9WsDRYXPXE8bw6SFutmzMRIvu-U_Zzw-39Nd5Ic,8053
 gcf/encode.py,sha256=OYGDyF3oP2I8Y2PrPL_5yDVURqB0mghtqlOGyDEd-Fs,4081
+gcf/fastmcp.py,sha256=cwIX77DhA96rMrelQcrlAlFXGQ4FDNModa4rSGlGN7I,5139
 gcf/generic.py,sha256=1c53utF2GcD8lS_wks2opQw08hMz4KGL-7C8g7JB5bA,21577
 gcf/generic_delta.py,sha256=5KSUT_QUeH7OILLWfu9JveaXRSrqRIi3c6E8WjlgC4Q,18785
 gcf/keyed_map.py,sha256=qCwhehXB1FQ2iYCPhcvXOqGwrVqdXhGYZGxv56CSUgc,3644
@@ -15,8 +16,8 @@ gcf/session.py,sha256=rPqR4xsHKpi_G37t1ODwkTUdHhVAGa3Uig8F60h34Ms,5335
 gcf/stream.py,sha256=3eyzmLMZPyEGC1MS9pujxio2x_t7rCL-eNuJ4DjYkaA,5938
 gcf/stream_generic.py,sha256=h2mJ-jI-c1H2L0uoQVhrvDc7uJEcOwS1MB51k4SCPNM,5775
 gcf/types.py,sha256=AWm-LQoSqLHAYtEjcAxWQZqJ4JXqNreLUKO2mJFgNMA,1465
-gcf_python-2.6.0.dist-info/METADATA,sha256=0iJSJoi00y_XFo6x3cM7lq5mp9JuShcf3VFfCYYbov4,16165
-gcf_python-2.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-gcf_python-2.6.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
-gcf_python-2.6.0.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
-gcf_python-2.6.0.dist-info/RECORD,,
+gcf_python-2.7.1.dist-info/METADATA,sha256=FYQP8X41OUkaB4Bwyvl0rvUCmlMsdTfINUDiRqQMcLM,17107
+gcf_python-2.7.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+gcf_python-2.7.1.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-2.7.1.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
+gcf_python-2.7.1.dist-info/RECORD,,