gcf-python 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

gcf/__init__.py

@@ -59,4 +59,4 @@ __all__ = [
     "encode_with_session",
 ]
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"

gcf/decode.py

@@ -34,6 +34,9 @@ def decode(input_text: str) -> Payload:
         raise DecodeError(f"invalid header, expected 'GCF ...' got {header!r}")
     _parse_header(header[4:], p)
 
+    if not p.tool:
+        raise DecodeError("header missing required 'tool' field")
+
     # Parse body: symbols and edges.
     symbols: list[Symbol] = []
     sym_by_id: dict[int, Symbol] = {}
@@ -48,6 +51,10 @@ def decode(input_text: str) -> Payload:
         # Group header.
         if line.startswith("## "):
             group = line[3:]
+            # Strip bracket suffix: "edges [200]" -> "edges"
+            bracket_idx = group.find(" [")
+            if bracket_idx >= 0:
+                group = group[:bracket_idx]
             in_edges = group == "edges"
             if not in_edges:
                 if group == "targets":

gcf/encode.py

@@ -17,17 +17,23 @@ def encode(p: Payload) -> str:
     """
     parts: list[str] = []
 
-    # Header line.
-    header = f"GCF tool={p.tool} budget={p.token_budget} tokens={p.tokens_used} symbols={len(p.symbols)}"
-    if p.pack_root:
-        header += f" pack_root={p.pack_root}"
-    parts.append(header)
-
     # Build symbol index for edge references.
     sym_index: dict[str, int] = {}
     for i, s in enumerate(p.symbols):
         sym_index[s.qualified_name] = i
 
+    # Count valid edges (both endpoints in symbol index).
+    valid_edges = sum(
+        1 for e in p.edges
+        if e.source in sym_index and e.target in sym_index
+    )
+
+    # Header line.
+    header = f"GCF tool={p.tool} budget={p.token_budget} tokens={p.tokens_used} symbols={len(p.symbols)} edges={valid_edges}"
+    if p.pack_root:
+        header += f" pack_root={p.pack_root}"
+    parts.append(header)
+
     # Group symbols by distance.
     groups = _group_by_distance(p.symbols)
     group_names = ["targets", "related", "extended"]
@@ -58,7 +64,7 @@ def encode(p: Payload) -> str:
             if e.status and e.status != "unchanged":
                 line += f" {e.status}"
             edge_lines.append(line)
-        parts.append("## edges")
+        parts.append(f"## edges [{len(edge_lines)}]")
         parts.extend(edge_lines)
 
     return "\n".join(parts) + "\n"

gcf/generic.py

@@ -18,6 +18,8 @@ def encode_generic(data: Any) -> str:
     Returns:
         GCF-formatted text string.
     """
+    if data is None or not isinstance(data, (dict, list)):
+        return str(data) if data is not None else "-"
     lines: list[str] = []
     _encode_value(data, lines, depth=0)
     return "\n".join(lines) + "\n" if lines else "\n"
@@ -33,15 +35,16 @@ def _encode_value(value: Any, lines: list[str], depth: int) -> None:
         lines.append(_indent(depth) + _format_value(value))
 
 
-def _encode_dict(d: dict, lines: list[str], depth: int) -> None:
+def _encode_dict(d: dict, lines: list[str], depth: int, name: str | None = None) -> None:
     """Encode a dict into key=value pairs with section headers for nested values."""
     prefix = _indent(depth)
+    if name is not None:
+        lines.append(f"{prefix}## {name}")
     for key, value in d.items():
         if isinstance(value, list):
             _encode_array(value, key, lines, depth)
         elif isinstance(value, dict):
-            lines.append(f"{prefix}## {key}")
-            _encode_dict(value, lines, depth + 1)
+            _encode_dict(value, lines, depth + 1, name=key)
         else:
             lines.append(f"{prefix}{key}={_format_value(value)}")
 
@@ -85,14 +88,12 @@ def _encode_tabular(items: list[dict], name: str, lines: list[str], depth: int)
 
         if nested_fields:
             lines.append(f"{prefix}@{i} {row_str}")
-            inner_prefix = _indent(depth + 1)
             for nk in nested_fields:
                 nv = item.get(nk)
                 if isinstance(nv, list):
                     _encode_array(nv, nk, lines, depth + 1)
                 elif isinstance(nv, dict):
-                    lines.append(f"{inner_prefix}## {nk}")
-                    _encode_dict(nv, lines, depth + 2)
+                    _encode_dict(nv, lines, depth + 1, name=nk)
         else:
             lines.append(f"{prefix}{row_str}")
 
@@ -141,7 +142,7 @@ def _format_value(value: Any) -> str:
         return str(value)
     s = str(value)
     if "|" in s or "\n" in s or s == "":
-        escaped = s.replace("\\", "\\\\").replace('"', '\\"')
+        escaped = s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
         return f'"{escaped}"'
     return s
 

gcf/session.py

@@ -77,20 +77,26 @@ def encode_with_session(p: Payload, sess: Session | None = None) -> str:
 
     parts: list[str] = []
 
+    # Build local ID mapping for this response.
+    local_index: dict[str, int] = {}
+    for i, s in enumerate(p.symbols):
+        local_index[s.qualified_name] = i
+
+    # Count valid edges.
+    valid_edges = sum(
+        1 for e in p.edges
+        if e.source in local_index and e.target in local_index
+    )
+
     # Header with session=true marker.
     header = (
         f"GCF tool={p.tool} budget={p.token_budget} tokens={p.tokens_used} "
-        f"symbols={len(p.symbols)} session=true"
+        f"symbols={len(p.symbols)} edges={valid_edges} session=true"
     )
     if p.pack_root:
         header += f" pack_root={p.pack_root}"
     parts.append(header)
 
-    # Build local ID mapping for this response.
-    local_index: dict[str, int] = {}
-    for i, s in enumerate(p.symbols):
-        local_index[s.qualified_name] = i
-
     # Track which symbols are new (need full declaration).
     new_symbols: list[Symbol] = []
 
@@ -122,7 +128,7 @@ def encode_with_session(p: Payload, sess: Session | None = None) -> str:
 
     # Edges section.
     if p.edges:
-        parts.append("## edges")
+        parts.append(f"## edges [{valid_edges}]")
         for e in p.edges:
             src_idx = local_index.get(e.source)
             tgt_idx = local_index.get(e.target)

{gcf_python-0.1.2.dist-info → gcf_python-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 0.1.2
+Version: 0.2.0
 Summary: Python implementation of GCF (Graph Compact Format): token-optimized wire format for LLM tool responses
 Project-URL: Homepage, https://github.com/blackwell-systems/gcf-python
 Project-URL: Documentation, https://blackwell-systems.github.io/gcf/
@@ -30,9 +30,11 @@ Description-Content-Type: text/markdown
 
 # gcf-python
 
-Python implementation of [GCF (Graph Compact Format)](https://github.com/blackwell-systems/gcf).
+Python implementation of [GCF (Graph Compact Format)](https://gcformat.com/) — the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
 
-**84% fewer tokens than JSON. 32% fewer than TOON. 100% LLM comprehension accuracy at 500 symbols, where JSON fails.**
+**79% fewer input tokens than JSON. 75% fewer output tokens. 52% smaller than TOON. 100% LLM comprehension at 500 symbols, where JSON fails at 66.7%.**
+
+Docs: [gcformat.com](https://gcformat.com/) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
 
 ## Install
 
@@ -40,7 +42,7 @@ Python implementation of [GCF (Graph Compact Format)](https://github.com/blackwe
 pip install gcf-python
 ```
 
-Zero dependencies. Pure Python. Python 3.9+. Includes CLI.
+Zero dependencies. Pure Python. Python 3.9+. Includes CLI. Don't want to change code? Use the [MCP proxy](https://github.com/blackwell-systems/gcf-proxy) for zero-code adoption.
 
 ## CLI
 
@@ -84,12 +86,12 @@ output = encode(p)
 
 Output:
 ```
-GCF tool=context_for_task budget=5000 tokens=1847 symbols=2
+GCF tool=context_for_task budget=5000 tokens=1847 symbols=2 edges=1
 ## targets
 @0 fn pkg.AuthMiddleware 0.78 lsp_resolved
 ## related
 @1 fn pkg.NewServer 0.54 lsp_resolved
-## edges
+## edges [1]
 @0<@1 calls
 ```
 
@@ -211,11 +213,16 @@ GCF wins on every dataset except deeply nested config (75 tokens on a 618-token
 
 Reproducible: [blackwell-systems/toon@gcf-comparison](https://github.com/blackwell-systems/toon/tree/gcf-comparison)
 
-## Other Implementations
+## Links
 
-- **Go**: [github.com/blackwell-systems/gcf-go](https://github.com/blackwell-systems/gcf-go)
-- **TypeScript**: [github.com/blackwell-systems/gcf-typescript](https://github.com/blackwell-systems/gcf-typescript)
-- **Specification**: [github.com/blackwell-systems/gcf](https://github.com/blackwell-systems/gcf)
+- [Documentation](https://gcformat.com/)
+- [Playground](https://gcformat.com/playground.html)
+- [Specification](https://github.com/blackwell-systems/gcf)
+- [Go library](https://github.com/blackwell-systems/gcf-go)
+- [TypeScript library](https://github.com/blackwell-systems/gcf-typescript)
+- [MCP Proxy](https://github.com/blackwell-systems/gcf-proxy) (zero-code adoption)
+- [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
+- [TOON benchmark fork](https://github.com/blackwell-systems/toon/tree/gcf-comparison)
 
 ## License
 

gcf_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+gcf/__init__.py,sha256=epW-CoQh3RBrnF3-lWSiPS-DI4HUlRRe8q9JeLPRxwE,1541
+gcf/cli.py,sha256=2hSTBqiYcn1_EgGXuO65MHiEGh0C4DRMvspTd2zUaso,4258
+gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
+gcf/decode.py,sha256=48G6XmBilGYl0-c_Xy7MX0iTwOxGW9bn3wC4UyNApc4,5465
+gcf/delta.py,sha256=xU0ujtSq1iF7yU8yk_WNQKh8iove-WUV_nKSuvW1XVk,1656
+gcf/encode.py,sha256=Oljb1r5b7SHmng1XYvcvuJMpaRfJVJ81VOyocPf_kAs,2915
+gcf/generic.py,sha256=xSXCufl4uK3xaDDPsKb4g5Mf0B-HVePzzwnwKYXJ8OU,5200
+gcf/session.py,sha256=4_ARRL06Tg2CI8D2eyi0V5nFphFAFMfOKBXYnAbI6Nk,4690
+gcf/types.py,sha256=AWm-LQoSqLHAYtEjcAxWQZqJ4JXqNreLUKO2mJFgNMA,1465
+gcf_python-0.2.0.dist-info/METADATA,sha256=2YETOadgxh76qeHmHYZKOcpAo-4HGLyBQBh3BC148cA,7929
+gcf_python-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gcf_python-0.2.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-0.2.0.dist-info/licenses/LICENSE,sha256=txSvg3E4LugiB7MOOTci6WKd6wMOrOJTvaITeFJ2SgU,1074
+gcf_python-0.2.0.dist-info/RECORD,,

gcf_python-0.1.2.dist-info/RECORD

@@ -1,14 +0,0 @@
-gcf/__init__.py,sha256=bhnoIK9Qk7tMgWX_3q6HFvE3w55yw5rw2jyFHx7Bqx8,1541
-gcf/cli.py,sha256=2hSTBqiYcn1_EgGXuO65MHiEGh0C4DRMvspTd2zUaso,4258
-gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
-gcf/decode.py,sha256=gkBW9fmcurQ9bfcDXbaCOWemMmljo_MiZMj3-1rYvsw,5198
-gcf/delta.py,sha256=xU0ujtSq1iF7yU8yk_WNQKh8iove-WUV_nKSuvW1XVk,1656
-gcf/encode.py,sha256=WZCRv1Vj2PDTYvBgv__2P8GHh8FapxfAZmt5zo0k9Jc,2700
-gcf/generic.py,sha256=N4rhf3JAdQHcWA9HEbTPxWnMfvdac6oZzQHQSnZdXdE,5105
-gcf/session.py,sha256=F8OTJCMRMCY7Yzcvd7aU8wlbER0LZAMUcB4W9kHeSq4,4508
-gcf/types.py,sha256=AWm-LQoSqLHAYtEjcAxWQZqJ4JXqNreLUKO2mJFgNMA,1465
-gcf_python-0.1.2.dist-info/METADATA,sha256=FumNV9D2FUZfkUor89SPotIgLTo2QXmUhT9RHZc4DYk,7320
-gcf_python-0.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-gcf_python-0.1.2.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
-gcf_python-0.1.2.dist-info/licenses/LICENSE,sha256=txSvg3E4LugiB7MOOTci6WKd6wMOrOJTvaITeFJ2SgU,1074
-gcf_python-0.1.2.dist-info/RECORD,,