promptcompiler-core 0.1.1

The LLVM + MLflow for Prompt Engineering

⚙️ PromptCompiler

The LLVM + MLflow for Prompt Engineering

A production-grade, Python-first, local-first Prompt Compiler platform designed to parse, analyze, optimize, benchmark, and observe LLM prompts like source code.

---

📌 Vision

PromptCompiler treats prompts as structured code, not arbitrary text strings.

Instead of relying on black-box LLM rewrites:

Raw Prompt  ──►  LLM Rewrite  ──►  Unpredictable Output

PromptCompiler executes an explainable, deterministic Compiler Pipeline:

  Raw Prompt
      │
      ▼
┌───────────┐      ┌───────────┐      ┌──────────────────┐      ┌──────────────────────┐
│  Parser   │ ───► │ Prompt IR │ ───► │ Static Analysis  │ ───► │ Optimization Passes  │
└───────────┘      └───────────┘      └──────────────────┘      └──────────────────────┘
                                                                           │
                                                                           ▼
┌───────────┐      ┌───────────┐      ┌──────────────────┐      ┌──────────────────────┐
│  Web UI   │ ◄─── │ Registry  │ ◄─── │ Score & Token    │ ◄─── │  Prompt Renderer     │
│ Dashboard │      │ (SQLite)  │      │ Diff Metrics     │      │ (Markdown/XML/Chat)  │
└───────────┘      └───────────┘      └──────────────────┘      └──────────────────────┘

---

✨ Features

• ⚡ Deterministic Compiler Passes: Deduplicate constraints, normalize passive phrasing, strip conversational fluff, reorder sections for LLM attention hierarchy, and inject anti-hallucination fallback rules.
• 🔍 Static Analysis & Diagnostics: Detect prompt smells, ambiguous objectives, duplicate instructions, over-framing, and missing output schemas.
• 📊 Quality Scoring & AST Diffs: Get multi-dimensional metrics (Specificity, Constraint Quality, Token Efficiency, Hallucination Risk) and Git-style AST diffs with exact token savings calculations.
• 🖥️ Embedded Local Dashboard: Single command (promptc ui) starts FastAPI + React UI on localhost with live split-screen editor, AST tree viewer, and run metrics.
• 🗃️ Local-First SQLite Registry: Track projects, compilation runs, metrics, and prompt versions without cloud dependencies, SaaS subscriptions, or telemetry.
• 🔌 Extensible Plugin System: Register custom compiler passes, analyzers, evaluators, and renderers via standard Python entry points.

---

🚀 Quick Start

1. Installation

Install via pip:

pip install promptcompiler-core

2. Workspace Initialization

Initialize local .promptcompiler/ workspace and SQLite database:

promptc init

3. Command Line Interface (promptc)

Compile a Prompt

Optimize prompt file, strip fluff, deduct duplicate constraints, and calculate token savings:

promptc compile prompt.md -o compiled_prompt.md

Run Static Diagnostics

Inspect prompt smells and quality issues with Rich terminal formatting:

promptc analyze prompt.md

Start Web UI Dashboard

Launch FastAPI backend and open the interactive Web UI on http://127.0.0.1:8501:

promptc ui

---

🐍 Python SDK Guide

Use PromptCompiler programmatically in Python applications:

from promptcompiler import PromptCompiler

# Initialize compiler client
compiler = PromptCompiler(project_name="my_app")

raw_prompt = """
# Role
Senior Software Engineer

# Task
Try to summary this file as best as you can please.

# Constraints
- Keep output concise
- Keep output concise
"""

# Compile prompt through pipeline
result = compiler.compile(raw_prompt)

# Print compiled prompt & metrics
print("=== COMPILED PROMPT ===")
print(result.compiled_prompt)

print(f"\nOverall Score: {result.score.overall_score}/100")
print(f"Token Savings: {result.diff.token_savings} tokens")
print(f"Hallucination Risk: {result.score.hallucination_risk}/100")

# Access AST / PromptIR
ir = result.compiled_ir
print("Target Role:", ir.role)
print("Constraints Count:", len(ir.constraints))

# Render to ChatML, XML, or JSON format
chatml_str = compiler.render(ir, format_type="chatml")
xml_str = compiler.render(ir, format_type="xml")

---

⚙️ Architecture & Data Structures

Prompt Intermediate Representation (PromptIR)

The central AST structure representing structured prompt components:

class PromptIR(BaseModel):
    version: str = "1.0"
    role: Optional[str] = None
    task: Optional[str] = None
    objective: Optional[str] = None
    context: List[str] = []
    constraints: List[Constraint] = []
    examples: List[Example] = []
    variables: List[Variable] = []
    reasoning: ReasoningSpec
    output_schema: OutputSchema
    formatting_rules: List[str] = []
    metadata: Dict[str, Any] = {}

Built-in Optimization Passes

Each compiler pass accepts a PromptIR and yields an optimized PromptIR along with transformation metadata:

Pass Name	Description
CompressPrompt	Strips conversational preamble, politeness fluff, and redundant whitespace.
RemoveDuplicateInstructions	Deduplicates identical constraint directives.
NormalizeLanguage	Replaces passive/weak directives ("try to") with direct imperative rules ("Ensure to").
ReorderSections	Enforces canonical LLM attention layout (Role -> Task -> Constraints -> Context -> Schema).
HallucinationReduction	Injects grounding constraints and explicit fallback rules for unknown context.

---

🛠️ CLI Reference

Command	Arguments / Options	Description
promptc init	[--directory]	Initialize workspace & SQLite registry.
promptc compile	<file_path> [-o output]	Compile prompt file and display score & diffs.
promptc analyze	<file_path>	Run static analysis diagnostics on prompt.
promptc ui	[--host] [--port]	Start local FastAPI server & open Web Dashboard.
promptc serve	[--host] [--port]	Serve REST API endpoints.
promptc doctor	None	Run system environment diagnostics.

---

🔌 Extensibility & Plugin System

Custom compiler passes can be registered using PluginManager or entry points in your pyproject.toml:

from promptcompiler.optimizer.base import BaseCompilerPass, PassResult
from promptcompiler.ir.models import PromptIR

class CustomSecurityPass(BaseCompilerPass):
    pass_name = "CustomSecurityPass"
    description = "Inject custom security rules"

    def run(self, ir: PromptIR) -> tuple[PromptIR, PassResult]:
        # Custom AST transformation logic
        return ir, PassResult(pass_name=self.pass_name, applied=True)

---

📜 License

PromptCompiler is released under the MIT License.