meta-llama · 8bnns · Jul 1, 2025 · Jul 1, 2025 · Jul 2, 2025 · Jul 2, 2025
diff --git a/.coveragerc b/.coveragerc
@@ -0,0 +1,15 @@
+[run]
+source = src/prompt_ops
+omit =
+    */tests/*
+    */site-packages/*
+    setup.py
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    pass
+    raise ImportError
diff --git a/.github/workflows/ci-with-coverage.yml b/.github/workflows/ci-with-coverage.yml
@@ -34,7 +34,7 @@ jobs:
 
     - name: Run tests with coverage
       run: |
-        pytest --cov=src/llama_prompt_ops --cov-report=xml tests/
+        pytest --cov=src/prompt_ops --cov-report=xml tests/
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -40,7 +40,7 @@ jobs:
         echo "Package version: $VERSION"
 
         # Check if this version already exists on PyPI
-        if pip index versions llama-prompt-ops 2>/dev/null | grep -q "$VERSION"; then
+        if pip index versions prompt-ops 2>/dev/null | grep -q "$VERSION"; then
           echo "Error: Version $VERSION already exists on PyPI"
           exit 1
         fi

diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
+local.env
+
 
 # Python cache files
 __pycache__/

diff --git a/README.md b/README.md
@@ -1,5 +1,17 @@
 <h1 align="center"> Prompt Ops </h1>
 
+### 🎉 New: Prompt Duel Optimizer (PDO) Published!
+
+We've published a new paper on **PDO (Prompt Duel Optimizer)** - an efficient label-free prompt optimization method using dueling bandits and Thompson sampling. PDO achieves state-of-the-art results on BIG-bench Hard and MS MARCO benchmarks.
+
+📄 **Read the paper:** [LLM Prompt Duel Optimizer: Efficient Label-Free Prompt Optimization](https://www.arxiv.org/abs/2510.13907) (arXiv:2510.13907)
+
+🧪 **Try it yourself:** Check out the [Web of Lies use case](use-cases/web-of-lies-pdo/) demonstrating PDO on logical reasoning tasks
+
+⭐ **Star this repo** and follow along - we'll be publishing a detailed tutorial notebook soon!
+
+---
+
 ## What is prompt-ops?
 <p align="center">
   <a href="https://pypi.org/project/prompt-ops/"><img src="https://img.shields.io/pypi/v/prompt-ops.svg" /></a>
@@ -24,11 +36,11 @@
 
 
 
-prompt-ops is a Python package that **automatically optimizes prompts** for Llama models. It transforms prompts that work well with other LLMs into prompts that are optimized for Llama models, improving performance and reliability.
+prompt-ops is a Python package that **automatically optimizes prompts** for Llama models. It transforms prompts that work well with other LLMs into prompts that are optimized for LLM models, improving performance and reliability.
 
 **Key Benefits:**
 - **No More Trial and Error**: Stop manually tweaking prompts to get better results
-- **Fast Optimization**: Get Llama-optimized prompts in minutes with template-based optimization
+- **Fast Optimization**: Get model-optimized prompts in minutes with template-based optimization
 - **Data-Driven Improvements**: Use your own examples to create prompts that work for your specific use case
 - **Measurable Results**: Evaluate prompt performance with customizable metrics
 
@@ -66,7 +78,7 @@ To get started with prompt-ops, you'll need:
 2. [**Prepare your dataset**](#preparing-your-data): Create a JSON file with query-response pairs for evaluation and optimization
 3. **Configure optimization**: Set up a simple YAML file with your dataset and preferences (see [example configuration](configs/facility-simple.yaml))
 4. [**Run optimization**](#step-4-run-optimization): Execute a single command to transform your prompt
-5. [**Get results**](#prompt-transformation-example): Receive a Llama-optimized prompt with performance metrics
+5. [**Get results**](#prompt-transformation-example): Receive a model-optimized prompt with performance metrics
 
 
 ## Real-world Results
@@ -85,19 +97,21 @@ These results were measured on the [HotpotQA multi-hop reasoning benchmark](http
 
 ### Step 1: Installation
 
+> **Note:** We recommend installing from source as we are currently transitioning package names on PyPI. This ensures you get the latest stable version without any naming conflicts.
+
 ```bash
 # Create a virtual environment
 conda create -n prompt-ops python=3.10
 conda activate prompt-ops
 
-# Install from PyPI
-pip install prompt-ops
-
-# OR install from source
+# Recommended: Install from source
 git clone https://github.com/meta-llama/prompt-ops.git
 cd prompt-ops
 pip install -e .
 
+# Alternative: Install from PyPI (may have naming transition issues, still on version 0.0.7)
+# pip install llama-prompt-ops
+
 ```
 
 ### Step 2: Create a sample project
@@ -116,7 +130,8 @@ Add your API key to the `.env` file:
 ```bash
 OPENROUTER_API_KEY=your_key_here
 ```
-You can get an OpenRouter API key by creating an account at [OpenRouter](https://openrouter.ai/). For more inference provider options, see [Inference Providers](./docs/inference_providers.md).
+
+prompt-ops uses LiteLLM as a unified API client. LiteLLM automatically detects the provider from your model name (e.g., `openrouter/model`, `groq/model`) and looks for the corresponding provider-specific environment variable (`OPENROUTER_API_KEY`, `GROQ_API_KEY`, etc.). For more inference provider options, see [Inference Providers](./docs/inference_providers.md).
 
 ### Step 4: Run Optimization
 The optimization will take about 5 minutes.

diff --git a/configs/facility-simple.yaml b/configs/facility-simple.yaml
@@ -10,6 +10,7 @@ dataset:
   golden_output_field: "answer"
 
 # Model configuration (minimal required settings)
+# LiteLLM auto-detects API keys from provider-specific env vars (e.g., OPENROUTER_API_KEY)
 model:
   name: "openrouter/meta-llama/llama-3.3-70b-instruct"
   task_model: "openrouter/meta-llama/llama-3.3-70b-instruct"

diff --git a/configs/facility.yaml b/configs/facility.yaml
@@ -1,12 +1,9 @@
 # Facility dataset configuration for prompt optimization
 
-#TODO: think if there are any way to abstract this
-# provider: openrouter/hosted_vllm/togethercomputer
-# model: meta-llama/llama-3.3-70b-instruct
-# litellm
+# Model configuration - uses LiteLLM with provider prefix
+# LiteLLM auto-detects API key from provider-specific env vars (e.g., OPENROUTER_API_KEY, GROQ_API_KEY)
 model:
   name: "openrouter/meta-llama/llama-3.3-70b-instruct"
-  api_base: "https://openrouter.ai/api/v1" # rename base_url:
   temperature: 0.0
   # max_tokens: 2048       # Maximum number of tokens to generate
   # top_p: 0.9             # Nucleus sampling parameter

diff --git a/configs/hotpotqa.yaml b/configs/hotpotqa.yaml
@@ -1,6 +1,5 @@
 model:
   name: "openrouter/meta-llama/llama-3.1-8b-instruct"
-  api_base: "https://openrouter.ai/api/v1"
   temperature: 0.0
   max_tokens: 40960
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,3 +1,11 @@
+---
+title: Getting Started
+category: Basics
+description: Learn the fundamentals of prompt-ops and choose your optimization path
+order: 1
+icon: book
+---
+
 # prompt-ops Getting Started Guide
 
 Welcome to prompt-ops! This guide will help you understand what's supported out of the box and how to get started quickly.
@@ -54,6 +62,13 @@ prompt-ops supports various inference providers and endpoints to fit your infras
 - **CSV**: Tabular data with headers
 - **YAML**: Structured data in YAML format
 
+## Documentation Languages / لغات التوثيق
+
+- [English (current)](./README.md)
+- [العربية / Arabic](./ar/README.md)
+
+---
+
 ## Try Our Examples
 
 We've prepared several complete examples to help you get started:

diff --git a/docs/advanced/logging.md b/docs/advanced/logging.md
@@ -1,3 +1,11 @@
+---
+title: Logging & Telemetry
+category: Advanced
+description: Configure logging levels and export optimization telemetry for analysis
+order: 32
+icon: settings
+---
+
 # Logging and Telemetry
 
 The `prompt-ops` library includes a flexible logging framework to provide insights into the optimization process. You can control the verbosity of the output and export detailed telemetry for analysis.

diff --git a/docs/advanced/readme.md b/docs/advanced/readme.md
@@ -1,3 +1,11 @@
+---
+title: Custom Adapters & Metrics
+category: Advanced
+description: Create custom dataset adapters and evaluation metrics for your use case
+order: 31
+icon: code
+---
+
 # Using prompt-ops for your use case (with Examples)
 
 > **Note:** This guide explains how to add new use cases to prompt-ops by either configuring existing components or creating custom components.

diff --git a/docs/ar/README.md b/docs/ar/README.md
@@ -0,0 +1,80 @@
+---
+title: البدء السريع
+category: الأساسيات
+description: تعلّم أساسيات prompt-ops واختر مسار التحسين المناسب
+order: 1
+icon: book
+---
+
+# دليل البدء مع prompt-ops
+
+<div dir="rtl">
+
+مرحبًا بك في **prompt-ops**! يساعدك هذا الدليل على فهم ما يدعمه النظام خارج الصندوق وكيفية البدء بسرعة.
+
+## البدء السريع: اختر مسارك
+
+- [أنا جديد على هندسة البرومبت الآلية](./basic/readme.md) — تعلّم الأساسيات عبر الأمثلة الموجّهة
+- [أريد تهيئة تحسين البرومبت](./intermediate/readme.md) — تعرّف على خيارات التهيئة المتوسطة
+- [لديّ مجموعة بيانات وحالة استخدام خاصة](./advanced/readme.md) — كيفية تكييف prompt-ops مع احتياجاتك
+
+---
+
+## اختيار محوّل مجموعة البيانات
+
+| نوع المحوّل | صيغة الإدخال | متى تستخدمه |
+|---|---|---|
+| StandardJSONAdapter | `[{"question": "ما عاصمة فرنسا؟", "answer": "باريس"}]` | لمعظم مجموعات البيانات الشائعة التي تحتوي على حقلَي سؤال وإجابة |
+| RAGJSONAdapter | `[{"question": "...", "context": "...", "answer": "..."}]` | عندما تتضمن مجموعة البيانات سياقات استرداد |
+| محوّل مخصص | أي صيغة متخصصة لا تنطبق عليها الأنماط السابقة | عندما لا تلبّي المحوّلات الموجودة احتياجاتك |
+
+راجع [دليل اختيار محوّل مجموعة البيانات التفصيلي](./dataset_adapter_selection_guide.md) لمزيد من المعلومات.
+
+---
+
+## مقاييس التقييم
+
+| نوع المقياس | حالة الاستخدام | الصيغة المتوقعة | متى تستخدمه |
+|---|---|---|---|
+| **ExactMatchMetric** | المطابقة النصية البسيطة | نصوص عادية | عند الحاجة إلى مطابقة دقيقة بين التوقع والحقيقة |
+| **StandardJSONMetric** | تقييم JSON هيكلي | كائنات JSON أو نصوص | عند تقييم استجابات JSON منظَّمة بحقول محددة |
+| **مقياس مخصص** | احتياجات تقييم متخصصة | أي صيغة مخصصة | عندما لا تلبّي المقاييس الموجودة احتياجاتك |
+
+راجع [دليل اختيار المقاييس التفصيلي](./metric_selection_guide.md) لمزيد من المعلومات.
+
+---
+
+## دعم مزودي الاستدلال المتعددين
+
+يدعم prompt-ops مزودي استدلال ونقاط نهاية متنوعة لتناسب احتياجات بنيتك التحتية. راجع [الدليل التفصيلي لمزودي الاستدلال](./inference_providers.md) لأمثلة التهيئة مع:
+
+- OpenRouter (واجهة برمجية سحابية)
+- vLLM (نشر محلي)
+- NVIDIA NIMs (حاويات محسَّنة)
+
+---
+
+## الصيغ المدعومة دفعةً واحدة
+
+### صيغ البرومبت
+
+- **ملفات نصية**: ملفات نص عادي تحتوي على تعليمات
+- **نص مضمّن**: نص مباشر في تهيئة YAML
+- **متغيرات القالب**: استخدم صيغة `{{variable}}` للمدخلات
+
+### صيغ مجموعات البيانات
+
+- **JSON**: مصفوفات من الكائنات (الأكثر شيوعًا)
+- **CSV**: بيانات جدولية برؤوس أعمدة
+- **YAML**: بيانات منظَّمة بصيغة YAML
+
+---
+
+## جرّب أمثلتنا
+
+أعددنا عدة أمثلة متكاملة لمساعدتك على البدء:
+
+- [الإجابة على الأسئلة متعددة الخطوات (HotpotQA)](../../use-cases/hotpotqa/): تحسين البرومبتات لمهام QA متعددة الخطوات
+- [محلّل دعم المرافق](../../use-cases/facility-support-analyzer/): تصنيف الرسائل وتحليلها
+
+</div>