https://github.com/skzl-ai/tscg

TSCG — Deterministic tool-schema compiler for LLM agents. 50-72% token savings, 50 tools in 2.4ms. Phi-4 recovers from 0% to 90% accuracy. 459 tests, zero dependencies, MIT.
https://github.com/skzl-ai/tscg
agentic-ai compression function-calling langchain llm mcp prompt-optimization token-savings tool-use typescript
Last synced: 27 days ago
JSON representation
TSCG — Deterministic tool-schema compiler for LLM agents. 50-72% token savings, 50 tools in 2.4ms. Phi-4 recovers from 0% to 90% accuracy. 459 tests, zero dependencies, MIT.
Host: GitHub
URL: https://github.com/skzl-ai/tscg
Owner: SKZL-AI
License: mit
Created: 2026-04-09T12:50:22.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-05-23T21:02:02.000Z (2 months ago)
Last Synced: 2026-06-30T15:00:32.111Z (27 days ago)
Topics: agentic-ai, compression, function-calling, langchain, llm, mcp, prompt-optimization, token-savings, tool-use, typescript
Language: TypeScript
Homepage: https://github.com/SKZL-AI/tscg#readme
Size: 8.26 MB
Stars: 19
Watchers: 4
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project

README

          # TSCG -- Tool-Schema Compression Grammar

[![npm @tscg/core](https://img.shields.io/npm/v/@tscg/core?label=%40tscg%2Fcore)](https://www.npmjs.com/package/@tscg/core)

[![npm @tscg/mcp-proxy](https://img.shields.io/npm/v/@tscg/mcp-proxy?label=%40tscg%2Fmcp-proxy)](https://www.npmjs.com/package/@tscg/mcp-proxy)

[![npm @tscg/tool-optimizer](https://img.shields.io/npm/v/@tscg/tool-optimizer?label=%40tscg%2Ftool-optimizer)](https://www.npmjs.com/package/@tscg/tool-optimizer)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[![Tests](https://img.shields.io/badge/tests-108%20passing-brightgreen)]()

[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-green)]()

**Deterministic tool-schema compiler that reduces LLM tool-definition overhead by 50--72% while *improving* accuracy.**

1,200 LOC TypeScript. Zero dependencies. Sub-millisecond. 23KB ESM bundle.

## Paper 2: Agentic RAG Enablement (May 2026)

### 6,566-Call Agentic RAG Benchmark

TSCG enables agentic RAG under constrained context budgets. We evaluate 14 models (1.5B--32B local models plus one frontier API model) across 6,566 API calls at three context budgets (8K, 16K, 32K) with 28 tool definitions:

| Condition | JSON EM | TSCG EM | Delta |

|-----------|---------|---------|-------|

| 8K, 28 tools (avg 8 models) | 2.6% | 23.1% | **+20.5pp** |

| HotpotQA (Phi-4, 8K) | 0% | 48% | **+48pp** |

| 32K ceiling control | -- | -- | 4 of 5 models: \|Delta\| <= 1pp |

| Frontier: 500 tools, 200K | 0% | 90% | **+90pp** |

**Key finding:** At 8K context with 28 tools, JSON schemas overflow the context window entirely (near-zero accuracy, 2.6% avg EM). TSCG compression restores RAG functionality -- a categorical enablement, not incremental improvement.

- 14 models tested (1.5B--32B + one frontier API model), $107 total cost

- Frontier scaling: JSON overflows at ~494 tools, TSCG operational beyond 800

- External validation on HotpotQA confirms generalizability

- TAB Scenario C (25--100 tools) cross-validates stable compression at scale

- Balanced profile ablation (n=400): equivalent accuracy to conservative (delta = +0.8pp)

- Paper: [TSCG-RAG-Benchmark-Paper.pdf](./TSCG-RAG-Benchmark-Paper.pdf)

---

## Paper 1 Findings (April 2026)

### 720-Call E2E Benchmark on Claude Models

**Claude Opus 4.7** -- matches-or-beats baseline with 57-63% token savings:

| Tool Count | Baseline | TSCG Balanced | Δ Accuracy | Savings |

|------------|----------|---------------|------------|---------|

| 16 | 70.0% | **77.5%** | **+7.5pp** | 56.9% |

| 43 | 77.5% | **80.0%** | **+2.5pp** | 63.0% |

| 50 | 72.5% | **80.0%** | **+7.5pp** | 62.8% |

**Claude Sonnet 4** -- consistent 57-63% compression with robust accuracy:

| Tool Count | Baseline | TSCG Balanced | Δ Accuracy | Savings |

|------------|----------|---------------|------------|---------|

| 16 | 77.5% | 80.0% | +2.5pp | 56.9% |

| 43 | 85.0% | 80.0% | -5.0pp | 63.0% |

| 50 | 77.5% | 77.5% | ±0.0pp | 62.8% |

### 480-Call MCP Proxy Benchmark (v1.4.1)

**480-call extended proxy benchmark** (n=40 per cell, 2 seeds, 2 models x 3 tool counts):

| Model | Tools | Baseline | TSCG Proxy | Δ Accuracy | Token Savings |

|-------|-------|----------|------------|------------|---------------|

| **Opus 4.7** | 16 | 70.0% | **75.0%** | **+5.0pp** | 53.1% |

| **Opus 4.7** | 43 | 75.0% | 75.0% | ±0.0pp | 55.8% |

| **Opus 4.7** | 50 | 77.5% | 77.5% | ±0.0pp | 55.5% |

| Sonnet 4 | 16 | 80.0% | 77.5% | -2.5pp | 53.1% |

| Sonnet 4 | 43 | 85.0% | 82.5% | -2.5pp | 55.8% |

| Sonnet 4 | 50 | 77.5% | 77.5% | ±0.0pp | 55.5% |

Opus 4.7 matches-or-beats baseline in all conditions; Sonnet 4 within expected CI (max -2.5pp). Both achieve 53-56% token savings.

**Tool-Optimizer E2E validation** (`@tscg/tool-optimizer` `withTSCG()` wrapper, 30 calls, Sonnet 4 @ 16 tools): withTSCG **86.7%** vs baseline 80.0% (**+6.7pp**), 36.6% character savings.

### Three Frontier-Model Operator Archetypes

TSCG compression response is model-specific. Three distinct archetypes observed:

- **Opus 4.7 -- Operator-HUNGRY** -- every operator contributes; balanced (all-8) is optimal

- **Sonnet 4 -- Operator-ROBUST** -- config-agnostic; 6 of 7 configs near-identical accuracy

- **GPT-5.2 -- Operator-SENSITIVE** -- CFL helps, CFO hurts; custom config optimal

### External Validation -- 4 Independent Benchmarks

TSCG's internal benchmark (TAB -- Tool-Agentic Bench, ~19,000 calls) is **independently corroborated** by four external benchmarks, including industry-standard evaluation suites:

| Benchmark | Type | Result | Significance |

|-----------|------|--------|--------------|

| **BFCL** ([Berkeley Function Calling Leaderboard](https://gorilla.cs.berkeley.edu/leaderboard.html)) | Industry standard | **108--181% ARR** across 3 frontier models | Sonnet 4: 85.7%→93.2% (+7.5pp), GPT-4o: 31.7%→57.4% (+25.7pp), GPT-5.2: 61.9%→89.4% (+27.5pp) |

| **ToolBench** (Qin et al.) | Academic benchmark | **+5.0pp** (75.0%→80.0%) | Real-world tool catalog, 20 tools |

| **API-Bank** (Li et al.) | Academic benchmark | -5.0pp (80.0%→75.0%) | Honest negative result -- not all benchmarks improve |

| **Real MCP Server** (@modelcontextprotocol/server-filesystem) | Production endpoint | **100% syntactic validity** | 30 tasks on live MCP server, server-acceptance 90--97% |

**TAB → Real MCP Transfer (0.1pp):** The internal TAB benchmark is not merely a self-constructed evaluation -- it demonstrably **predicts real-world MCP behavior within 0.1 accuracy points**. Sonnet 4 on 43-tool MCP: synthetic TAB delta = -1.6pp vs real MCP delta = -1.7pp. This tight transfer validates TAB as a reliable proxy for production MCP deployments.

Mean across the 3 external catalog benchmarks: **+2.5pp** (80.2%→82.7%).

See [paper](./TSCG-paper.pdf) for full methodology and per-benchmark analysis.

## The Problem

Every LLM agent framework sends full JSON Schema definitions for every registered tool on every API call. Claude Code injects ~50,000 tokens of tool definitions per subprocess. At production scale (100K calls/day), the schema overhead alone costs **>$30,000/month**.

Worse: small models (4B--14B) cannot parse JSON-format tool schemas reliably at scale -- achieving **0--49% accuracy** with >15 tools. This locks agentic capabilities behind expensive frontier APIs.

## Key Results

### Pareto Dominance: Better Accuracy AND Fewer Tokens

BFCL ([Berkeley Function Calling Leaderboard](https://gorilla.cs.berkeley.edu/leaderboard.html)) validation -- the industry standard for tool-calling evaluation:

| Model | Without TSCG | With TSCG | Improvement | Token Savings |

|-------|-------------|-----------|-------------|---------------|

| Claude Sonnet 4 | 85.7% | 93.2% | +7.5pp | 46.8% |

| **GPT-4o** | **31.7%** | **57.4%** | **+25.7pp (181% ARR)** | 2.6% |

| GPT-5.2 | 61.9% | 89.4% | +27.5pp (144% ARR) | 8.3% |

Every model *improves*. TSCG achieves **108--181% Accuracy Retention Rate** -- it doesn't just retain accuracy, it increases it.

### Small Model Enablement

| Model | JSON Baseline (20 tools) | With TSCG | Recovery |

|-------|------------------------|-----------|----------|

| Phi-4 14B | 0% | 84.4% | **+84.4pp** |

| Mistral 7B | 35% | 80.1% | **+45.1pp** |

| Gemma 3 4B | 49.9% | 67.0% | +17.1pp |

Seven small models (4B--14B) that achieve 0--49% accuracy on JSON tools recover to **65--90%** with TSCG. The root cause: JSON format, not model capacity (R^2 = 0.88 against JSON baselines, collapses to 0.03 against text -- **97% of variance is format sensitivity**).

### Full Benchmark Summary

From **~19,000 API calls** across **12 models** (4B--32B + 3 frontier APIs), 5 scenarios:

| Finding | Detail |

|---------|--------|

| Token savings | 50--72% on tool schemas |

| BFCL validation | 108--181% Accuracy Retention Rate |

| Formal guarantee | >=51% savings on any well-formed schema (Theorem 3.1) |

| Predictive model | R^2 = 0.88 predicts TSCG benefit from single baseline measurement |

| Speed | 50 tools in 2.4ms (Node.js v24, commodity hardware) |

| Cost at scale | >$30,000/month savings at 100K calls/day |

### Verified Performance (Fresh Install)

Independent reproduction on `@tscg/core` from npm:

| Metric | Measured |

|--------|----------|

| 5 realistic tools (Claude target) | 59.5% token savings |

| 50 tools | 66.6% savings in 2.4ms |

| Compression time (5 tools) | 0.9ms |

| Unit tests | 108 passing (core 47 + proxy 61) |

| Bundle | 34.7KB (11.7KB gzipped) |

| Dependencies | 0 |

## What TSCG Does

TSCG applies 8 formally-defined transforms grounded in how causal transformers process tokens:

| Principle | Full Name | What It Does |

|-----------|-----------|-------------|

| **TAS** | Tokenizer-Aligned Syntax | Optimizes for BPE boundaries |

| **CFL** | Constraint-First Layout | Exploits the attention sink at position 0 |

| **CFO** | Causal-Flow Ordering | Orders operations into causal chains |

| **SDM** | Semantic Density Maximization | Removes 104+ filler patterns |

| **DRO** | Delimiter-Role Optimization | Converts verbose phrases to compact delimiters |

| **CCP** | Closure-Context Preservation | Appends closure block for recency bias |

| **CAS** | Causal Access Scoring | Scores and reorders by parameter fragility |

| **SAD-F** | Selective Anchor Duplication | Budget-constrained anchor duplication |

## Quick Start

All three `@tscg/*` packages use umbrella versioning -- same version number, released together.

```bash

npm install @tscg/core                # Core compression engine

npm install @tscg/mcp-proxy           # Transparent MCP middleware

npm install @tscg/tool-optimizer      # LangChain / Vercel AI SDK integrations

```

```typescript

import { compress } from '@tscg/core';

const tools = [

  {

    type: 'function',

    function: {

      name: 'get_weather',

      description: 'Get the current weather for a location',

      parameters: {

        type: 'object',

        properties: {

          location: { type: 'string', description: 'City name or coordinates' },

          units: { type: 'string', enum: ['celsius', 'fahrenheit'] },

        },

        required: ['location'],

      },

    },

  },

];

const result = compress(tools, { model: 'claude-sonnet' });

console.log(result.compressed);

console.log(`Saved ${result.metrics.tokens.savingsPercent}% tokens`);

// => "get_weather(location:str units?:str[celsius|fahrenheit])|Get current weather"

// => "Saved 62.3% tokens"

```

### Result Object

```typescript

const result = compress(tools, { model: 'claude-sonnet', profile: 'balanced' });

result.compressed                        // string — compressed tool definitions

result.metrics.tokens.original           // number — original token count

result.metrics.tokens.compressed         // number — compressed token count

result.metrics.tokens.savingsPercent     // number — e.g. 62.3

result.metrics.compressionTimeMs         // number — e.g. 0.9

result.appliedPrinciples                 // string[] — e.g. ['SDM', 'CAS', 'DRO', 'TAS']

result.metrics.perTool                   // { name, originalTokens, compressedTokens, savingsPercent }[]

```

### Options

```typescript

compress(tools, {

  model: 'claude-sonnet',   // Target model: 'claude-sonnet' | 'gpt-4o' | 'gpt-4' | ...

  profile: 'balanced',      // Profile: 'conservative' | 'balanced' | 'aggressive' | 'auto'

});

```

### Description-Only Mode (v1.4.0)

Compress only `.description` fields while preserving the full JSON Schema structure -- compatible with native tool-calling APIs (OpenAI, Anthropic, Google):

```typescript

import { compressDescriptions } from '@tscg/core';

const result = compressDescriptions(tools, { model: 'claude-sonnet' });

console.log(result.tools);              // Tools with compressed descriptions

console.log(result.metrics.descriptions.savingsPercent); // ~25-40% description savings

```

### Auto Profile (v1.4.0)

The `auto` profile selects compression principles based on catalog size. At >=30 tools, CFL/CFO are automatically disabled (they become harmful at scale per our 100-tool benchmark findings):

```typescript

compress(tools, { model: 'claude-sonnet', profile: 'auto' });

```

## Packages

| Package | Description | Install |

|---------|-------------|---------|

| [`@tscg/core`](packages/core/) | Core compression engine (8 operators) | `npm i @tscg/core` |

| [`@tscg/mcp-proxy`](packages/mcp-proxy/) | MCP stdio proxy -- transparent TSCG compression for any MCP server | `npm i @tscg/mcp-proxy` |

| [`@tscg/tool-optimizer`](packages/tool-optimizer/) | LangChain, MCP, Vercel AI SDK integrations | `npm i @tscg/tool-optimizer` |

## CLI

```bash

# Compress tool schemas

npx tsx cli/tscg.ts compress --input tools.json --model claude-sonnet --profile balanced

# Run benchmarks

npx tsx cli/tscg.ts benchmark --model claude-sonnet

# Show compression info

npx tsx cli/tscg.ts info

```

## MCP Proxy

`@tscg/mcp-proxy` sits between Claude Code (or any MCP client) and your MCP tool servers, transparently compressing tool schemas:

```bash

# Opus 4.7 -- 57-63% savings, +2.5 to +7.5pp accuracy

npx @tscg/mcp-proxy --target=claude-opus-4-7 --server=

# Sonnet 4 -- 57-63% savings, robust accuracy

npx @tscg/mcp-proxy --target=claude-sonnet-4 --server=

```

Setting `--target` automatically enables the full compression pipeline validated by our 720-call benchmark. No other flags required.

**Legacy mode** (backward compatible with v1.0.x):

```bash

npx @tscg/mcp-proxy --server=

```

## Integrations

**LangChain:**

```typescript

import { withTSCG } from '@tscg/tool-optimizer/langchain';

const optimizedAgent = withTSCG(agent);

```

**Vercel AI SDK:**

```typescript

import { tscgMiddleware } from '@tscg/tool-optimizer/vercel';

```

## TSCG vs Other Approaches

| Property | TSCG | LLMLingua-2 | DSPy / SAMMO |

|----------|------|-------------|-------------|

| Accuracy effect | **Improves** (108--181% ARR) | Degrades (-5 to -20%) | Degrades |

| Speed | **2.4ms / 50 tools** | ~42s (GPU) | Minutes |

| Dependencies | **None** | GPU + ML framework | API calls |

| Deterministic | **Yes** | No | No |

| Formal guarantees | **>=51% savings** | None | None |

| Bundle size | **34.7KB** | Requires PyTorch | Full stack |

| Works offline | **Yes** | GPU required | API required |

## Who Benefits

- **Claude Code / Cursor / Windsurf users**: ~35K fewer tokens per subprocess

- **Local LLM users (Ollama)**: 7B models become functional tool-use agents with 50+ tools

- **Production API deployments**: >$30,000/month savings at 100K calls/day

- **Multi-agent orchestration**: Savings multiply per sub-agent in the chain

- **Edge / Mobile / Privacy**: EU AI Act compliant local deployment becomes viable

## Project Structure

```

packages/

  core/             # @tscg/core — compression engine (8 operators, 47 tests)

  mcp-proxy/        # @tscg/mcp-proxy — stdio proxy for MCP servers (61 tests)

  tool-optimizer/   # @tscg/tool-optimizer — LangChain, Vercel AI SDK integrations

paper/              # LaTeX source (arXiv version)

cli/                # Unified CLI (compress, benchmark, analyze, info)

benchmark/          # TAB benchmark harness, analysis code, raw data

integrations/       # Framework integration examples

docs/               # Technical documentation

```

## Development

```bash

git clone https://github.com/SKZL-AI/tscg.git

cd tscg

npm install

npm run build

npm test          # 459 tests

npm run typecheck # Type checking

```

## Papers

### Paper 1: TSCG -- Deterministic Tool-Schema Compilation for Agentic LLM Deployments

Furkan Sakizli ([ORCID: 0009-0009-5975-5014](https://orcid.org/0009-0009-5975-5014)). April 2026.

[TSCG-paper.pdf](./TSCG-paper.pdf) -- arXiv preprint (full version, 12 models, ~19,000 API calls, 4-class taxonomy)

LaTeX source is available in [`paper/`](paper/).

### Paper 2: Tool-Schema Compression Enables Agentic RAG Under Constrained Context Budgets

Furkan Sakizli ([ORCID: 0009-0009-5975-5014](https://orcid.org/0009-0009-5975-5014)). May 2026.

[TSCG-RAG-Benchmark-Paper.pdf](./TSCG-RAG-Benchmark-Paper.pdf) -- 14 models, 6,566 API calls, binary enablement at 8K

## Citation

```bibtex

@article{sakizli2026tscg,

  title={TSCG: Deterministic Tool-Schema Compilation for Agentic LLM Deployments},

  author={Sakizli, Furkan},

  year={2026},

  note={arXiv preprint},

  orcid={0009-0009-5975-5014}

}

@article{sakizli2026tscgrag,

  title={Tool-Schema Compression Enables Agentic RAG Under Constrained Context Budgets},

  author={Sakizli, Furkan},

  year={2026},

  note={arXiv preprint},

  orcid={0009-0009-5975-5014}

}

```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines.

## License

[MIT](LICENSE)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/skzl-ai/tscg

Awesome Lists containing this project

README
