feat: add comprehensive tests, examples, and documentation

.github/workflows/ci.yml

@@ -7,12 +7,53 @@ on:
     branches: [main]
 
 jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install linting tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+
+      - name: Install packages for type checking
+        run: |
+          pip install pydantic langchain-core
+          cd packages/promptpack && pip install -e .
+          cd ../promptpack-langchain && pip install -e .
+
+      - name: Run ruff linter on packages
+        run: ruff check packages/
+
+      - name: Run ruff linter on examples
+        run: ruff check examples/
+
+      - name: Run ruff formatter check on packages
+        run: ruff format --check packages/
+
+      - name: Run ruff formatter check on examples
+        run: ruff format --check examples/
+
+      - name: Run mypy on promptpack
+        run: mypy packages/promptpack/src/promptpack --ignore-missing-imports
+
+      - name: Run mypy on promptpack-langchain
+        run: mypy packages/promptpack-langchain/src/promptpack_langchain --ignore-missing-imports
+
   test:
+    name: Test (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4
@@ -25,7 +66,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install hatch
+          pip install pytest pytest-asyncio pytest-cov
 
       - name: Install promptpack package
         run: |
@@ -40,14 +81,22 @@ jobs:
       - name: Run promptpack tests
         run: |
           cd packages/promptpack
-          pytest tests/ -v --tb=short
+          pytest tests/ -v --tb=short --cov=src/promptpack --cov-report=xml:coverage-promptpack.xml
 
       - name: Run promptpack-langchain tests
         run: |
           cd packages/promptpack-langchain
-          pytest tests/ -v --tb=short
+          pytest tests/ -v --tb=short --cov=src/promptpack_langchain --cov-report=xml:coverage-langchain.xml
 
-  lint:
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          files: packages/promptpack/coverage-promptpack.xml,packages/promptpack-langchain/coverage-langchain.xml
+          fail_ci_if_error: false
+
+  examples:
+    name: Verify Examples
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -57,25 +106,21 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install linting tools
+      - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install ruff mypy
+          pip install pytest
 
-      - name: Install packages for type checking
+      - name: Install packages
         run: |
-          pip install pydantic langchain-core
           cd packages/promptpack && pip install -e .
           cd ../promptpack-langchain && pip install -e .
 
-      - name: Run ruff linter
-        run: ruff check packages/
-
-      - name: Run ruff formatter check
-        run: ruff format --check packages/
+      - name: Run basic_usage example
+        run: python examples/basic_usage.py
 
-      - name: Run mypy on promptpack
-        run: mypy packages/promptpack/src/promptpack --ignore-missing-imports
+      - name: Run tools_example
+        run: python examples/tools_example.py
 
-      - name: Run mypy on promptpack-langchain
-        run: mypy packages/promptpack-langchain/src/promptpack_langchain --ignore-missing-imports
+      - name: Run validation_example
+        run: python examples/validation_example.py

docs/astro.config.mjs

@@ -23,6 +23,7 @@ export default defineConfig({
       sidebar: [
         { label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
         { label: 'Packages', autogenerate: { directory: 'packages' } },
+        { label: 'Examples', autogenerate: { directory: 'examples' } },
         { label: 'API Reference', autogenerate: { directory: 'api' } },
         { label: 'Contributors', autogenerate: { directory: 'contributors' } },
       ],

docs/src/content/docs/examples/basic-usage.md

@@ -0,0 +1,172 @@
+---
+title: Basic Usage
+description: Getting started with PromptPack Python
+sidebar:
+  order: 2
+---
+
+This example demonstrates the core PromptPack workflow: loading packs, creating templates, and formatting prompts.
+
+## Loading a PromptPack
+
+```python
+from pathlib import Path
+from promptpack import parse_promptpack
+
+# Load from a file
+pack = parse_promptpack("path/to/pack.json")
+
+# Or parse from a string
+from promptpack import parse_promptpack_string
+
+pack_json = '{"id": "my-pack", ...}'
+pack = parse_promptpack_string(pack_json)
+```
+
+## Creating Templates
+
+Use `PromptPackTemplate` to create LangChain-compatible templates:
+
+```python
+from promptpack_langchain import PromptPackTemplate
+
+# Create a template from a specific prompt in the pack
+template = PromptPackTemplate.from_promptpack(pack, "support")
+
+# Check input variables
+print(template.input_variables)  # ['role', 'company']
+
+# Get LLM parameters
+params = template.get_parameters()
+print(params)  # {'temperature': 0.7, 'max_tokens': 1500}
+```
+
+## Formatting Prompts
+
+Format the template with your variables:
+
+```python
+# Format with variables
+formatted = template.format(
+    role="customer support agent",
+    issue_type="billing"
+)
+
+print(formatted)
+```
+
+Output:
+```
+You are a customer support agent assistant for TechCorp.
+
+# Company Context
+TechCorp provides cloud infrastructure, SaaS products, and enterprise solutions.
+
+# Your Role
+Handle billing customer inquiries effectively.
+
+# Guidelines
+Maintain a professional yet friendly tone. Be concise and solution-oriented.
+```
+
+## Using Fragments
+
+PromptPacks support reusable fragments that are automatically resolved:
+
+```json
+{
+  "fragments": {
+    "company_context": "TechCorp provides cloud infrastructure...",
+    "tone_guidelines": "Maintain a professional yet friendly tone..."
+  },
+  "prompts": {
+    "support": {
+      "system_template": "{{fragment:company_context}}\n\n{{fragment:tone_guidelines}}"
+    }
+  }
+}
+```
+
+Fragments are resolved automatically when you call `template.format()`.
+
+## Model Overrides
+
+Templates can have model-specific configurations:
+
+```python
+# Create template with model-specific overrides
+template = PromptPackTemplate.from_promptpack(
+    pack,
+    "support",
+    model_name="gpt-4"
+)
+
+# The template and parameters will use GPT-4 specific settings
+params = template.get_parameters()
+```
+
+## Using with LangChain
+
+Convert to a ChatPromptTemplate for use with LangChain:
+
+```python
+from langchain_openai import ChatOpenAI
+
+# Create chat template
+chat_template = template.to_chat_prompt_template(
+    role="support agent",
+    company="Acme Corp"
+)
+
+# Create chain
+model = ChatOpenAI(
+    model="gpt-4o-mini",
+    temperature=template.get_parameters().get("temperature", 0.7)
+)
+
+chain = chat_template | model
+
+# Invoke
+response = chain.invoke({
+    "messages": [("human", "I was charged twice for my subscription")]
+})
+
+print(response.content)
+```
+
+## Complete Example
+
+Here's the complete `basic_usage.py` example:
+
+```python
+#!/usr/bin/env python3
+from pathlib import Path
+
+from promptpack import parse_promptpack
+from promptpack_langchain import PromptPackTemplate
+
+
+def main():
+    # Load PromptPack
+    pack_path = Path(__file__).parent / "packs" / "customer-support.json"
+    pack = parse_promptpack(pack_path)
+
+    print(f"Loaded pack: {pack.name} (v{pack.version})")
+    print(f"Available prompts: {list(pack.prompts.keys())}")
+
+    # Create template
+    template = PromptPackTemplate.from_promptpack(pack, "support")
+    print(f"Input variables: {template.input_variables}")
+    print(f"Parameters: {template.get_parameters()}")
+
+    # Format
+    formatted = template.format(
+        role="customer support agent",
+        issue_type="billing"
+    )
+    print(formatted)
+
+
+if __name__ == "__main__":
+    main()
+```

docs/src/content/docs/examples/index.md

@@ -0,0 +1,45 @@
+---
+title: Examples Overview
+description: Learn how to use PromptPack Python through practical examples
+sidebar:
+  order: 1
+---
+
+This section contains practical examples demonstrating how to use PromptPack Python in real-world scenarios.
+
+## Available Examples
+
+### [Basic Usage](/promptpack-python/examples/basic-usage/)
+Learn the fundamentals of loading PromptPacks, creating templates, and formatting prompts with variables and fragments.
+
+### [Tools Integration](/promptpack-python/examples/tools/)
+Discover how to convert PromptPack tools to LangChain format, bind custom handlers, and use tools with agents.
+
+### [Validation](/promptpack-python/examples/validation/)
+Explore the validation system including banned words, length limits, and regex pattern matching.
+
+## Running the Examples
+
+All examples are located in the `examples/` directory of the repository. To run them:
+
+```bash
+# Clone the repository
+git clone https://github.com/AltairaLabs/promptpack-python.git
+cd promptpack-python
+
+# Install dependencies
+pip install -e packages/promptpack
+pip install -e packages/promptpack-langchain
+
+# Run an example
+python examples/basic_usage.py
+python examples/tools_example.py
+python examples/validation_example.py
+```
+
+## Example Packs
+
+The examples use PromptPack JSON files located in `examples/packs/`:
+
+- **customer-support.json** - Customer support prompts with fragments, validators, and multiple prompt types
+- **sales-assistant.json** - Sales assistant with CRM tools (customer lookup, inventory, orders)