convez.ai
MCP ServerIntegração & APIsIntermediário
blackwell-systems

GCF Python — Formato Eficiente de Tokens para LLMs

blackwell-systems/gcf-python

Formato wire token-eficiente para estruturados em LLMs: 73% menos tokens que JSON

Ver no GitHub
InicialPluginScore · de 0 a 100

Implementação Python do GCF, um formato de serialização otimizado para economia de tokens em modelos de linguagem. Reduz consumo de tokens em 25,5% comparado a TOON e 53% comparado a JSON, mantendo 100% de compreensão. Oferece CLI, biblioteca com codificação/decodificação, deduplicação de sessão e suporte a streaming.

Instalação

$npx convez-ai blackwell-systems/gcf-python

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v2.8.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Reduzir custos de APIs de LLM em pipelines de integração
  • Serializar estruturas complexas (grafos de código, contexto) com máxima eficiência
  • Streaming de grandes volumes de dados estruturados com memória O(1)

Veredito

Solução técnica sólida para otimização de custos em LLM APIs. Bem documentada, zero dependências, testada em 1.700+ avaliações. Recomendado para cenários de alta escala onde compressão de tokens impacta fatura significativamente.

README

A tradução para o português deste README ainda está na fila.

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

FunctionDescription
encode(p: Payload) -> strEncode a graph payload to GCF text
encode_generic(data: Any) -> strEncode any value to GCF tabular format
decode(input_text: str) -> PayloadParse GCF text back to a Payload
encode_with_session(p: Payload, s: Session) -> strEncode with session deduplication
encode_delta(d: DeltaPayload) -> strEncode a delta (added/removed only)
Session()Create a new session tracker (thread-safe)

Types

TypePurpose
PayloadFull GCF payload: tool, budget, symbols, edges, pack root
SymbolGraph node: qualified name, kind, score, provenance, distance
EdgeDirected relationship: source, target, edge type
DeltaPayloadDiff between two packs: added/removed symbols and edges
SessionThread-safe tracker for multi-call deduplication
KIND_ABBREV / KIND_EXPANDBidirectional kind abbreviation dicts

Benchmarks

1,700+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.

GCFTOONJSON
Comprehension (23 runs, 10 models)90.7%68.5%53.6%
Generation (28 runs, 9 models)5/51.0/55.0/5
Input tokens (500 symbols)11,09016,37853,341
Output tokens (100 symbols)5,9768,93716,121

GCF wins 13/15 datasets on the expanded token efficiency benchmark. Full results: gcformat.com/guide/benchmarks

Links

License

MIT - Dayna Blackwell

Ver o original no GitHub

Bom para

Relacionados