Metadata-Version: 2.4
Name: promptcompiler-core
Version: 0.1.1
Summary: The LLVM + MLflow for Prompt Engineering
Author: PromptCompiler Contributors
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.28.0
Requires-Dist: typer>=0.12.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: sqlalchemy>=2.0.28
Requires-Dist: alembic>=1.13.1
Requires-Dist: litellm>=1.30.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: tiktoken>=0.6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: networkx>=3.2.1
Requires-Dist: jinja2>=3.1.3
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: structlog>=24.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: hypothesis>=6.98.0; extra == "dev"
Dynamic: license-file

<div align="center">

# ⚙️ PromptCompiler

### *The LLVM + MLflow for Prompt Engineering*

[![PyPI version](https://img.shields.io/pypi/v/promptcompiler-core.svg?color=blue)](https://pypi.org/project/promptcompiler-core/)
[![Python Versions](https://img.shields.io/pypi/pyversions/promptcompiler-core.svg)](https://pypi.org/project/promptcompiler-core/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

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

---

</div>

## 📌 Vision

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

Instead of relying on black-box LLM rewrites:

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

PromptCompiler executes an explainable, deterministic **Compiler Pipeline**:

```text
  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:

```bash
pip install promptcompiler-core
```

### 2. Workspace Initialization

Initialize local `.promptcompiler/` workspace and SQLite database:

```bash
promptc init
```

### 3. Command Line Interface (`promptc`)

#### Compile a Prompt
Optimize prompt file, strip fluff, deduct duplicate constraints, and calculate token savings:

```bash
promptc compile prompt.md -o compiled_prompt.md
```

#### Run Static Diagnostics
Inspect prompt smells and quality issues with Rich terminal formatting:

```bash
promptc analyze prompt.md
```

#### Start Web UI Dashboard
Launch FastAPI backend and open the interactive Web UI on `http://127.0.0.1:8501`:

```bash
promptc ui
```

---

## 🐍 Python SDK Guide

Use `PromptCompiler` programmatically in Python applications:

```python
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:

```python
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`:

```python
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**.
