Metadata-Version: 2.4
Name: pagans
Version: 0.1.3
Summary: Prompts Aligned to Guidelines and Normalization System for OpenAI, Anthropic, xAI, and Google models
Author-email: Abu Bakar Siddik <abubakar1808031@gmail.com>
Maintainer-email: Abu Bakar Siddik <abubakar1808031@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/abubakarsiddik31/pagans
Project-URL: Documentation, https://pagans.readthedocs.io/
Project-URL: Repository, https://github.com/abubakarsiddik31/pagans
Project-URL: Issues, https://github.com/abubakarsiddik31/pagans/issues
Project-URL: Discussions, https://github.com/abubakarsiddik31/pagans/discussions
Project-URL: Changelog, https://github.com/abubakarsiddik31/pagans/blob/main/CHANGELOG.md
Project-URL: Source Code, https://github.com/abubakarsiddik31/pagans
Project-URL: Download, https://pypi.org/project/pagans/
Project-URL: Bug Reports, https://github.com/abubakarsiddik31/pagans/issues
Project-URL: Contributing, https://github.com/abubakarsiddik31/pagans/blob/main/CONTRIBUTING.md
Project-URL: Security, https://github.com/abubakarsiddik31/pagans/blob/main/SECURITY.md
Project-URL: Support, https://github.com/abubakarsiddik31/pagans/blob/main/SUPPORT.md
Keywords: ai,llm,prompt,optimization,openai,anthropic,claude,google,gemini,xai,grok,openrouter,machine-learning,nlp,artificial-intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pydantic>=2.11.7
Requires-Dist: python-dotenv>=1.1.1
Provides-Extra: dev
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-asyncio>=1.1.0; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: jupyterlab>=4.2.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
Dynamic: license-file

# PAGANS - Prompt Optimization Framework

<div align="center">
  <img src="logo.png" alt="PAGANS Logo" width="180" />
</div>

[![PyPI version](https://badge.fury.io/py/pagans.svg)](https://pypi.org/project/pagans/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build](https://github.com/abubakarsiddik31/pagans/actions/workflows/build.yml/badge.svg)](https://github.com/abubakarsiddik31/pagans/actions/workflows/build.yml)
[![Test](https://github.com/abubakarsiddik31/pagans/actions/workflows/test.yml/badge.svg)](https://github.com/abubakarsiddik31/pagans/actions/workflows/test.yml)
[![Lint](https://github.com/abubakarsiddik31/pagans/actions/workflows/lint.yml/badge.svg)](https://github.com/abubakarsiddik31/pagans/actions/workflows/lint.yml)

PAGANS (Prompts Aligned to Guidelines and Normalization System) is a prompt
optimization framework for LLM applications. It adapts prompts to the target
model family automatically so the same prompt can perform better across
OpenAI, Anthropic, Google, and xAI model series through OpenRouter.

## ✨ Features

- 🚀 Fast prompt optimization for production workflows
- 🎯 Family-aware optimization for OpenAI, Anthropic, Google, and xAI models
- 🔍 Automatic model-family detection from short and provider-prefixed names
- ⚡ Async-first API for single, compare, and batch operations
- 🧠 Built-in caching to reduce repeated optimization cost
- 🛠️ CLI support for optimize, compare, and batch workflows
- 🔗 Unified OpenRouter integration path

## Installation

```bash
pip install pagans
```

## Quick Start

```python
import asyncio
from pagans import PAGANSOptimizer


async def main() -> None:
    async with PAGANSOptimizer() as optimizer:
        result = await optimizer.optimize(
            prompt="Write a robust retry policy for external API calls.",
            target_model="openai/gpt-4o",
        )
        print(result.optimized)


asyncio.run(main())
```

Required environment variable:

```bash
export OPENROUTER_API_KEY="your-openrouter-api-key"
```

Optional environment variables:

```bash
export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
export PAGANS_OPTIMIZER_MODEL="openai/gpt-4o-mini"
```

## CLI

PAGANS installs a CLI as `pagans`.

```bash
pagans optimize --prompt "Explain quantum computing for beginners" --target-model gpt-4o
```

```bash
pagans compare \
  --prompt "Design an event-driven order system" \
  --models "gpt-4o,claude-sonnet-4,gemini-2.5-pro"
```

```bash
pagans batch --prompts-file ./prompts.txt --target-model gemini-2.5-pro
```

## 🎯 Model Family Series

PAGANS optimizes prompts for these model families and series:

- OpenAI GPT series
- Anthropic Claude series
- Google Gemini series
- xAI Grok series

PAGANS detects the target model family and applies the matching optimization strategy automatically.

## Links

- Source: https://github.com/abubakarsiddik31/pagans
- Issues: https://github.com/abubakarsiddik31/pagans/issues

## License

MIT
