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

GCF Kotlin — Formato Eficiente para LLMs

blackwell-systems/gcf-kotlin

Formato wire otimizado para LLMs com 25,5% menos tokens que TOON

Ver no GitHub
InicialPluginScore · de 0 a 100

Implementação em Kotlin/JVM do GCF (Graph Compression Format), um formato de wire otimizado para LLMs que reduz tokens em 25,5% comparado a TOON e 53% comparado a JSON. Oferece 100% de compreensão em modelos frontier, com suporte a deduplicação de sessão e zero treinamento necessário.

Instalação

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

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
1
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

  • Comprimir estruturas de dados complexas para APIs de LLM
  • Otimizar contexto de grafos de código em agentes IA
  • Reduzir custos de token em aplicações que usam Claude ou outros modelos

Veredito

Ferramenta de infraestrutura técnica sólida para quem precisa otimizar comunicação com LLMs em produção. A eficiência comprovada em 1.700+ avaliações justifica adoção em sistemas que lidam com grandes volumes de dados estruturados.

README

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

gcf-kotlin

Kotlin/JVM 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

Add the JitPack repository, then the dependency:

Gradle (Kotlin DSL)

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.blackwell-systems:gcf-kotlin:v0.5.0")
}

Gradle (Groovy)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.blackwell-systems:gcf-kotlin:v0.5.0'
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.blackwell-systems</groupId>
    <artifactId>gcf-kotlin</artifactId>
    <version>v0.5.0</version>
</dependency>

Don't want to change code? Use the MCP proxy for zero-code adoption.

Quick Start

import com.blackwellsystems.gcf.*

val output = encodeGeneric(mapOf(
    "employees" to listOf(
        mapOf("id" to 1, "name" to "Alice", "department" to "Engineering", "salary" to 95000),
        mapOf("id" to 2, "name" to "Bob", "department" to "Sales", "salary" to 72000),
    )
))

Output:

## employees [2]{department,id,name,salary}
Engineering|1|Alice|95000
Sales|2|Bob|72000

Graph Profile

val payload = Payload(
    tool = "context_for_task", tokenBudget = 5000, tokensUsed = 1847,
    symbols = listOf(
        Symbol(qualifiedName = "pkg.Auth", kind = "function", score = 0.78, provenance = "lsp", distance = 0),
        Symbol(qualifiedName = "pkg.Server", kind = "function", score = 0.54, provenance = "lsp", distance = 1),
    ),
    edges = listOf(Edge(source = "pkg.Server", target = "pkg.Auth", edgeType = "calls"))
)
val output = encode(payload)

Output:

GCF tool=context_for_task budget=5000 tokens=1847 symbols=2 edges=1
## targets
@0 fn pkg.Auth 0.78 lsp
## related
@1 fn pkg.Server 0.54 lsp
## edges [1]
@0<@1 calls

Decode

val p = decode(input)
println("${p.tool} ${p.symbols.size} symbols ${p.edges.size} edges")

Throws DecodeException on invalid input.

Session Deduplication

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

val session = Session()

val out1 = encodeWithSession(payload1, session) // full declarations
val out2 = encodeWithSession(payload2, session) // 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:

val enc = StreamEncoder(writer, "context_for_task", StreamOptions(tokenBudget = 5000))

enc.writeSymbol(Symbol(qualifiedName = "pkg.Auth", kind = "function", score = 0.95, provenance = "lsp", distance = 0))
enc.writeEdge(Edge(source = "pkg.Server", target = "pkg.Auth", edgeType = "calls"))
enc.close()  // emits ## _summary trailer

Output uses [?] deferred counts and ## _summary trailer. Standard decode() handles streaming output with no changes. Thread-safe via @Synchronized.

Delta Encoding

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

val delta = DeltaPayload(
    tool = "context_for_task",
    baseRoot = "aaa111",
    newRoot = "bbb222",
    removed = listOf(Symbol(qualifiedName = "pkg.OldFunc", kind = "function")),
    added = listOf(Symbol(qualifiedName = "pkg.NewFunc", kind = "function", score = 0.85, provenance = "rwr")),
    deltaTokens = 30,
    fullTokens = 200
)

val output = encodeDelta(delta)

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

Generic Encoding

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

val data = mapOf(
    "employees" to listOf(
        mapOf("id" to 1, "name" to "Alice", "department" to "Engineering", "salary" to 95000),
        mapOf("id" to 2, "name" to "Bob", "department" to "Sales", "salary" to 72000),
    )
)
val output = encodeGeneric(data)

Output:

## employees [2]{department,id,name,salary}
Engineering|1|Alice|95000
Sales|2|Bob|72000

Works on maps, lists, and primitives. Arrays of uniform maps get tabular rows. Nested maps use ## key section headers.

API

FunctionDescription
encode(payload: Payload): StringEncode a graph payload to GCF text
encodeGeneric(data: Any?): StringEncode any value to GCF tabular format
decode(input: String): PayloadParse GCF text back to a Payload
encodeWithSession(payload: Payload, session: Session?): StringEncode with session deduplication
encodeDelta(delta: DeltaPayload): StringEncode 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
ComponentsScore breakdown: blast radius, confidence, recency, distance
DecodeExceptionThrown on invalid GCF input
kindAbbrev / kindExpandBidirectional 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