feat(core): add multi-provider support for prompt optimization

Expand the framework to support OpenAI, Anthropic, Google AI Studio,
and Z.ai as optimizer providers alongside OpenRouter. This change
introduces specific client implementations, provider-aware
environment variable handling, and updated CLI flags to select the
active backend.

Key changes:
- Add Anthropic, OpenAI, Google, and Z.ai client implementations
- Implement shared OpenAICompatibleClient for standard endpoints
- Update PAGANSOptimizer to handle provider-specific configurations
- Enhance CLI with --provider and corresponding environment variables
- Add provider-specific Jupyter notebooks and updated documentation

Author: abubakarsiddik31

.env.example

@@ -1,3 +1,16 @@
 OPENROUTER_API_KEY=
-DEFAULT_PAGANS_OPTIMIZER_MODEL=
-OPENROUTER_BASE_URL=
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+
+OPENAI_API_KEY=
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+GOOGLE_API_KEY=
+GOOGLE_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+
+ANTHROPIC_API_KEY=
+ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
+
+ZAI_API_KEY=
+ZAI_BASE_URL=https://api.z.ai/api/paas/v4
+
+PAGANS_OPTIMIZER_MODEL=

README.md

@@ -14,17 +14,17 @@
 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.
+OpenAI, Anthropic, Google, and xAI model series.
 
-## ✨ Features
+## 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
+- 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
+- Optimizer provider support for OpenRouter, OpenAI, Google AI Studio, Anthropic, and Z.ai
 
 ## Installation
 
@@ -36,11 +36,12 @@ pip install pagans
 
 ```python
 import asyncio
-from pagans import PAGANSOptimizer
+
+from pagans import PAGANSOptimizer, Provider
 
 
 async def main() -> None:
-    async with PAGANSOptimizer() as optimizer:
+    async with PAGANSOptimizer(provider=Provider.OPENROUTER) as optimizer:
         result = await optimizer.optimize(
             prompt="Write a robust retry policy for external API calls.",
             target_model="openai/gpt-4o",
@@ -51,38 +52,76 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-Required environment variable:
+## Provider Configuration
+
+Set one provider key (or pass `api_key` and `base_url` explicitly).
 
 ```bash
+# OpenRouter
 export OPENROUTER_API_KEY="your-openrouter-api-key"
-```
+export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
 
-Optional environment variables:
+# OpenAI
+export OPENAI_API_KEY="your-openai-api-key"
+export OPENAI_BASE_URL="https://api.openai.com/v1"
 
-```bash
-export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
+# Google AI Studio (Gemini OpenAI-compatible endpoint)
+export GOOGLE_API_KEY="your-gemini-api-key"
+export GOOGLE_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai"
+
+# Anthropic
+export ANTHROPIC_API_KEY="your-anthropic-api-key"
+export ANTHROPIC_BASE_URL="https://api.anthropic.com/v1"
+
+# Z.ai
+export ZAI_API_KEY="your-zai-api-key"
+export ZAI_BASE_URL="https://api.z.ai/api/paas/v4"
+
+# Optional global override for optimizer model
 export PAGANS_OPTIMIZER_MODEL="openai/gpt-4o-mini"
 ```
 
+### Python Provider Examples
+
+```python
+from pagans import PAGANSOptimizer, Provider
+
+# OpenAI as optimizer provider
+optimizer = PAGANSOptimizer(provider=Provider.OPENAI)
+
+# Google AI Studio as optimizer provider
+optimizer = PAGANSOptimizer(provider=Provider.GOOGLE)
+
+# Anthropic as optimizer provider
+optimizer = PAGANSOptimizer(provider=Provider.ANTHROPIC)
+
+# Z.ai as optimizer provider
+optimizer = PAGANSOptimizer(provider=Provider.ZAI)
+```
+
 ## CLI
 
 PAGANS installs a CLI as `pagans`.
 
 ```bash
-pagans optimize --prompt "Explain quantum computing for beginners" --target-model gpt-4o
+pagans --provider openrouter optimize \
+  --prompt "Explain quantum computing for beginners" \
+  --target-model gpt-4o
 ```
 
 ```bash
-pagans compare \
+pagans --provider openai 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
+pagans --provider anthropic batch \
+  --prompts-file ./prompts.txt \
+  --target-model gemini-2.5-pro
 ```
 
-## 🎯 Model Family Series
+## Model Family Series
 
 PAGANS optimizes prompts for these model families and series:
 
@@ -93,6 +132,17 @@ PAGANS optimizes prompts for these model families and series:
 
 PAGANS detects the target model family and applies the matching optimization strategy automatically.
 
+## Notebooks
+
+Provider notebook examples are available in [`notebooks/`](./notebooks):
+
+- `pagans_quickstart.ipynb`
+- `pagans_openrouter_optimizer.ipynb`
+- `pagans_openai_optimizer.ipynb`
+- `pagans_google_optimizer.ipynb`
+- `pagans_anthropic_optimizer.ipynb`
+- `pagans_zai_optimizer.ipynb`
+
 ## Links
 
 - Source: https://github.com/abubakarsiddik31/pagans

docs/CLI.md

@@ -1,37 +1,46 @@
 # PAGANS CLI
 
-The `pagans` command provides a terminal interface for prompt optimization through OpenRouter.
+The `pagans` command provides a terminal interface for prompt optimization across providers.
 
 ## Global Flags
 
-- `--api-key`: OpenRouter API key (optional if `OPENROUTER_API_KEY` is set)
-- `--base-url`: OpenRouter base URL (optional if `OPENROUTER_BASE_URL` is set)
+- `--provider`: optimizer provider (`openrouter`, `openai`, `google`, `anthropic`, `zai`)
+- `--api-key`: provider API key (optional if provider env key is set)
+- `--base-url`: provider base URL (optional if provider env base URL is set)
 - `--optimizer-model`: model used to perform optimization (optional if `PAGANS_OPTIMIZER_MODEL` is set)
 
+Provider env vars:
+
+- OpenRouter: `OPENROUTER_API_KEY`, `OPENROUTER_BASE_URL`
+- OpenAI: `OPENAI_API_KEY`, `OPENAI_BASE_URL`
+- Google AI Studio: `GOOGLE_API_KEY`, `GOOGLE_BASE_URL`
+- Anthropic: `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`
+- Z.ai: `ZAI_API_KEY`, `ZAI_BASE_URL`
+
 ## Commands
 
 ## `optimize`
 
 Optimize a single prompt for one target model.
 
 ```bash
-pagans optimize \
+pagans --provider openrouter optimize \
   --prompt "Write a production-ready retry strategy for HTTP calls" \
   --target-model gpt-5.4
 ```
 
 Use a prompt file:
 
 ```bash
-pagans optimize \
+pagans --provider anthropic optimize \
   --prompt-file ./prompt.txt \
   --target-model claude-sonnet-4-20250514
 ```
 
 JSON output:
 
 ```bash
-pagans optimize \
+pagans --provider openai optimize \
   --prompt "Summarize this architecture decision" \
   --target-model gemini-3.1-pro-preview \
   --json
@@ -42,7 +51,7 @@ pagans optimize \
 Optimize one prompt across multiple models.
 
 ```bash
-pagans compare \
+pagans --provider google compare \
   --prompt "Design a scalable queue processing architecture" \
   --models "gpt-5.4,claude-sonnet-4-20250514,gemini-3.1-pro-preview,grok-4-1-fast-reasoning"
 ```
@@ -52,7 +61,7 @@ pagans compare \
 Optimize multiple prompts from a text file (`one prompt per line`).
 
 ```bash
-pagans batch \
+pagans --provider zai batch \
   --prompts-file ./prompts.txt \
   --target-model grok-4-1-fast-reasoning \
   --max-concurrent 5

docs/TEXT_MODEL_GUIDANCE.md

@@ -1,8 +1,27 @@
 # Text Model Guidance Matrix
 
-Last reviewed: **2026-03-18**
+Last reviewed: **2026-03-19**
 
-This file tracks official prompt-guidance sources and the text-model aliases currently maintained in PAGANS.
+This file tracks official prompt-guidance sources, provider API references, and the text-model aliases currently maintained in PAGANS.
+
+## Optimizer Provider APIs
+
+Official API docs used for provider client configuration:
+
+- OpenAI Chat Completions: https://platform.openai.com/docs/api-reference/chat/create-chat-completion
+- OpenAI Models API: https://platform.openai.com/docs/api-reference/models
+- Google AI Studio OpenAI compatibility: https://ai.google.dev/gemini-api/docs/openai
+- Anthropic Messages API: https://docs.anthropic.com/en/api/messages
+- Anthropic Models API: https://docs.anthropic.com/en/api/models
+- Z.ai developer quick start: https://docs.z.ai/guides
+
+Configured default base URLs:
+
+- OpenRouter: `https://openrouter.ai/api/v1`
+- OpenAI: `https://api.openai.com/v1`
+- Google AI Studio: `https://generativelanguage.googleapis.com/v1beta/openai`
+- Anthropic: `https://api.anthropic.com/v1`
+- Z.ai: `https://api.z.ai/api/paas/v4`
 
 ## OpenAI
 
@@ -36,8 +55,8 @@ Compatibility aliases kept for routing:
 ## Google Gemini
 
 Official docs used:
-- https://ai.google.dev/gemini-api/docs/models/gemini-v2
-- https://ai.google.dev/gemini-api/docs/models/generative-models
+- https://ai.google.dev/gemini-api/docs/models
+- https://ai.google.dev/gemini-api/docs/openai
 
 Primary optimization targets (latest text focus):
 - `gemini-3.1-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-flash-lite-preview`
@@ -66,10 +85,10 @@ Compatibility aliases kept for routing:
 
 When updating model aliases:
 1. Confirm canonical model IDs in each provider's official docs.
-2. Confirm OpenRouter provider prefixes/IDs for routed usage.
-3. Update `src/pagans/models.py`:
+2. Confirm provider prefix/ID conventions for routed usage.
+3. Update `src/pagans/models.py` and `src/pagans/models/__init__.py`:
    - `SHORT_MODEL_NAMES`
-   - `OPENROUTER_MODEL_MAPPINGS`
+   - provider-specific model mappings
    - `MODEL_MAPPINGS`
 4. Add/update tests in `tests/test_models.py` and `tests/test_optimizer_prompts.py`.
 5. Update this file's "Last reviewed" date.

notebooks/README.md

@@ -3,7 +3,12 @@
 This folder contains runnable Jupyter notebooks for PAGANS.
 
 - `pagans_quickstart.ipynb`: end-to-end quickstart for single prompt optimization,
-  cross-family comparison (OpenAI, Anthropic, xAI, Gemini), and batch optimization.
+  cross-family comparison, and batch optimization.
+- `pagans_openrouter_optimizer.ipynb`: OpenRouter optimizer provider setup and run.
+- `pagans_openai_optimizer.ipynb`: OpenAI optimizer provider setup and run.
+- `pagans_google_optimizer.ipynb`: Google AI Studio optimizer provider setup and run.
+- `pagans_anthropic_optimizer.ipynb`: Anthropic optimizer provider setup and run.
+- `pagans_zai_optimizer.ipynb`: Z.ai optimizer provider setup and run.
 
 ## Run locally
 
@@ -12,4 +17,4 @@ uv sync --dev
 uv run jupyter lab
 ```
 
-Then open `notebooks/pagans_quickstart.ipynb`.
+Then open any notebook in `notebooks/`.

notebooks/pagans_anthropic_optimizer.ipynb

@@ -0,0 +1,56 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Anthropic Optimizer Notebook\n",
+        "\n",
+        "Set `ANTHROPIC_API_KEY` before running.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "74da00de",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from pagans import PAGANSOptimizer, Provider\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "async def main():\n",
+        "    async with PAGANSOptimizer(\n",
+        "        provider=Provider.ANTHROPIC,\n",
+        "        optimizer_model='claude-sonnet-4-20250514',\n",
+        "    ) as optimizer:\n",
+        "        result = await optimizer.optimize(\n",
+        "            prompt='Turn this feature request into a precise technical specification.',\n",
+        "            target_model='claude-sonnet-4',\n",
+        "        )\n",
+        "        print(result.optimized)\n",
+        "\n",
+        "await main()\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.12"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}