Freesha

• 

  .ico

Inspiration

LLM workflows quietly accumulate a context tax: repeated tool output, verbose JSON, stale history, and duplicated context are sent again and again. That raises input cost and latency, but deleting context blindly can remove the detail a model or developer needs later.

Freesha started with a simple question: can we make deterministic context smaller without making it irreversible or untrustworthy?

What it does

Freesha is a local-first context economy layer for OpenAI-compatible workflows. It reduces avoidable deterministic input context before a host application sends a request, while keeping omitted data recoverable locally and producing an auditable receipt.

The working CLI can:

• minify JSON losslessly;
• compact repetitive tool and log output while preserving critical lines;
• deduplicate byte-identical optional context;
• prioritize required and task-relevant context under a token budget;
• pass through input when optimization would be a net loss;
• store omitted data locally for exact recovery;
• prepare documented GPT-5.6 prompt-cache fields for stable reusable prefixes.

The bundled offline benchmark is reproducible. With the dependency-free estimator it reduces the committed mixed fixture from 7,475 to 1,743 estimated input tokens (76.68%); with optional tiktoken/o200k_base, the same fixture is 8,819 to 1,800 (79.59%). These are workload-specific local estimates, not universal savings promises or provider billing receipts.

Experimental JOY preview

The latest extension is JOY — Justify, Optimize, Yield. JOY is a local, deterministic, fixture-only --dry-run router. It first estimates the optimized local context, then filters synthetic model fixtures using hard quality, capability, privacy, data-class, latency, and budget constraints. It ranks eligible candidates by projected input cost, latency tier, and model ID, and returns a receipt with rejection reasons and higher-quality fallbacks.

JOY cannot send provider requests, spend money, or claim live model availability or pricing. The catalog is intentionally synthetic. Live routing is future work.

How we built it

We built Freesha as a dependency-light Python CLI so judges can install and test it locally without an API key. The core combines deterministic transformations, a local content store, recovery handles, receipts, and quality gates. The JOY extension adds a bounded routing module, committed fixture files, a public judge path, and regression tests.

A judge can run the project directly:

python3 -m unittest discover -s tests -v
python3 freesha_core.py benchmark
python3 freesha_core.py joy examples/joy_task.json --models examples/joy_models.fixture.json --dry-run

Built With

• api-design
• ast
• automation
• data-processing
• json
• middleware
• openai-api
• prompt-engineering
• python