gcf-python 0.1.0__py3-none-any.whl

gcf/__init__.py

@@ -0,0 +1,60 @@
+"""GCF (Graph Compact Format): token-optimized wire format for LLM tool responses.
+
+84% fewer tokens than JSON. 32% fewer than TOON. 100% LLM comprehension accuracy.
+
+Encode a payload:
+
+    from gcf import encode, Payload, Symbol
+
+    p = Payload(
+        tool="context_for_task",
+        token_budget=5000,
+        tokens_used=1847,
+        symbols=[Symbol(qualified_name="pkg.Func", kind="function", score=0.9, provenance="lsp_resolved")],
+    )
+    output = encode(p)
+
+Decode a payload:
+
+    from gcf import decode
+    p = decode(input_text)
+
+Session deduplication:
+
+    from gcf import encode_with_session, Session
+    sess = Session()
+    out1 = encode_with_session(payload1, sess)  # full declarations
+    out2 = encode_with_session(payload2, sess)  # reused symbols as bare refs
+
+Delta encoding:
+
+    from gcf import encode_delta, DeltaPayload
+    out = encode_delta(DeltaPayload(...))
+
+Specification: https://github.com/blackwell-systems/gcf
+"""
+
+from .constants import KIND_ABBREV, KIND_EXPAND
+from .decode import DecodeError, decode
+from .delta import encode_delta
+from .encode import encode
+from .session import Session, encode_with_session
+from .types import Components, DeltaPayload, Edge, Payload, Symbol
+
+__all__ = [
+    "Components",
+    "DecodeError",
+    "DeltaPayload",
+    "Edge",
+    "KIND_ABBREV",
+    "KIND_EXPAND",
+    "Payload",
+    "Session",
+    "Symbol",
+    "decode",
+    "encode",
+    "encode_delta",
+    "encode_with_session",
+]
+
+__version__ = "0.1.0"

gcf/cli.py

@@ -0,0 +1,155 @@
+"""GCF command-line interface: encode, decode, stats."""
+
+import json
+import sys
+
+from .decode import decode
+from .encode import encode
+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
+
+Examples:
+  gcf encode < payload.json
+  gcf decode < payload.gcf
+  gcf stats payload.json
+"""
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(USAGE, end="")
+        sys.exit(0 if args else 1)
+
+    cmd = args[0]
+    file_args = args[1:]
+
+    if cmd == "encode":
+        data = _read_input(file_args)
+        _do_encode(data)
+    elif cmd == "decode":
+        data = _read_input(file_args)
+        _do_decode(data)
+    elif cmd == "stats":
+        data = _read_input(file_args)
+        _do_stats(data)
+    elif cmd == "version":
+        print("gcf 0.1.0")
+    else:
+        print(f"unknown command: {cmd}\n", file=sys.stderr)
+        print(USAGE, file=sys.stderr, end="")
+        sys.exit(1)
+
+
+def _read_input(args: list[str]) -> str:
+    if args and args[0] != "-":
+        with open(args[0]) as f:
+            return f.read()
+    return sys.stdin.read()
+
+
+def _payload_from_json(data: str) -> Payload:
+    obj = json.loads(data)
+    symbols = [
+        Symbol(
+            qualified_name=s["qualifiedName"],
+            kind=s["kind"],
+            score=s["score"],
+            provenance=s["provenance"],
+            distance=s.get("distance", 0),
+        )
+        for s in obj.get("symbols", [])
+    ]
+    edges = [
+        Edge(
+            source=e["source"],
+            target=e["target"],
+            edge_type=e["edgeType"],
+            status=e.get("status", ""),
+        )
+        for e in obj.get("edges", [])
+    ]
+    return Payload(
+        tool=obj.get("tool", ""),
+        token_budget=obj.get("tokenBudget", 0),
+        tokens_used=obj.get("tokensUsed", 0),
+        pack_root=obj.get("packRoot", ""),
+        symbols=symbols,
+        edges=edges,
+    )
+
+
+def _payload_to_json(p: Payload) -> str:
+    obj = {
+        "tool": p.tool,
+        "tokensUsed": p.tokens_used,
+        "tokenBudget": p.token_budget,
+        "packRoot": p.pack_root,
+        "symbols": [
+            {
+                "qualifiedName": s.qualified_name,
+                "kind": s.kind,
+                "score": s.score,
+                "provenance": s.provenance,
+                "distance": s.distance,
+            }
+            for s in p.symbols
+        ],
+        "edges": [
+            {
+                "source": e.source,
+                "target": e.target,
+                "edgeType": e.edge_type,
+                **({"status": e.status} if e.status else {}),
+            }
+            for e in p.edges
+        ],
+    }
+    return json.dumps(obj, indent=2)
+
+
+def _do_encode(data: str) -> None:
+    try:
+        p = _payload_from_json(data)
+    except (json.JSONDecodeError, KeyError, TypeError) as e:
+        print(f"error: invalid JSON: {e}", file=sys.stderr)
+        sys.exit(1)
+    print(encode(p), end="")
+
+
+def _do_decode(data: str) -> None:
+    p = decode(data)
+    print(_payload_to_json(p))
+
+
+def _do_stats(data: str) -> None:
+    try:
+        p = _payload_from_json(data)
+    except (json.JSONDecodeError, KeyError, TypeError) as e:
+        print(f"error: invalid JSON: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    gcf_output = encode(p)
+    json_tokens = len(data.strip()) // 4
+    gcf_tokens = len(gcf_output.strip()) // 4
+
+    savings = 0.0
+    if json_tokens > 0:
+        savings = 100.0 * (1.0 - gcf_tokens / json_tokens)
+
+    bar_width = 30
+    json_bar = "█" * bar_width
+    gcf_filled = (gcf_tokens * bar_width) // json_tokens if json_tokens > 0 else 0
+    gcf_bar = "█" * gcf_filled + "░" * (bar_width - gcf_filled)
+
+    print(f"Payload: {len(p.symbols)} symbols, {len(p.edges)} edges\n")
+    print(f"  JSON  {json_bar}  {json_tokens} tokens")
+    print(f"  GCF   {gcf_bar}  {gcf_tokens} tokens")
+    print(f"\n  Savings: {savings:.0f}% fewer tokens with GCF")

gcf/constants.py

@@ -0,0 +1,24 @@
+"""Kind abbreviation mappings for GCF encoding/decoding."""
+
+# Maps full kind names to short GCF abbreviations.
+KIND_ABBREV: dict[str, str] = {
+    "function": "fn",
+    "type": "type",
+    "method": "method",
+    "interface": "iface",
+    "var": "var",
+    "const": "const",
+    "resource": "resource",
+    "table": "table",
+    "class": "class",
+    "selector": "selector",
+    "field": "field",
+    "route_handler": "route",
+    "external": "ext",
+    "file": "file",
+    "package": "pkg",
+    "service": "svc",
+}
+
+# Maps short GCF abbreviations to full kind names.
+KIND_EXPAND: dict[str, str] = {v: k for k, v in KIND_ABBREV.items()}

gcf/decode.py

@@ -0,0 +1,181 @@
+"""GCF decoder: parses GCF text back into a Payload."""
+
+from .constants import KIND_EXPAND
+from .types import Edge, Payload, Symbol
+
+
+class DecodeError(Exception):
+    """Raised when GCF text cannot be parsed."""
+
+
+def decode(input_text: str) -> Payload:
+    """Parse GCF text back into a Payload.
+
+    Args:
+        input_text: GCF-formatted text string.
+
+    Returns:
+        Parsed Payload.
+
+    Raises:
+        DecodeError: If the input is not valid GCF.
+    """
+    lines = input_text.split("\n")
+    if not lines:
+        raise DecodeError("empty input")
+
+    p = Payload()
+
+    # Parse header.
+    header = lines[0]
+    if not header.startswith("GCF "):
+        raise DecodeError(f"invalid header, expected 'GCF ...' got {header!r}")
+    _parse_header(header[4:], p)
+
+    # Parse body: symbols and edges.
+    symbols: list[Symbol] = []
+    sym_by_id: dict[int, Symbol] = {}
+    current_distance = 0
+    in_edges = False
+
+    for line in lines[1:]:
+        line = line.rstrip("\r")
+        if not line:
+            continue
+
+        # Group header.
+        if line.startswith("## "):
+            group = line[3:]
+            in_edges = group == "edges"
+            if not in_edges:
+                if group == "targets":
+                    current_distance = 0
+                elif group == "related":
+                    current_distance = 1
+                elif group == "extended":
+                    current_distance = 2
+                elif group.startswith("distance_"):
+                    try:
+                        current_distance = int(group[9:])
+                    except ValueError:
+                        pass
+            continue
+
+        # Comment.
+        if line.startswith("# "):
+            continue
+
+        if in_edges:
+            edge = _parse_edge_line(line, sym_by_id)
+            p.edges.append(edge)
+        else:
+            sym, sym_id = _parse_symbol_line(line, current_distance)
+            symbols.append(sym)
+            sym_by_id[sym_id] = sym
+
+    p.symbols = symbols
+    return p
+
+
+def _parse_header(fields: str, p: Payload) -> None:
+    """Parse header key=value pairs into the payload."""
+    for part in fields.split():
+        kv = part.split("=", 1)
+        if len(kv) != 2:
+            continue
+        key, value = kv
+        if key == "tool":
+            p.tool = value
+        elif key == "budget":
+            try:
+                p.token_budget = int(value)
+            except ValueError as e:
+                raise DecodeError(f"invalid budget {value!r}: {e}") from e
+        elif key == "tokens":
+            try:
+                p.tokens_used = int(value)
+            except ValueError as e:
+                raise DecodeError(f"invalid tokens {value!r}: {e}") from e
+        elif key == "pack_root":
+            p.pack_root = value
+        # "symbols" is informational, reconstructed from parsed symbols.
+
+
+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}")
+
+    parts = line.split()
+    if len(parts) < 5:
+        raise DecodeError(
+            f"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
+
+    kind = parts[1]
+    kind = KIND_EXPAND.get(kind, kind)
+
+    qname = parts[2]
+
+    try:
+        score = float(parts[3])
+    except ValueError as e:
+        raise DecodeError(f"invalid score {parts[3]!r}: {e}") from e
+
+    provenance = parts[4]
+
+    return Symbol(
+        qualified_name=qname,
+        kind=kind,
+        score=score,
+        provenance=provenance,
+        distance=distance,
+    ), sym_id
+
+
+def _parse_edge_line(line: str, sym_by_id: dict[int, Symbol]) -> Edge:
+    """Parse an edge line into an Edge."""
+    parts = line.split()
+    if len(parts) < 2:
+        raise DecodeError(f"edge line needs at least 2 fields, got {line!r}")
+
+    ref = parts[0]
+    lt_idx = ref.find("<")
+    if lt_idx < 0:
+        raise DecodeError(f"edge line missing '<' separator in {ref!r}")
+
+    target_id_str = ref[1:lt_idx]  # strip leading @
+    source_id_str = ref[lt_idx + 2:]  # strip <@
+
+    try:
+        target_id = int(target_id_str)
+    except ValueError as e:
+        raise DecodeError(f"invalid target id {target_id_str!r}: {e}") from e
+
+    try:
+        source_id = int(source_id_str)
+    except ValueError as e:
+        raise DecodeError(f"invalid source id {source_id_str!r}: {e}") from e
+
+    target_sym = sym_by_id.get(target_id)
+    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}"
+        )
+
+    edge_type = parts[1]
+    status = parts[2] if len(parts) >= 3 else ""
+
+    return Edge(
+        source=source_sym.qualified_name,
+        target=target_sym.qualified_name,
+        edge_type=edge_type,
+        status=status,
+    )

gcf/delta.py

@@ -0,0 +1,54 @@
+"""GCF delta encoding: only added/removed symbols for incremental delivery."""
+
+from .constants import KIND_ABBREV
+from .types import DeltaPayload
+
+
+def encode_delta(d: DeltaPayload) -> str:
+    """Encode a DeltaPayload into GCF delta format.
+
+    Args:
+        d: The delta payload to encode.
+
+    Returns:
+        GCF delta-formatted text string.
+    """
+    parts: list[str] = []
+
+    # Header.
+    savings = 0.0
+    if d.full_tokens > 0:
+        savings = 100.0 * (1.0 - d.delta_tokens / d.full_tokens)
+
+    parts.append(
+        f"GCF tool={d.tool} delta=true base_root={d.base_root} "
+        f"new_root={d.new_root} tokens={d.delta_tokens} savings={savings:.0f}%"
+    )
+
+    # Removed symbols: short references (consumer already has the full declaration).
+    if d.removed:
+        parts.append("## removed")
+        for s in d.removed:
+            kind = KIND_ABBREV.get(s.kind, s.kind)
+            parts.append(f"{kind} {s.qualified_name}")
+
+    # Added symbols: full declarations (consumer doesn't have these).
+    if d.added:
+        parts.append("## added")
+        for i, s in enumerate(d.added):
+            kind = KIND_ABBREV.get(s.kind, s.kind)
+            parts.append(f"@{i} {kind} {s.qualified_name} {s.score:.2f} {s.provenance}")
+
+    # Removed edges.
+    if d.removed_edges:
+        parts.append("## edges_removed")
+        for e in d.removed_edges:
+            parts.append(f"{e.source} -> {e.target} {e.edge_type}")
+
+    # Added edges.
+    if d.added_edges:
+        parts.append("## edges_added")
+        for e in d.added_edges:
+            parts.append(f"{e.source} -> {e.target} {e.edge_type}")
+
+    return "\n".join(parts) + "\n"

gcf/encode.py

@@ -0,0 +1,86 @@
+"""GCF encoder: serializes Payload into GCF text format."""
+
+from .constants import KIND_ABBREV
+from .types import Payload, Symbol
+
+
+def encode(p: Payload) -> str:
+    """Encode a Payload into GCF text format.
+
+    Args:
+        p: The payload to encode.
+
+    Returns:
+        GCF-formatted text string.
+    """
+    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
+
+    # Group symbols by distance.
+    groups = _group_by_distance(p.symbols)
+    group_names = ["targets", "related", "extended"]
+
+    for g_distance, g_symbols in groups:
+        if not g_symbols:
+            continue
+        if g_distance < len(group_names):
+            name = group_names[g_distance]
+        else:
+            name = f"distance_{g_distance}"
+        parts.append(f"## {name}")
+
+        for s in g_symbols:
+            idx = sym_index[s.qualified_name]
+            kind = KIND_ABBREV.get(s.kind, s.kind)
+            parts.append(f"@{idx} {kind} {s.qualified_name} {s.score:.2f} {s.provenance}")
+
+    # Edges section.
+    if p.edges:
+        edge_lines: list[str] = []
+        for e in p.edges:
+            src_idx = sym_index.get(e.source)
+            tgt_idx = sym_index.get(e.target)
+            if src_idx is None or tgt_idx is None:
+                continue
+            line = f"@{tgt_idx}<@{src_idx} {e.edge_type}"
+            if e.status and e.status != "unchanged":
+                line += f" {e.status}"
+            edge_lines.append(line)
+        parts.append("## edges")
+        parts.extend(edge_lines)
+
+    return "\n".join(parts) + "\n"
+
+
+def _group_by_distance(symbols: list[Symbol]) -> list[tuple[int, list[Symbol]]]:
+    """Group symbols by distance, preserving order."""
+    if not symbols:
+        return []
+
+    groups: list[tuple[int, list[Symbol]]] = []
+    current_distance: int | None = None
+    current_symbols: list[Symbol] = []
+
+    for s in symbols:
+        if current_distance is None or current_distance != s.distance:
+            if current_symbols:
+                groups.append((current_distance, current_symbols))  # type: ignore[arg-type]
+            current_distance = s.distance
+            current_symbols = [s]
+        else:
+            current_symbols.append(s)
+
+    if current_symbols:
+        groups.append((current_distance, current_symbols))  # type: ignore[arg-type]
+
+    return groups

gcf/session.py

@@ -0,0 +1,137 @@
+"""Session-based deduplication for GCF encoding."""
+
+import threading
+
+from .constants import KIND_ABBREV
+from .encode import _group_by_distance
+from .types import Payload, Symbol
+
+
+class Session:
+    """Tracks symbols transmitted to a client, enabling subsequent responses
+    to reference them by ID without full retransmission.
+
+    Thread-safe: multiple tool handlers may encode concurrently within a session.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._symbols: dict[str, int] = {}  # qualified_name -> global session ID
+        self._next_id: int = 0
+
+    def transmitted(self, qname: str) -> bool:
+        """Return True if the symbol has been sent in a previous response."""
+        with self._lock:
+            return qname in self._symbols
+
+    def get_id(self, qname: str) -> int:
+        """Return the session-global ID for a previously transmitted symbol.
+
+        Returns -1 if not found.
+        """
+        with self._lock:
+            return self._symbols.get(qname, -1)
+
+    def record(self, symbols: list[Symbol]) -> None:
+        """Mark symbols as transmitted and assign session-global IDs.
+
+        Call this after a successful encode to register newly-sent symbols.
+        """
+        with self._lock:
+            for sym in symbols:
+                if sym.qualified_name not in self._symbols:
+                    self._symbols[sym.qualified_name] = self._next_id
+                    self._next_id += 1
+
+    def size(self) -> int:
+        """Return the number of symbols tracked in this session."""
+        with self._lock:
+            return len(self._symbols)
+
+    def reset(self) -> None:
+        """Clear the session state."""
+        with self._lock:
+            self._symbols.clear()
+            self._next_id = 0
+
+
+def encode_with_session(p: Payload, sess: Session | None = None) -> str:
+    """Encode a payload with session deduplication.
+
+    Symbols that were already transmitted in prior responses are emitted as
+    bare references (`@N  # previously transmitted`) instead of full declarations.
+    After encoding, newly-sent symbols are recorded in the session.
+
+    Args:
+        p: The payload to encode.
+        sess: Optional session tracker. If None, encodes without deduplication.
+
+    Returns:
+        GCF-formatted text string.
+    """
+    if sess is None:
+        from .encode import encode
+        return encode(p)
+
+    parts: list[str] = []
+
+    # 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"
+    )
+    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] = []
+
+    # Group by distance.
+    groups = _group_by_distance(p.symbols)
+    group_names = ["targets", "related", "extended"]
+
+    for g_distance, g_symbols in groups:
+        if not g_symbols:
+            continue
+        if g_distance < len(group_names):
+            name = group_names[g_distance]
+        else:
+            name = f"distance_{g_distance}"
+        parts.append(f"## {name}")
+
+        for s in g_symbols:
+            idx = local_index[s.qualified_name]
+            if sess.transmitted(s.qualified_name):
+                # Bare reference: symbol was sent in a prior response.
+                parts.append(f"@{idx}  # previously transmitted")
+            else:
+                # Full declaration.
+                kind = KIND_ABBREV.get(s.kind, s.kind)
+                parts.append(
+                    f"@{idx} {kind} {s.qualified_name} {s.score:.2f} {s.provenance}"
+                )
+                new_symbols.append(s)
+
+    # Edges section.
+    if p.edges:
+        parts.append("## edges")
+        for e in p.edges:
+            src_idx = local_index.get(e.source)
+            tgt_idx = local_index.get(e.target)
+            if src_idx is None or tgt_idx is None:
+                continue
+            line = f"@{tgt_idx}<@{src_idx} {e.edge_type}"
+            if e.status and e.status != "unchanged":
+                line += f" {e.status}"
+            parts.append(line)
+
+    # Record all new symbols in the session.
+    sess.record(new_symbols)
+
+    return "\n".join(parts) + "\n"

gcf/types.py

@@ -0,0 +1,63 @@
+"""Data types for GCF payloads."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Components:
+    """Score breakdown for a symbol."""
+
+    blast_radius: float = 0.0
+    confidence: float = 0.0
+    recency: float = 0.0
+    distance: float = 0.0
+
+
+@dataclass
+class Symbol:
+    """A node in a GCF payload."""
+
+    qualified_name: str = ""
+    kind: str = ""
+    score: float = 0.0
+    provenance: str = ""
+    distance: int = 0
+    signature: str = ""
+    components: Components = field(default_factory=Components)
+
+
+@dataclass
+class Edge:
+    """A directed relationship in a GCF payload."""
+
+    source: str = ""
+    target: str = ""
+    edge_type: str = ""
+    status: str = ""
+
+
+@dataclass
+class Payload:
+    """Input/output structure for GCF encoding/decoding."""
+
+    tool: str = ""
+    tokens_used: int = 0
+    token_budget: int = 0
+    pack_root: str = ""
+    symbols: list[Symbol] = field(default_factory=list)
+    edges: list[Edge] = field(default_factory=list)
+
+
+@dataclass
+class DeltaPayload:
+    """Diff between a prior context pack and the current result."""
+
+    tool: str = ""
+    base_root: str = ""
+    new_root: str = ""
+    removed: list[Symbol] = field(default_factory=list)
+    added: list[Symbol] = field(default_factory=list)
+    removed_edges: list[Edge] = field(default_factory=list)
+    added_edges: list[Edge] = field(default_factory=list)
+    delta_tokens: int = 0
+    full_tokens: int = 0

gcf_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: gcf-python
+Version: 0.1.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/
+Project-URL: Specification, https://github.com/blackwell-systems/gcf
+Author: Blackwell Systems
+License: MIT
+License-File: LICENSE
+Keywords: gcf,graph,llm,mcp,token-efficient,wire-format
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://github.com/blackwell-systems"><img src="https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg" alt="Blackwell Systems"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</p>
+
+# gcf-python
+
+Python implementation of [GCF (Graph Compact Format)](https://github.com/blackwell-systems/gcf).
+
+**84% fewer tokens than JSON. 32% fewer than TOON. 100% LLM comprehension accuracy at 500 symbols, where JSON fails.**
+
+## Install
+
+```
+pip install gcf-py
+```
+
+Zero dependencies. Pure Python. Python 3.9+. Includes CLI.
+
+## CLI
+
+```bash
+gcf encode < payload.json    # JSON to GCF
+gcf decode < payload.gcf     # GCF to JSON
+gcf stats  < payload.json    # token comparison with visual bar
+```
+
+```
+Payload: 50 symbols, 20 edges
+
+  JSON  ██████████████████████████████  4,200 tokens
+  GCF   ████████░░░░░░░░░░░░░░░░░░░░░░  1,150 tokens
+
+  Savings: 73% fewer tokens with GCF
+```
+
+## Library
+
+### Quick Start
+
+```python
+from gcf import encode, Payload, Symbol, Edge
+
+p = Payload(
+    tool="context_for_task",
+    token_budget=5000,
+    tokens_used=1847,
+    symbols=[
+        Symbol(qualified_name="pkg.AuthMiddleware", kind="function", score=0.78, provenance="lsp_resolved", distance=0),
+        Symbol(qualified_name="pkg.NewServer", kind="function", score=0.54, provenance="lsp_resolved", distance=1),
+    ],
+    edges=[
+        Edge(source="pkg.NewServer", target="pkg.AuthMiddleware", edge_type="calls"),
+    ],
+)
+
+output = encode(p)
+```
+
+Output:
+```
+GCF tool=context_for_task budget=5000 tokens=1847 symbols=2
+## targets
+@0 fn pkg.AuthMiddleware 0.78 lsp_resolved
+## related
+@1 fn pkg.NewServer 0.54 lsp_resolved
+## edges
+@0<@1 calls
+```
+
+## Decode
+
+```python
+from gcf import decode
+
+p = decode(input_text)
+print(p.tool, len(p.symbols), "symbols", len(p.edges), "edges")
+```
+
+## Session Deduplication
+
+Track transmitted symbols across multiple tool responses. Previously-sent symbols become bare references instead of full declarations:
+
+```python
+from gcf import encode_with_session, Session, Payload, Symbol
+
+sess = Session()
+
+out1 = encode_with_session(payload1, sess)  # full declarations
+out2 = encode_with_session(payload2, sess)  # reused symbols as "@N  # previously transmitted"
+```
+
+By the 5th call in a session: 92.7% token savings vs JSON.
+
+## Delta Encoding
+
+When the consumer already has a prior context pack, send only what changed:
+
+```python
+from gcf import encode_delta, DeltaPayload, Symbol, Edge
+
+delta = DeltaPayload(
+    tool="context_for_task",
+    base_root="aaa111",
+    new_root="bbb222",
+    removed=[Symbol(qualified_name="pkg.OldFunc", kind="function")],
+    added=[Symbol(qualified_name="pkg.NewFunc", kind="function", score=0.85, provenance="rwr")],
+    delta_tokens=30,
+    full_tokens=200,
+)
+
+output = encode_delta(delta)
+```
+
+81.2% savings on re-queries where the pack changed slightly.
+
+## API
+
+| Function | Description |
+|----------|-------------|
+| `encode(p: Payload) -> str` | Encode a payload to GCF text |
+| `decode(input_text: str) -> Payload` | Parse GCF text back to a Payload |
+| `encode_with_session(p: Payload, s: Session) -> str` | Encode with session deduplication |
+| `encode_delta(d: DeltaPayload) -> str` | Encode a delta (added/removed only) |
+| `Session()` | Create a new session tracker (thread-safe) |
+
+## Types
+
+| Type | Purpose |
+|------|---------|
+| `Payload` | Full GCF payload: tool, budget, symbols, edges, pack root |
+| `Symbol` | Graph node: qualified name, kind, score, provenance, distance |
+| `Edge` | Directed relationship: source, target, edge type |
+| `DeltaPayload` | Diff between two packs: added/removed symbols and edges |
+| `Session` | Thread-safe tracker for multi-call deduplication |
+| `KIND_ABBREV` / `KIND_EXPAND` | Bidirectional kind abbreviation dicts |
+
+## Comprehension Eval
+
+Rigorous 3-way benchmark (GCF vs TOON vs JSON) at 500 symbols, 200 edges. Six structured extraction questions sent to an LLM:
+
+| Format | Accuracy | Tokens | vs JSON |
+|--------|----------|--------|---------|
+| **GCF** | **100%** (6/6) | **11,090** | **79% fewer** |
+| TOON | 100% (6/6) | 16,378 | 69% fewer |
+| JSON | 66.7% (4/6) | 53,341 | baseline |
+
+JSON failed on counting tasks. GCF and TOON both achieved perfect accuracy. GCF does it in 32% fewer tokens.
+
+## Token Efficiency (TOON's Own Benchmark)
+
+Running [TOON's benchmark harness](https://github.com/blackwell-systems/toon/tree/gcf-comparison) with GCF inserted (their datasets, their tokenizer):
+
+| Track | GCF | TOON | Result |
+|-------|-----|------|--------|
+| Mixed-structure (nested, semi-uniform) | 169,554 | 227,896 | **GCF 34% smaller** |
+| Flat-only (tabular) | 66,026 | 67,837 | **GCF 3% smaller** |
+| Semi-uniform event logs | 107,269 | 154,032 | **GCF 44% smaller** |
+
+GCF wins on every dataset except deeply nested config (75 tokens on a 618-token payload). On semi-uniform data, GCF uses 44% fewer tokens than TOON.
+
+Reproducible: [blackwell-systems/toon@gcf-comparison](https://github.com/blackwell-systems/toon/tree/gcf-comparison)
+
+## Other Implementations
+
+- **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)
+
+## License
+
+MIT

gcf_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+gcf/__init__.py,sha256=XzxWfa__EBT3GqV6nAC74WX6EpNFO1Qg-YsnCg1ROQQ,1483
+gcf/cli.py,sha256=2hSTBqiYcn1_EgGXuO65MHiEGh0C4DRMvspTd2zUaso,4258
+gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
+gcf/decode.py,sha256=kdbYrx0WzozDw-PhPieBv6h_a0B995crCEK-CJoK59c,5162
+gcf/delta.py,sha256=xU0ujtSq1iF7yU8yk_WNQKh8iove-WUV_nKSuvW1XVk,1656
+gcf/encode.py,sha256=KYGxFHy5LJoOF0IQblAm78bLL5uFf5iQMtrnyuuQXCA,2664
+gcf/session.py,sha256=jVfpEK4euCn7apVm-sb0OyycUJrFUPaAUEWCT0d2c14,4472
+gcf/types.py,sha256=yZL2knyFYguh2ex1ZXO1VwD4NEY4jvC-DL6-R-i-x0U,1429
+gcf_python-0.1.0.dist-info/METADATA,sha256=hfE2L2HB1wxrBi8mRYHTD-KiViqVZ-4omjQNdT-ZtNA,6646
+gcf_python-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gcf_python-0.1.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-0.1.0.dist-info/licenses/LICENSE,sha256=txSvg3E4LugiB7MOOTci6WKd6wMOrOJTvaITeFJ2SgU,1074
+gcf_python-0.1.0.dist-info/RECORD,,

gcf_python-0.1.0.dist-info/WHEEL

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

gcf_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gcf = gcf.cli:main

gcf_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blackwell Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.