A deterministic, LM-free compiler for prompts modelled as an AST/IR.
promptc parses a prompt into a typed intermediate representation, runs a
fixed-order pipeline of optimization passes — each with stated preconditions,
postconditions, a determinism proof sketch, and a behavior-preservation
argument — and emits the optimized prompt back into the chosen surface format.
The compile path never calls a language model. Same input bytes + same compiler version = same output bytes. Behavior preservation is empirically validated via the routerlab eval harness on crisp tasks (classification, extractive QA) using paired statistical-equivalence tests.
Save this to prompt.md:
# Task
Summarize the input passage in one sentence. In order to keep the summary tight, due to the fact that brevity matters, prior to writing, take into account the main topic.Run:
promptc optimize --target=cost --in prompt.mdOutput (stdout):
## Task
Summarize the input passage in one sentence. To keep the summary tight, because brevity matters, before writing, consider the main topic.Summary (stderr):
pass whitespace_redundancy_strip applied -2 tok
pass vocab_simplification applied -4 tok
tokens: 32 -> 23 (-9, -28.1%)
bytes: 179 -> 147
Five more runnable prompts in examples/, one per pass.
# Global:
npm install -g @promptc/cli
# Per-project dev dependency:
npm install --save-dev @promptc/cli
# Or run without installing:
npx --yes @promptc/cli --helpThe published CLI runs on Node.js >=20 and has no runtime dependencies beyond
the @promptc/* workspace packages. This repository still uses Bun for local
workspace orchestration and tests.
- Quickstart — 5-minute tutorial, install through first optimized prompt.
- Adoption — CI, build-step, and team rollout patterns for prompt repositories.
- Benchmarks — before/after examples with token savings and behavior-preservation checks.
- Passes — per-pass deep dive: preconditions, postconditions, behavior-preservation argument, when to disable.
- IR — the typed
PromptIRfor library consumers. - Comparisons — placement vs SAMMO, DSPy, LLMLingua, ctxray; the 2x2 of deterministic-vs-stochastic and LM-free-vs-LM-in-the-loop.
- Design — the full design contract: IR types, pass framework, eval methodology, non-goals.
- Examples — five runnable prompts, one per pass.
dead_instruction_elimination— drop instructions not referenced by the output schema, retained examples, or other retained instructions.example_pruning_by_mutual_info— cluster few-shot examples by pairwise Jaccard input-side similarity; keep one representative per cluster.format_collapse— collapse verbose markdown/XML formatting where provably whitespace-insensitive.whitespace_redundancy_strip— trim trailing whitespace, collapse blank-line runs, strip filler openers. Fence-aware.vocab_simplification— rewrite verbose phrases to short equivalents from a curated, versioned map.
Each pass declares preconditions. If unmet, the pass is skipped and logged
in metadata.passLog. No pass ever runs an LLM.
# List passes:
promptc passes
# Dry-run a single pass:
promptc explain --in prompt.md --pass=vocab_simplification
# Run a specific subset, in order:
promptc optimize --target=cost \
--passes=dead_instruction_elimination,whitespace_redundancy_strip \
--in prompt.mdPrompt optimization that calls an LM at compile time has three structural
problems in production systems: it pays the run-time price at compile time,
turns compile latency into minutes, and breaks reproducibility (same input
compiles to different output). promptc preserves the engineering posture
every other compiler enjoys: same source bytes + same compiler version =
same artifact. The IR, the passes, the eval methodology — everything is in
service of that property.
- Not a prompt-compression library. LLMLingua / LongLLMLingua /
LLMLingua-2 own that niche; their best regime is long contexts and their
mechanism is learned scoring.
promptcnever frames itself as compression — cost reduction is a byproduct of structural simplification. - Not a prompt-search system. SAMMO / EvoPrompt / AutoPrompt / APO /
APE / OPRO own search.
promptchas no search loop, no candidate evaluation, no iterative refinement. - Not an LM-in-the-loop optimizer. DSPy / MIPRO / OpenAI Prompt
Optimizer / MLflow Prompt Optimization / PRewrite / TextGrad own that
posture.
promptc's compile path is provably LM-free. - Not a soft-prompt or weight-tuning framework. AutoCompressors and
continuous-prefix-tuning methods operate on model internals.
promptcnever touches weights, embeddings, or continuous vectors. - Not a prompt-versioning ops platform. Agenta / LangSmith / Promptfoo
/ Helicone do prompt versioning + observability.
promptcis a transformation library that composes underneath those platforms. - Not a multi-call agent orchestration framework. LangGraph / LangChain
agents / CrewAI / AutoGen / SAMMO operate at the program-graph layer.
promptcoperates over one prompt at a time.
See docs/COMPARISONS.md for the 2x2 placement.
The @promptc/* packages are published and usable for deterministic prompt
compilation workflows. Public APIs may still evolve as the pass set expands,
but documented behavior is tested and release-managed through Changesets.
This repo's docs and examples describe how to adopt the published packages
without requiring a source checkout.
bun install
bun test # unit + integration tests
bun run eval:regression # paired-bootstrap behavior-preservation harness@misc{promptc-2026,
author = {Faraazuddin Mohammed},
title = {{promptc}: A Compiler for Cost-Aware Prompt Optimization},
year = {2026},
howpublished = {\url{https://github.com/faraa2m/promptc}}
}