gcf-python 0.5.1__py3-none-any.whl → 1.0.1__py3-none-any.whl

gcf/__init__.py

@@ -65,4 +65,4 @@ __all__ = [
     "encode_with_session",
 ]
 
-__version__ = "0.1.3"
+__version__ = "1.0.0"

gcf/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m gcf`."""
+
+from .cli import main
+
+main()

gcf/cli.py

@@ -5,19 +5,25 @@ import sys
 
 from .decode import decode
 from .encode import encode
+from .decode_generic import decode_generic
+from .generic import encode_generic
 from .types import Edge, Payload, Symbol
 
 USAGE = """gcf - token-optimized wire format for LLM tool responses
 
 Usage:
-  gcf encode [file]    Encode JSON payload to GCF (stdin if no file)
-  gcf decode [file]    Decode GCF text to JSON (stdin if no file)
-  gcf stats  [file]    Compare token counts: JSON vs GCF (stdin if no file)
-  gcf version          Print version
+  gcf encode          [file]  Encode JSON graph payload to GCF (stdin if no file)
+  gcf decode          [file]  Decode GCF graph text to JSON (stdin if no file)
+  gcf encode-generic  [file]  Encode JSON to GCF generic profile (stdin if no file)
+  gcf decode-generic  [file]  Decode GCF generic text to JSON (stdin if no file)
+  gcf stats           [file]  Compare token counts: JSON vs GCF (stdin if no file)
+  gcf version                 Print version
 
 Examples:
   gcf encode < payload.json
   gcf decode < payload.gcf
+  echo '{"name":"Alice"}' | gcf encode-generic
+  echo 'GCF profile=generic\\nname=Alice' | gcf decode-generic
   gcf stats payload.json
 """
 
@@ -37,11 +43,18 @@ def main() -> None:
     elif cmd == "decode":
         data = _read_input(file_args)
         _do_decode(data)
+    elif cmd == "encode-generic":
+        data = _read_input(file_args)
+        _do_encode_generic(data)
+    elif cmd == "decode-generic":
+        data = _read_input(file_args)
+        _do_decode_generic(data)
     elif cmd == "stats":
         data = _read_input(file_args)
         _do_stats(data)
     elif cmd == "version":
-        print("gcf 0.1.0")
+        from . import __version__
+        print(f"gcf {__version__}")
     else:
         print(f"unknown command: {cmd}\n", file=sys.stderr)
         print(USAGE, file=sys.stderr, end="")
@@ -115,6 +128,20 @@ def _payload_to_json(p: Payload) -> str:
     return json.dumps(obj, indent=2)
 
 
+def _do_encode_generic(data: str) -> None:
+    try:
+        obj = json.loads(data)
+    except json.JSONDecodeError as e:
+        print(f"error: invalid JSON: {e}", file=sys.stderr)
+        sys.exit(1)
+    print(encode_generic(obj), end="")
+
+
+def _do_decode_generic(data: str) -> None:
+    result = decode_generic(data)
+    print(json.dumps(result))
+
+
 def _do_encode(data: str) -> None:
     try:
         p = _payload_from_json(data)

gcf/decode.py

@@ -35,7 +35,11 @@ def decode(input_text: str) -> Payload:
     _parse_header(header[4:], p)
 
     if not p.tool:
-        raise DecodeError("header missing required 'tool' field")
+        raise DecodeError("missing_tool: header missing required 'tool' field")
+
+    # Detect delta mode.
+    is_delta = "delta=true" in header
+    valid_delta_sections = {"removed", "added", "edges_removed", "edges_added"}
 
     # Parse body: symbols and edges.
     symbols: list[Symbol] = []
@@ -48,6 +52,10 @@ def decode(input_text: str) -> Payload:
         if not line:
             continue
 
+        # Skip ##! summary trailer.
+        if line.startswith("##! "):
+            continue
+
         # Group header.
         if line.startswith("## "):
             group = line[3:]
@@ -55,6 +63,8 @@ def decode(input_text: str) -> Payload:
             bracket_idx = group.find(" [")
             if bracket_idx >= 0:
                 group = group[:bracket_idx]
+            if is_delta and group not in valid_delta_sections:
+                raise DecodeError(f"malformed_delta: invalid delta section {group!r}")
             in_edges = group == "edges"
             if not in_edges:
                 if group == "targets":
@@ -113,19 +123,19 @@ def _parse_header(fields: str, p: Payload) -> None:
 def _parse_symbol_line(line: str, distance: int) -> tuple[Symbol, int]:
     """Parse a symbol line into a Symbol and its local ID."""
     if not line.startswith("@"):
-        raise DecodeError(f"expected symbol line starting with @, got {line!r}")
+        raise DecodeError(f"invalid_node_line: expected symbol line starting with @, got {line!r}")
 
     parts = line.split()
     if len(parts) < 5:
         raise DecodeError(
-            f"symbol line needs at least 5 fields, got {len(parts)} in {line!r}"
+            f"invalid_node_line: symbol line needs at least 5 fields, got {len(parts)} in {line!r}"
         )
 
     id_str = parts[0][1:]  # strip @
     try:
         sym_id = int(id_str)
     except ValueError as e:
-        raise DecodeError(f"invalid symbol id {id_str!r}: {e}") from e
+        raise DecodeError(f"invalid_symbol_id: invalid symbol id {id_str!r}: {e}") from e
 
     kind = parts[1]
     kind = KIND_EXPAND.get(kind, kind)
@@ -135,7 +145,7 @@ def _parse_symbol_line(line: str, distance: int) -> tuple[Symbol, int]:
     try:
         score = float(parts[3])
     except ValueError as e:
-        raise DecodeError(f"invalid score {parts[3]!r}: {e}") from e
+        raise DecodeError(f"invalid_score: invalid score {parts[3]!r}: {e}") from e
 
     provenance = parts[4]
 
@@ -157,7 +167,7 @@ def _parse_edge_line(line: str, sym_by_id: dict[int, Symbol]) -> Edge:
     ref = parts[0]
     lt_idx = ref.find("<")
     if lt_idx < 0:
-        raise DecodeError(f"edge line missing '<' separator in {ref!r}")
+        raise DecodeError(f"invalid_edge_syntax: edge line missing '<' separator in {ref!r}")
 
     target_id_str = ref[1:lt_idx]  # strip leading @
     source_id_str = ref[lt_idx + 2:]  # strip <@
@@ -176,7 +186,7 @@ def _parse_edge_line(line: str, sym_by_id: dict[int, Symbol]) -> Edge:
     source_sym = sym_by_id.get(source_id)
     if target_sym is None or source_sym is None:
         raise DecodeError(
-            f"edge references unknown symbol id(s): target={target_id} source={source_id}"
+            f"unknown_edge_reference: edge references unknown symbol id(s): target={target_id} source={source_id}"
         )
 
     edge_type = parts[1]