promptclarity-sdk 0.1.1

A quality, clarity, and risk validation SDK for LLM inputs.

PromptClarity SDK

Guard prompts before they become bad outputs.

PromptClarity SDK is a pre-LLM validation layer that detects unclear, incomplete, risky, or low-quality prompts before they reach an AI system.

Positioning

PromptClarity SDK helps teams validate LLM inputs for:

• prompt quality scoring
• missing context detection
• ambiguity detection
• dataset metadata validation
• agent-readiness checks
• RAG-readiness checks
• cost and token waste reduction
• safer enterprise AI workflows

Rule Coverage

PromptClarity currently uses 250+ deterministic rule signals across:

• vague prompt wording
• missing objective, audience, constraints, timeframe, examples, and success criteria
• dataset details and privacy handling
• output format and analysis type detection
• evaluation and selection criteria
• RAG source/citation readiness
• agent/tool boundary readiness
• sensitive-data patterns such as emails, phone numbers, SSNs, API keys, tokens, private keys, IPs, and cards
• unsafe-intent terms such as phishing, malware, prompt injection, SQL injection, credential theft, and bypass attempts

Enterprise tagline:

A quality, clarity, and risk validation SDK for LLM inputs.

Install

pip install promptclarity-sdk

Usage

from promptclarity import PromptClarity

guard = PromptClarity()

result = guard.validate("Analyze this data and give insights")

print(result.to_dict())

Optional LLM Assistance

PromptClarity can run in two modes:

1. Rule-only mode: default, local, deterministic, no API key, no network call.
2. LLM-assisted mode: optional semantic review using an LLM advisor that you provide.

PromptClarity does not choose, bundle, or call an LLM provider by itself. Your application decides which provider and model to use, then passes a callback to the SDK.

You can use any model/provider, including:

• OpenAI
• Anthropic Claude
• Google Gemini
• Mistral
• Groq
• Ollama or other local models
• Azure OpenAI
• private/internal enterprise models
• any custom API that your application can call

Who Decides What?

• Your app decides the LLM provider and model.
• Your app owns API keys, auth, network calls, retries, and provider-specific SDKs.
• PromptClarity decides the baseline score, status, risk level, and rule findings.
• The optional LLM advisor only adds semantic missing items and recommendations.
• No LLM call happens unless use_llm=True.
• If use_llm=True, an llm_advisor callback is required.

The LLM advisor can return a plain dictionary or an LLMReport.

from promptclarity import PromptClarity, LLMReport


def my_llm_advisor(prompt, *, metadata=None):
    # Call your chosen LLM here:
    # - OpenAI
    # - Claude
    # - Gemini
    # - Ollama/local model
    # - internal enterprise model
    # - any other provider
    #
    # Then normalize the model response into this shape.
    return {
        "model": "your-model-name",
        "confidence": 0.86,
        "missing_items": ["domain assumptions"],
        "recommendations": ["Clarify the assumptions the model should use."],
    }


guard = PromptClarity(llm_advisor=my_llm_advisor)
result = guard.validate("Analyze this data", use_llm=True)

print(result.to_dict())

Expected advisor return shape:

{
    "model": "provider-model-name",
    "confidence": 0.86,
    "missing_items": ["domain assumptions"],
    "recommendations": ["Clarify the assumptions the model should use."],
}

The same result can be returned as an LLMReport:

from promptclarity import LLMReport


def my_llm_advisor(prompt, *, metadata=None):
    return LLMReport(
        model="your-model-name",
        confidence=0.86,
        missing_items=["domain assumptions"],
        recommendations=["Clarify the assumptions the model should use."],
    )

Why PromptClarity Does Not Pick the LLM

Different teams have different constraints:

• cost
• latency
• privacy
• compliance
• deployment region
• model quality
• internal vendor policy
• local/offline requirements

Because of that, PromptClarity stays provider-agnostic. It gives you the validation interface; your application chooses the model.

Example output:

{
    "status": "needs_clarification",
    "prompt_score": 42,
    "risk_level": "low",
    "missing_items": [
        "success criteria",
        "dataset details",
        "business objective",
        "output format",
    ],
    "recommendations": [
        "Define the success criteria for a useful answer.",
        "Describe the dataset, including source, fields, and size.",
        "State the business objective or decision the answer should support.",
        "Define the expected output format.",
        "Specify the type of analysis required.",
        "Mention whether you need EDA, prediction, reporting, or recommendations.",
    ],
}

Package Layout

promptclarity/
|-- analyzer.py          # prompt quality analyzer
|-- rules.py             # rule-based checks
|-- risk.py              # unsafe / sensitive / vague input checks
|-- metadata.py          # dataset/file metadata analysis
|-- recommender.py       # missing-detail suggestions
|-- prompt_builder.py    # improved prompt generator
|-- llm.py               # optional LLM advisor interface
`-- __init__.py

Development

python -m pytest

Release Checklist

1. Update the version in pyproject.toml and promptclarity/__init__.py.
2. Run python -m pytest.
3. Build with python -m build.
4. Check the distribution with python -m twine check dist/*.
5. Upload to TestPyPI first, then PyPI.