gcf-python 0.1.3__tar.gz → 0.2.0__tar.gz

{gcf_python-0.1.3 → gcf_python-0.2.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v0.2.0 (2026-06-05)
+
+- **Breaking**: `encode()` now emits `edges=N` in header line
+- **Breaking**: `encode()` now emits `## edges [N]` section header (was `## edges`)
+- `decode()` updated to parse `## edges [N]` format (strips bracket suffix)
+- Session encoder updated to emit new edge count format
+
+## v0.1.3 (2026-06-04)
+
+- Docs: update README for PyPI discoverability (gcformat.com, proxy, vs-toon links)
+- Fix: decoder rejects headers missing required `tool` field (conformance)
+- Fix: escape newlines as `\n` in quoted strings in `encode_generic`
+
 ## v0.1.2 (2026-06-04)
 
 - Fix: escape `"` inside quoted strings in `encode_generic`

{gcf_python-0.1.3 → gcf_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 0.1.3
+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/
@@ -86,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
 ```
 

{gcf_python-0.1.3 → gcf_python-0.2.0}/README.md

@@ -61,12 +61,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
 ```
 

{gcf_python-0.1.3 → gcf_python-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gcf-python"
-version = "0.1.3"
+version = "0.2.0"
 description = "Python implementation of GCF (Graph Compact Format): token-optimized wire format for LLM tool responses"
 readme = "README.md"
 license = {text = "MIT"}

{gcf_python-0.1.3 → gcf_python-0.2.0}/src/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_python-0.1.3 → gcf_python-0.2.0}/src/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_python-0.1.3 → gcf_python-0.2.0}/src/gcf/generic.py

@@ -142,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_python-0.1.3 → gcf_python-0.2.0}/src/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.3 → gcf_python-0.2.0}/tests/test_decode.py

@@ -13,7 +13,7 @@ def test_decode_basic_payload():
         "@0 fn pkg.AuthMiddleware 0.78 lsp_resolved\n"
         "## related\n"
         "@1 fn pkg.NewServer 0.54 lsp_resolved\n"
-        "## edges\n"
+        "## edges [1]\n"
         "@0<@1 calls\n"
     )
 
@@ -93,7 +93,7 @@ def test_decode_edge_with_status():
         "## targets\n"
         "@0 fn a.A 0.90 x\n"
         "@1 fn b.B 0.80 x\n"
-        "## edges\n"
+        "## edges [1]\n"
         "@0<@1 calls added\n"
     )
     p = decode(input_text)
@@ -171,7 +171,7 @@ def test_decode_edge_missing_separator():
         "## targets\n"
         "@0 fn a.A 0.90 x\n"
         "@1 fn b.B 0.80 x\n"
-        "## edges\n"
+        "## edges [1]\n"
         "@0@1 calls\n"
     )
     with pytest.raises(DecodeError, match="missing '<' separator"):
@@ -184,7 +184,7 @@ def test_decode_edge_unknown_symbol():
         "GCF tool=test budget=100 tokens=50 symbols=1\n"
         "## targets\n"
         "@0 fn a.A 0.90 x\n"
-        "## edges\n"
+        "## edges [1]\n"
         "@0<@99 calls\n"
     )
     with pytest.raises(DecodeError, match="unknown symbol id"):

{gcf_python-0.1.3 → gcf_python-0.2.0}/tests/test_encode.py

@@ -32,12 +32,12 @@ def test_encode_basic_payload():
 
     output = encode(p)
     expected = (
-        "GCF tool=context_for_task budget=5000 tokens=1847 symbols=2\n"
+        "GCF tool=context_for_task budget=5000 tokens=1847 symbols=2 edges=1\n"
         "## targets\n"
         "@0 fn pkg.AuthMiddleware 0.78 lsp_resolved\n"
         "## related\n"
         "@1 fn pkg.NewServer 0.54 lsp_resolved\n"
-        "## edges\n"
+        "## edges [1]\n"
         "@0<@1 calls\n"
     )
     assert output == expected
@@ -175,8 +175,9 @@ def test_encode_skips_edges_with_missing_symbols():
     )
     output = encode(p)
     # Section header is emitted (matches Go), but no edge lines beneath it
-    assert "## edges" in output
-    lines_after_edges = output.split("## edges\n")[1]
+    assert "## edges [0]" in output
+    assert "edges=0" in output
+    lines_after_edges = output.split("## edges [0]\n")[1]
     assert lines_after_edges.strip() == ""
 
 
@@ -184,4 +185,4 @@ def test_encode_empty_payload():
     """Empty payload produces only header."""
     p = Payload(tool="test", token_budget=100, tokens_used=0)
     output = encode(p)
-    assert output == "GCF tool=test budget=100 tokens=0 symbols=0\n"
+    assert output == "GCF tool=test budget=100 tokens=0 symbols=0 edges=0\n"