Metadata-Version: 2.4
Name: prlyn
Version: 0.1.1
Summary: A powerful, extensible tool for analyzing LLM prompts.
Project-URL: Homepage, https://github.com/Mishtert/prlyn
Project-URL: Repository, https://github.com/Mishtert/prlyn
Author: prlyn Contributors
License: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: mcp>=0.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: sentence-transformers>=2.2.2
Requires-Dist: spacy>=3.7.0
Requires-Dist: structlog>=25.5.0
Requires-Dist: tiktoken>=0.7.0
Description-Content-Type: text/markdown

# prlyn (Prompt Linter)

[![PyPI version](https://img.shields.io/pypi/v/prlyn.svg)](https://pypi.org/project/prlyn/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/Mishtert/prlyn/actions/workflows/ci.yml/badge.svg)](https://github.com/Mishtert/prlyn/actions/workflows/ci.yml)
[![Downloads](https://static.pepy.tech/badge/prlyn)](https://pepy.tech/project/prlyn)

**prlyn** is a professional-grade static analysis tool for LLM prompts. Beyond basic linting, it provides a comprehensive suite of linguistic, security, and model-specific metrics to ensure your prompts are robust, efficient, and safe for production.

---

## 🌟 Why prlyn?

Developing effective prompts is often trial-and-error. prlyn brings **Engineering Rigor** to Prompt Engineering by:
- **Quantifying Quality**: Move from "it feels slow" to "Actionable Ratio is 0.45".
- **Detecting Vulnerabilities**: Identify design-time security flaws before they become runtime liabilities.
- **Ensuring Model Fit**: Adjust scores based on whether you are targeting GPT-4, Claude, or legacy models.
- **Preventing Regression**: Track metrics over time as you iterate on complex system instructions.

---

## 🚀 Key Features

### 1. Design-time Security (Prompt Shield)
prlyn doesn't just detect attacks; it flags **vulnerability patterns** in your system prompts:
- **Delimiter Analysis**: Verifies strong separation between instructions and user data.
- **Defensive Anchors**: Checks for mandatory safety instructions and negative constraints.
- **Reflexive Leakage**: Identifies instructions that might inadvertently reveal your prompt's inner workings.

### 2. Advanced Linguistics
- **Flow Cohesion**: Uses semantic embeddings to detect "logical jumps" or disjointed instructions that confuse models.
- **Instructional Strength**: Quantifies the assertiveness of your commands using weighted verb analysis (e.g., *Must* vs. *Try*).
- **Position Scoring**: Detects the "lost middle" phenomenon by measuring instructional density at the context window's edges.

### 3. Model-Aware Intelligence
Use the `--model` flag to tailor analysis to specific LLM quirks:
- **GPT-4**: Penalizes "buried" instructions more heavily due to known recency bias.
- **Claude 3.5**: Adjusts thresholds for excellent long-context retrieval capabilities.

### 4. Prompt Shadowing (Iterative Development)
- **Automatic History**: Every scan is stored in a hidden `.prlyn/` directory.
- **Regression Detection**: Use `prlyn --diff` to compare your current draft against the previous version and see how your scores changed.

---

## 🚀 Quick Start (CLI)

For **human users** who want to manually scan a prompt. No installation required.

```bash
# Basic analysis
uvx --from git+https://github.com/Mishtert/prlyn prlyn "Your prompt here..."

# Show all options
uvx --from git+https://github.com/Mishtert/prlyn prlyn --help
```

---

## 🛠 Usage

### CLI Usage
```bash
# Basic analysis (if already running via uvx as shown above)
uvx --from git+https://github.com/Mishtert/prlyn prlyn "Your prompt here..."
```

# Model-specific analysis
prlyn "..." --model gpt-4

# 1. Run analysis (saved automatically)
prlyn "Initial draft..."

# 2. Iterate and compare against your last run
prlyn "Improved draft..." --diff
---

---

## 🤖 For AI Agents (MCP Server)

For **AI Assistants** (Claude, Cursor, Antigravity) to self-correct and optimize prompts.

#### 1. Claude Desktop
Add this to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "prlyn": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Mishtert/prlyn",
        "prlyn"
      ]
    }
  }
}
```

#### 2. Cursor
1. Go to **Settings** > **Cursor Settings** > **Features** > **MCP**.
2. Click **+ Add New MCP Server**.
3. Name: `prlyn`
4. Type: `command`
5. Command: `uvx --from git+https://github.com/Mishtert/prlyn prlyn`

#### 3. Antigravity
Add the following to your MCP configuration:
```json
{
  "mcpServers": {
    "prlyn": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Mishtert/prlyn",
        "prlyn"
      ]
    }
  }
}
```

#### 4. Automated Rewriting
prlyn supports **self-correction workflows**. Your agent can:
1.  Call `prlyn.analyze_prompt(prompt)` to get a quality score.
2.  If the score is low, call `prlyn.get_improvement_template(prompt)`.
3.  Use the returned **Actionable Template** to rewrite its own prompt.

---

## 🔭 Technical Details

- **NLP Engine**: Spacy (`en_core_web_sm`) for linguistic structure and POS tagging.
- **Embeddings**: SentenceTransformers (`all-MiniLM-L6-v2`) for semantic similarity and flow analysis.
- **Tokenizer**: `tiktoken` for accurate token budget estimation.

---

## 💻 For Developers

If you want to contribute to **prlyn**:

```bash
# Clone the repository
git clone https://github.com/Mishtert/prlyn.git
cd prlyn

# Install dependencies and setup environment
uv sync

# Run pipeline locally
uv run pytest
uv run pre-commit run --all-files
```

### CI/CD Pipeline
Every PR triggers a 4-stage pipeline:
1.  **Quality**: Linting (`ruff`) and Type Checking (`mypy`).
2.  **Security**: Vulnerability scanning (`bandit`).
3.  **Test**: Unit tests (`pytest`).
4.  **Build**: Package verification (`uv build`).

Refer to [CONTRIBUTING.md](https://github.com/Mishtert/prlyn/blob/main/CONTRIBUTING.md) for more details.

---

## 🔒 Privacy & Telemetry
**prlyn respects your privacy.**
- **No Home**: prlyn does not send any data to external servers.
- **Local Analysis**: All NLP and scanning happens locally on your machine.
- **Usage Tracking**: We rely solely on public [PyPI download stats](https://pepy.tech/project/prlyn) to gauge interest.
