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

GCF TypeScript — Formato de Wire Eficiente para LLMs

blackwell-systems/gcf-typescript

Formato de dados 53% mais eficiente que JSON para comunicação com LLMs

Ver no GitHub
InicialPluginScore · de 0 a 100

Implementação TypeScript do GCF (formato de compressão de dados otimizado para modelos de linguagem). Reduz tokens em 25,5% comparado ao TOON e 53% comparado a JSON, mantendo 100% de compreensão em modelos fronteira. Inclui CLI, biblioteca TypeScript-first e suporte a sessões com deduplicação.

Instalação

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

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.7.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Reduzir consumo de tokens em APIs com LLMs
  • Serializar grafos complexos e dados estruturados compactamente
  • MCP servers que precisam otimizar bandwidth em conversas longas
  • Streaming de grandes volumes de dados para modelos sem buffering

Veredito

Ferramenta técnica sólida e comprovada (1.700+ avaliações LLM, zero treinamento necessário) para reduzir custos de token em produção. Recomendado para quem trabalha intensivamente com APIs de LLM ou MCP servers com restrição de contexto.

README

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

gcf-typescript

TypeScript 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

npm install @blackwell-systems/gcf

Zero dependencies. TypeScript-first. Includes CLI. Don't want to change code? Use the MCP proxy for zero-code adoption.

CLI

npx @blackwell-systems/gcf encode < payload.json    # JSON to GCF
npx @blackwell-systems/gcf decode < payload.gcf     # GCF to JSON
npx @blackwell-systems/gcf stats  < payload.json    # token comparison
Payload: 50 symbols, 20 edges

  JSON  ██████████████████████████████  4,200 tokens
  GCF   ████████░░░░░░░░░░░░░░░░░░░░░░  1,150 tokens

  Savings: 73% fewer tokens with GCF

Or install globally: npm install -g @blackwell-systems/gcf then use gcf directly.

Library

Quick Start

import { encodeGeneric } from '@blackwell-systems/gcf';

const output = encodeGeneric({
  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

import { decode } from '@blackwell-systems/gcf';

const p = decode(input);
console.log(p.tool, p.symbols.length, 'symbols', p.edges.length, 'edges');

Session Deduplication

Track transmitted symbols across multiple tool responses. Previously-sent symbols become bare references instead of full declarations:

import { Session, encodeWithSession } from '@blackwell-systems/gcf';

const sess = new Session();

const out1 = encodeWithSession(payload1, sess); // full declarations
const out2 = encodeWithSession(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. Ideal for MCP servers that walk large graphs or paginate results:

import { StreamEncoder } from '@blackwell-systems/gcf';

const enc = new StreamEncoder(writer, 'context_for_task', { tokenBudget: 5000 });

// Symbols emit immediately as they're discovered.
enc.writeSymbol({ qualifiedName: 'pkg.Auth', kind: 'function', score: 0.95, provenance: 'lsp', distance: 0 });
enc.writeSymbol({ qualifiedName: 'pkg.Server', kind: 'function', score: 0.60, provenance: 'lsp', distance: 1 });

// Edges emit immediately too.
enc.writeEdge({ source: 'pkg.Server', target: 'pkg.Auth', edgeType: 'calls' });

// Close emits the ## _summary trailer with final counts.
enc.close();

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: string) method (Node.js streams, web WritableStreams, or a simple callback). Standard decode() handles streaming output with no changes.

Delta Encoding

When the consumer already has a prior context pack, send only what changed:

import { encodeDelta, type DeltaPayload } from '@blackwell-systems/gcf';

const delta: DeltaPayload = {
  tool: 'context_for_task',
  baseRoot: 'aaa111',
  newRoot: 'bbb222',
  removed: [{ qualifiedName: 'pkg.OldFunc', kind: 'function', score: 0, provenance: '', distance: 0 }],
  added: [{ qualifiedName: 'pkg.NewFunc', kind: 'function', score: 0.85, provenance: 'rwr', distance: 0 }],
  removedEdges: [],
  addedEdges: [],
  deltaTokens: 30,
  fullTokens: 200,
};

const output = encodeDelta(delta);

81.2% savings on re-queries where the pack changed slightly.

Generic Encoding

Encode any JS value (not just graph payloads) into GCF tabular format:

import { encodeGeneric } from '@blackwell-systems/gcf';

const output = encodeGeneric({
  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 objects, arrays, and primitives. Arrays of uniform objects get tabular rows. Nested objects use ## key section headers.

API

FunctionDescription
encode(p: Payload): stringEncode a graph payload to GCF text
encodeGeneric(data: unknown): stringEncode any value to GCF tabular format
decode(input: string): PayloadParse GCF text back to a Payload
encodeWithSession(p: Payload, s: Session): stringEncode with session deduplication
new StreamEncoder(w, tool, opts)Create a streaming encoder (zero-buffering)
encodeDelta(d: DeltaPayload): stringEncode a delta (added/removed only)
new Session()Create a new session tracker

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
SessionTracker for multi-call deduplication
KIND_ABBREV / KIND_EXPANDBidirectional kind abbreviation maps

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