Metadata-Version: 2.4
Name: promptclarity-sdk
Version: 0.1.1
Summary: A quality, clarity, and risk validation SDK for LLM inputs.
Author: PromptClarity
License-Expression: MIT
Project-URL: Homepage, https://github.com/promptclarity/promptclarity-sdk
Project-URL: Issues, https://github.com/promptclarity/promptclarity-sdk/issues
Project-URL: Source, https://github.com/promptclarity/promptclarity-sdk
Keywords: llm,prompt,prompt-quality,clarity,validation,prompt-engineering,rag,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install promptclarity-sdk
```

## Usage

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

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

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

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

```python
{
    "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

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

```bash
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.
