gcf-python 0.1.0__tar.gz

gcf_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]" || pip install -e . && pip install pytest
+      - run: pytest tests/ -v

gcf_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install build twine
+      - run: pip install -e . && pip install pytest && pytest tests/ -v
+      - run: python -m build
+      - run: twine upload --verbose dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

gcf_python-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+*.egg
+.eggs/

gcf_python-0.1.0/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.

gcf_python-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,172 @@
+<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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gcf-python"
+version = "0.1.0"
+description = "Python implementation of GCF (Graph Compact Format): token-optimized wire format for LLM tool responses"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    { name = "Blackwell Systems" },
+]
+keywords = ["gcf", "llm", "mcp", "token-efficient", "graph", "wire-format"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+gcf = "gcf.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/blackwell-systems/gcf-python"
+Documentation = "https://blackwell-systems.github.io/gcf/"
+Specification = "https://github.com/blackwell-systems/gcf"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gcf"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gcf_python-0.1.0/src/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"