gcf-python
Python implementation of GCF — the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
100% comprehension on every frontier model tested. 25.5% fewer tokens than TOON, 53% fewer than JSON across 15 datasets. 90.7% on structurally complex code graphs (vs TOON 68.5%, JSON 53.6%). 1,700+ LLM evaluations. Zero training.
Docs: gcformat.com · Playground · GCF vs TOON
Install
pip install gcf-python
Zero dependencies. Pure Python. Python 3.9+. Includes CLI. Don't want to change code? Use the MCP proxy for zero-code adoption.
CLI
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
from gcf import encode_generic
output = encode_generic({
"employees": [
{"id": 1, "name": "Alice", "department": "Engineering", "salary": 95000},
{"id": 2, "name": "Bob", "department": "Sales", "salary": 72000},
],
})
Output:
## employees [2]{id,name,department,salary}
1|Alice|Engineering|95000
2|Bob|Sales|72000
Decode
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:
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.
Streaming Encode
Write GCF output incrementally as symbols and edges arrive. Zero buffering, O(1) memory per row:
from gcf import StreamEncoder, Symbol, Edge
enc = StreamEncoder(sys.stdout, "context_for_task", token_budget=5000)
enc.write_symbol(Symbol(qualified_name="pkg.Auth", kind="function", score=0.95, provenance="lsp", distance=0))
enc.write_symbol(Symbol(qualified_name="pkg.Server", kind="function", score=0.60, provenance="lsp", distance=1))
enc.write_edge(Edge(source="pkg.Server", target="pkg.Auth", edge_type="calls"))
enc.close() # emits ## _summary trailer
Output:
GCF tool=context_for_task budget=5000
## targets
@0 fn pkg.Auth 0.95 lsp
## related
@1 fn pkg.Server 0.60 lsp
## edges [?]
@0<@1 calls
## _summary symbols=2 edges=1 sections=targets:1,related:1,edges:1
The writer is any object with a write(s: str) method. Thread-safe. Standard decode() handles streaming output with no changes.
Delta Encoding
When the consumer already has a prior context pack, send only what changed:
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.
Generic Encoding
Encode any Python value (not just graph payloads) into GCF tabular format:
from gcf import encode_generic
output = encode_generic({
"employees": [
{"id": 1, "name": "Alice", "department": "Engineering", "salary": 95000},
{"id": 2, "name": "Bob", "department": "Sales", "salary": 72000},
],
})
Output:
## employees [2]{id,name,department,salary}
1|Alice|Engineering|95000
2|Bob|Sales|72000
Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows. Nested dicts use ## key section headers.
API
| Function | Description |
|---|---|
encode(p: Payload) -> str |
Encode a graph payload to GCF text |
encode_generic(data: Any) -> str |
Encode any value to GCF tabular format |
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 |
Benchmarks
1,700+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.
| GCF | TOON | JSON | |
|---|---|---|---|
| Comprehension (23 runs, 10 models) | 90.7% | 68.5% | 53.6% |
| Generation (28 runs, 9 models) | 5/5 | 1.0/5 | 5.0/5 |
| Input tokens (500 symbols) | 11,090 | 16,378 | 53,341 |
| Output tokens (100 symbols) | 5,976 | 8,937 | 16,121 |
GCF wins 13/15 datasets on the expanded token efficiency benchmark. Full results: gcformat.com/guide/benchmarks
Implementations
| Language | Package | Repository |
|---|---|---|
| Go | go get github.com/blackwell-systems/gcf-go |
gcf-go |
| TypeScript | npm install @blackwell-systems/gcf |
gcf-typescript |
| Python | pip install gcf-python |
gcf-python |
| Rust | cargo add gcf |
gcf-rust |
| Swift | Swift Package Manager | gcf-swift |
| Kotlin | JitPack | gcf-kotlin |
| MCP Proxy | pip install gcf-proxy |
gcf-proxy (bidirectional, session dedup, HTTP frontend) |
| Claude Code Plugin | /plugin install |
gcf-claude-plugin (one-command install, session stats hook) |
| Codex Plugin | codex plugin add |
gcf-codex-plugin (one-command install, session stats hook) |
| VS Code | ext install blackwell-systems.gcf-vscode |
gcf-vscode (syntax highlighting) |
| n8n | npm install n8n-nodes-gcf |
gcf-n8n-nodes (workflow encode/decode) |
| Tree-sitter | npm install tree-sitter-gcf |
tree-sitter-gcf |
Zero runtime dependencies. MIT licensed. All implementations support both generic profile (encodeGeneric) and graph profile (encode). CLI included in all 6 languages.
Specification: SPEC v3.1 Stable with 157 conformance fixtures, 33,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.1.0+ (Go v1.2.0). Cross-language 6x6 matrix verified.
License
MIT - Dayna Blackwell
Metadata
Release files for gcf-python 2.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gcf_python-2.1.1.tar.gz | 867.5 kB | Without provenance | Details for gcf_python-2.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gcf_python-2.1.1-py3-none-any.whl | Python 3 | none | any | Details for gcf_python-2.1.1-py3-none-any.whl |
Total release size: 895.9 kB
Release files / gcf_python-2.1.1.tar.gz
| Download URL | gcf_python-2.1.1.tar.gz |
|---|---|
| Size | 867.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cbd621a1081e509649cec5793e3d952ea3c7f3aaf1139b388c578382672843bf
|
|
BLAKE2b-256 checksum How to use checksums |
fa12c9f11c516dc64637ee20a1dfc453b9292c35ee5181ef52e246edf3b77929
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / gcf_python-2.1.1-py3-none-any.whl
| Download URL | gcf_python-2.1.1-py3-none-any.whl |
|---|---|
| Size | 28.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ff952ec5a45ca968bffb8bb4d059597510aa066c83e88e815c9e6b20d0426d9c
|
|
BLAKE2b-256 checksum How to use checksums |
4bcad55d0d50c23de5e37117d4b6223a2ca516ac61fc17a72c39b30eb59b3192
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for gcf-python 2.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.