gcf-python 2.5.3__py3-none-any.whl → 2.7.0__py3-none-any.whl

gcf/__init__.py

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

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,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/scalar.py

@@ -93,6 +93,15 @@ def format_scalar(v: Any, delimiter: str = "") -> str:
     if isinstance(v, bool):
         return "true" if v else "false"
     if isinstance(v, int) and not isinstance(v, bool):
+        # The encoder enforces the int64 domain (SPEC 2.3.2): a Python int is
+        # arbitrary-precision, so a host integer outside int64 is rejected here
+        # rather than emitted as a bare token the decoder would reject.
+        if v < -(2**63) or v > 2**63 - 1:
+            raise ValueError(
+                f"out_of_range: integer {v} is outside the canonical int64 "
+                "domain [-9223372036854775808, 9223372036854775807]; "
+                "model larger values as strings (SPEC 2.3.2)"
+            )
         return str(v)
     if isinstance(v, float):
         return format_number(v)
@@ -111,7 +120,12 @@ def format_number(f: float) -> str:
         # Negative zero canonicalizes to 0 (SPEC 2.3.1): -0.0 equals 0.0 by value.
         return "0"
     a = abs(f)
-    if 1e-6 <= a < 1e21:
+    # Plain decimal only below 2^53. Every double at or above 2^53 is integer-valued,
+    # so a plain rendering would emit a bare-integer token: indistinguishable from an
+    # int64 on the wire and beyond the binary64 safe-integer range (2^53-1), so a
+    # JavaScript decoder rejects it under its default policy. Exponent shape keeps bare
+    # tokens int64 and decimal/exponent tokens doubles (SPEC 2.3.1). Ints format above.
+    if 1e-6 <= a < 2**53:
         # Use repr for shortest round-trippable form.
         s = repr(f)
         # If repr chose scientific notation, convert to plain decimal.
@@ -165,12 +179,20 @@ def parse_scalar(s: str, tabular_context: bool = False) -> Any:
     if s == "false":
         return False
     if _JSON_NUMBER_RE.match(s):
+        # Token shape follows domain (SPEC 2.3.2): a bare-integer literal (no
+        # fraction, no exponent) is an int64-domain integer parsed exactly, not
+        # routed through float(); a decimal or exponent literal is a double.
+        if "." not in s and "e" not in s and "E" not in s:
+            n = int(s)
+            if n < -(2**63) or n > 2**63 - 1:
+                raise ValueError(
+                    f"out_of_range: integer {s} is outside the canonical int64 "
+                    "domain [-9223372036854775808, 9223372036854775807]; "
+                    "model larger values as strings (SPEC 2.3.2)"
+                )
+            return n
         try:
-            f = float(s)
-            if "." not in s and "e" not in s and "E" not in s:
-                if abs(f) <= 2**53:
-                    return int(f)
-            return f
+            return float(s)
         except ValueError:
             pass
     return s

{gcf_python-2.5.3.dist-info → gcf_python-2.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: gcf-python
-Version: 2.5.3
+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.5.3.dist-info → gcf_python-2.7.0.dist-info}/RECORD

@@ -1,22 +1,23 @@
-gcf/__init__.py,sha256=dZkdcjbG-dcolg_7TBROjRq3opftDGU423ankMIOhyA,2616
+gcf/__init__.py,sha256=qRPchyWVeUYtuubktzAg96l-O0CKI3gMGH1CSm8aqvw,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=Q0qxk87VcCjwH2H8retxyTmieaIGZS7Q8aDsDPQa8sw,4554
 gcf/generic.py,sha256=1c53utF2GcD8lS_wks2opQw08hMz4KGL-7C8g7JB5bA,21577
 gcf/generic_delta.py,sha256=5KSUT_QUeH7OILLWfu9JveaXRSrqRIi3c6E8WjlgC4Q,18785
 gcf/keyed_map.py,sha256=qCwhehXB1FQ2iYCPhcvXOqGwrVqdXhGYZGxv56CSUgc,3644
 gcf/packroot.py,sha256=0rZY7TEVcLzA8XhoIOc6_g9lbRCn-MUr54YTRVhzsO4,2019
-gcf/scalar.py,sha256=WLNJuktGRPZ-kLUm2SLlBcJJBFZfApoyh_MDRrPDCZk,10035
+gcf/scalar.py,sha256=fQvfYLuJVbrbB46fd0V1BPDdVaxdthaOsrZJ2B8l2Gk,11499
 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.5.3.dist-info/METADATA,sha256=SEVTaCwxPj9U8h_zp2vzfNxiwMYvThrwrnioG5v5L1s,16165
-gcf_python-2.5.3.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-gcf_python-2.5.3.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
-gcf_python-2.5.3.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
-gcf_python-2.5.3.dist-info/RECORD,,
+gcf_python-2.7.0.dist-info/METADATA,sha256=AI5njTxmfrya82omvWIRaU8yzDYuAujw8irf2ENQu6s,17107
+gcf_python-2.7.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+gcf_python-2.7.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-2.7.0.dist-info/licenses/LICENSE,sha256=2Fit9wnaIe--RMSAgyQqxC5hfZTyZqn4fIdBtp9qPDw,1072
+gcf_python-2.7.0.dist-info/RECORD,,

{gcf_python-2.5.3.dist-info → gcf_python-2.7.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any