Why this package exists

Even well-crafted prompts can suffer from hidden flaws like ambiguity, lack of context, or weak constraints.

@promptforgee/analyzer provides a static analysis engine for prompts. It evaluates your prompt text and returns a structured diagnostic report detailing its strengths, weaknesses, and a quantitative score. This empowers you to identify issues before wasting tokens on poor LLM inferences.

[!NOTE] The current engine uses a fast, heuristic-based approach. It is designed to be easily swappable with an LLM-based analysis engine in the future without breaking the API contract.

Features

• Heuristic Engine: Fast, local evaluation without network latency.
• Detailed Diagnostics: Highlights missing constraints, context gaps, and ambiguity.
• Scoring System: Receive a numeric score (0-100) to benchmark prompt quality.
• Actionable Feedback: Get specific recommendations for improvement.

Installation

# npm
npm install @promptforgee/analyzer

# pnpm
pnpm add @promptforgee/analyzer

# yarn
yarn add @promptforgee/analyzer

# bun
bun add @promptforgee/analyzer

Quick Start

import { analyzePrompt } from '@promptforgee/analyzer';

async function main() {
  const promptText = 'Write a function to sort an array. Make it fast.';

  const report = await analyzePrompt(promptText);

  console.log(`Score: ${report.score}/100`);
  // Score: 30/100

  console.log('Strengths:', report.strengths);
  // Strengths: [ 'Has a clear action verb.' ]

  console.log('Weaknesses:', report.weaknesses);
  // Weaknesses: [ 'Missing clear constraints.', 'Lacks context about the input data type.' ]

  console.log('Suggestions:', report.suggestions);
  // Suggestions: [ 'Specify the expected time complexity (e.g., O(n log n)).', 'Define the type of elements in the array.' ]
}

main();

API Overview

analyzePrompt(promptText: string): Promise<AnalysisReport>

The primary exported function. Analyzes a raw prompt string and returns a comprehensive report.

HeuristicAnalyzer

The underlying class implementing the PromptAnalyzer interface. You can instantiate this directly if you prefer an object-oriented approach.

| Method | Description | | ---------------------- | ----------------------------------------------------- | | .analyze(promptText) | Evaluates the prompt and returns an AnalysisReport. |

AnalysisReport (Interface)

The structured output of the analysis.

| Property | Type | Description | | ------------- | ---------- | ----------------------------------------------- | | score | number | A normalized score from 0 to 100. | | strengths | string[] | A list of positive aspects of the prompt. | | weaknesses | string[] | A list of identified flaws or missing elements. | | suggestions | string[] | Actionable steps to improve the prompt. |

Real-world Example

Integrating the analyzer into a CI/CD pipeline or a local testing script to ensure baseline prompt quality:

import { analyzePrompt } from '@promptforgee/analyzer';
import { Prompt } from '@promptforgee/core';

// Assume this is built via @promptforgee/core
const myPrompt = Prompt.create().task('Generate a weekly report summary').build();

const report = await analyzePrompt(myPrompt);

if (report.score < 80) {
  throw new Error(
    `Prompt quality check failed! Score: ${report.score}. Suggestions: ${report.suggestions.join(', ')}`,
  );
}

Ecosystem

@promptforgee/analyzer works best when evaluating prompts generated by @promptforgee/core.

@promptforgee/core (Builds the prompt) ↓ @promptforgee/analyzer (You are here) ↓ @promptforgee/optimizer (Automatically fixes issues) ↓ @promptforgee/registry (Stores the improved prompt)

Documentation

For full documentation and advanced usage, visit promptforge.dev/docs/analyzer.

Examples

Check out our Examples directory for more real-world use cases.

Roadmap

• 🚧 LLM-backed analysis engine (OpenAI / Anthropic support)
• 🚧 Custom heuristic rules injection
• 🚧 Integration with ESLint for inline prompt linting

Contributing

We welcome contributions! Please read our Contributing Guide to get started.

License

MIT © Omnikon-Org