prompture 0.0.32__tar.gz → 0.0.42.dev1__tar.gz

prompture-0.0.42.dev1/.claude/skills/add-driver/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: add-driver
+description: Scaffold a new LLM provider driver for Prompture. Creates the driver class, registers it in the driver registry, adds settings, env template, setup.py extras, and package exports. Use when adding support for a new LLM provider.
+metadata:
+  author: prompture
+  version: "1.0"
+---
+
+# Add a New LLM Driver
+
+Scaffolds all files needed to integrate a new LLM provider into Prompture.
+
+## Before Starting
+
+Ask the user for:
+- **Provider name** (lowercase, used as registry key and `provider/model` prefix)
+- **SDK package name** on PyPI and minimum version
+- **Default model ID**
+- **Authentication** — API key env var name, endpoint URL, or both
+- **Model pricing** — cost per 1K tokens for prompt/completion, or `0.0` for free/local
+- **Lazy or eager import** — lazy if SDK is optional, eager if it's in `install_requires`
+
+## Files to Create or Modify (7 total)
+
+### 1. NEW: `prompture/drivers/{provider}_driver.py`
+
+See [references/driver-template.md](references/driver-template.md) for the full skeleton.
+
+Key rules:
+- Subclass `Driver` from `..driver`
+- `generate()` returns `{"text": str, "meta": dict}`
+- `meta` MUST contain: `prompt_tokens`, `completion_tokens`, `total_tokens`, `cost`, `raw_response`, `model_name`
+- Optional SDK: wrap import in try/except, raise `ImportError` pointing to `pip install prompture[{provider}]`
+
+### 2. `prompture/drivers/__init__.py`
+
+- Add import: `from .{provider}_driver import {Provider}Driver`
+- Add to `DRIVER_REGISTRY`:
+  ```python
+  "{provider}": lambda model=None: {Provider}Driver(
+      api_key=settings.{provider}_api_key,
+      model=model or settings.{provider}_model
+  ),
+  ```
+- Add `"{Provider}Driver"` to `__all__`
+
+### 3. `prompture/__init__.py`
+
+- Add `{Provider}Driver` to the `.drivers` import line
+- Add `"{Provider}Driver"` to `__all__` under `# Drivers`
+
+### 4. `prompture/settings.py`
+
+Add inside `Settings` class:
+```python
+# {Provider}
+{provider}_api_key: Optional[str] = None
+{provider}_model: str = "default-model"
+```
+
+### 5. `setup.py`
+
+If optional: add `"{provider}": ["{sdk}>={version}"]` to `extras_require`.
+If required: add to `install_requires`.
+
+### 6. `.env.copy`
+
+Add section:
+```
+# {Provider} Configuration
+{PROVIDER}_API_KEY=your-api-key-here
+{PROVIDER}_MODEL=default-model
+```
+
+### 7. `CLAUDE.md`
+
+Add `{provider}` to the driver list in the Module Layout bullet.
+
+## Verification
+
+```bash
+python -c "from prompture import {Provider}Driver; print('OK')"
+python -c "from prompture.drivers import get_driver_for_model; d = get_driver_for_model('{provider}/test'); print(d.model)"
+pytest tests/ -x -q
+```

prompture-0.0.42.dev1/.claude/skills/add-driver/references/driver-template.md

@@ -0,0 +1,83 @@
+# Driver Template
+
+Every Prompture driver follows this skeleton:
+
+```python
+import os
+import logging
+from ..driver import Driver
+from typing import Any, Dict
+
+logger = logging.getLogger(__name__)
+
+
+class {Provider}Driver(Driver):
+    MODEL_PRICING = {
+        # "model-name": {"prompt": cost_per_1k, "completion": cost_per_1k},
+        "default": {"prompt": 0.0, "completion": 0.0},
+    }
+
+    def __init__(self, api_key: str | None = None, model: str = "default-model"):
+        self.api_key = api_key or os.getenv("{PROVIDER}_API_KEY")
+        self.model = model
+        self.options: Dict[str, Any] = {}
+
+    def generate(self, prompt: str, options: Dict[str, Any] = None) -> Dict[str, Any]:
+        merged_options = self.options.copy()
+        if options:
+            merged_options.update(options)
+
+        # --- provider-specific API call here ---
+        # text = ...
+        # prompt_tokens = ...
+        # completion_tokens = ...
+        # raw = ...
+
+        # Compute cost
+        pricing = self.MODEL_PRICING.get(self.model, self.MODEL_PRICING["default"])
+        total_cost = (
+            (prompt_tokens / 1000) * pricing["prompt"]
+            + (completion_tokens / 1000) * pricing["completion"]
+        )
+
+        meta = {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": prompt_tokens + completion_tokens,
+            "cost": round(total_cost, 6),
+            "raw_response": raw,
+            "model_name": self.model,
+        }
+        return {"text": text, "meta": meta}
+```
+
+## Lazy Import Pattern (for optional SDKs)
+
+```python
+def __init__(self, ...):
+    self._client = None
+    # defer import
+
+def _ensure_client(self):
+    if self._client is not None:
+        return
+    try:
+        from some_sdk import Client
+    except ImportError:
+        raise ImportError(
+            "The 'some-sdk' package is required. "
+            "Install with: pip install prompture[provider]"
+        )
+    self._client = Client(api_key=self.api_key)
+```
+
+## Existing Drivers for Reference
+
+| Driver | File | SDK | Auth |
+|--------|------|-----|------|
+| OpenAI | `openai_driver.py` | `openai` | API key |
+| Claude | `claude_driver.py` | `anthropic` | API key |
+| Google | `google_driver.py` | `google-generativeai` | API key |
+| Groq | `groq_driver.py` | `groq` | API key |
+| Ollama | `ollama_driver.py` | `requests` | Endpoint URL |
+| AirLLM | `airllm_driver.py` | `airllm` (lazy) | None (local) |

prompture-0.0.42.dev1/.claude/skills/add-example/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: add-example
+description: Create a new Prompture usage example script. Follows project conventions for file naming, section structure, docstrings, and output formatting. Use when demonstrating extraction use cases or provider integrations.
+metadata:
+  author: prompture
+  version: "1.0"
+---
+
+# Add an Example File
+
+Creates a standalone runnable example in `examples/`.
+
+## Before Starting
+
+Ask the user:
+- **Topic / use case** (e.g. "medical record extraction", "product review analysis")
+- **Extraction method** — `extract_with_model`, `stepwise_extract_with_model`, `extract_and_jsonify`, `extract_from_data`, or `render_output`
+- **Provider/model** — default: `ollama/gpt-oss:20b`
+
+## Conventions
+
+- File: `examples/{descriptive_name}_example.py`
+- Standalone — no test framework imports
+- Section dividers: `# ── N. Title ──`
+- Always print extracted result and usage metadata
+- Realistic sample text, not lorem ipsum
+- Under 80 lines when possible
+
+## Template
+
+```python
+"""
+Example: {Title}
+
+This example demonstrates:
+1. {Feature 1}
+2. {Feature 2}
+
+Requirements:
+    pip install prompture
+    # Set up provider credentials in .env
+"""
+
+import json
+from pydantic import BaseModel, Field
+from prompture import extract_with_model
+
+# ── 1. Define the output model ──────────────────────────
+
+class MyModel(BaseModel):
+    field1: str = Field(description="...")
+    field2: int = Field(description="...")
+
+# ── 2. Input text ───────────────────────────────────────
+
+text = """
+Realistic sample text here.
+"""
+
+# ── 3. Extract ──────────────────────────────────────────
+
+MODEL = "ollama/gpt-oss:20b"
+
+result = extract_with_model(
+    model_cls=MyModel,
+    text=text,
+    model_name=MODEL,
+)
+
+# ── 4. Results ──────────────────────────────────────────
+
+print("Extracted model:")
+print(result["model"])
+print()
+print("Usage metadata:")
+print(json.dumps(result["usage"], indent=2))
+```
+
+## Rules
+
+- Import only from `prompture` public API
+- Include docstring header listing features and setup requirements
+- If provider-specific, mention the env var in the docstring

prompture-0.0.42.dev1/.claude/skills/add-field/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: add-field
+description: Add predefined field definitions to the Prompture field registry. Handles field structure, categories, template variables, enum support, and thread-safe registration. Use when adding reusable extraction fields.
+metadata:
+  author: prompture
+  version: "1.0"
+---
+
+# Add Field Definitions
+
+Adds new fields to the global `BASE_FIELD_DEFINITIONS` registry in `prompture/field_definitions.py`.
+
+## Before Starting
+
+Ask the user for each field:
+- **Field name** — lowercase, underscore-separated (e.g. `linkedin_url`, `blood_type`)
+- **Category** — Person, Contact, Professional, Financial, Location, Education, Demographic, Social Media, Task Management, or a new one
+- **Type** — `str`, `int`, `float`, `bool`, `list`, `dict`
+- **Description** — what this field represents
+- **Instructions** — how the LLM should extract or compute the value
+- **Default** — type-appropriate: `""` for str, `0` for int, `0.0` for float, `[]` for list, `False` for bool
+- **Nullable** — `True` if the field can legitimately be absent
+- **Enum values** (optional) — list of allowed string values
+
+## Field Structure
+
+```python
+"field_name": {
+    "type": str,
+    "description": "What this field represents.",
+    "instructions": "How the LLM should extract or compute this value.",
+    "default": "",
+    "nullable": False,
+},
+```
+
+### Optional keys
+
+- `"enum"`: `["low", "medium", "high"]`
+- Template variables in `instructions`: `{{current_year}}`, `{{current_date}}`, `{{current_datetime}}`, `{{current_month}}`, `{{current_day}}`, `{{current_weekday}}`, `{{current_iso_week}}`
+
+## Steps
+
+### 1. Edit `prompture/field_definitions.py`
+
+Add fields to `BASE_FIELD_DEFINITIONS` under the right category comment. If the category is new, add a comment header:
+
+```python
+    # ── Medical Fields ──────────────────────────────────
+```
+
+Alphabetical order within each category.
+
+### 2. Verify
+
+```bash
+python -c "from prompture.field_definitions import get_field_definition; print(get_field_definition('field_name'))"
+pytest tests/test_field_definitions.py -x -q
+```

prompture-0.0.42.dev1/.claude/skills/add-test/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: add-test
+description: Add unit and integration tests for Prompture functionality. Uses pytest conventions, shared fixtures from conftest.py, and the integration marker pattern. Use when writing tests for new or existing features.
+metadata:
+  author: prompture
+  version: "1.0"
+---
+
+# Add Tests
+
+Creates tests in `tests/` following project conventions.
+
+## Infrastructure
+
+- Framework: **pytest**
+- Shared fixtures: `tests/conftest.py`
+- Default model: `DEFAULT_MODEL` (currently `"ollama/gpt-oss:20b"`)
+- Integration marker: `@pytest.mark.integration` (skipped by default)
+
+## Available Fixtures and Helpers
+
+```python
+# Fixtures
+sample_json_schema       # {"name": str, "age": int, "interests": list}
+integration_driver       # Driver from DEFAULT_MODEL (skips if unavailable)
+
+# Assertion helpers
+assert_valid_usage_metadata(meta)           # Checks prompt_tokens, completion_tokens, total_tokens, cost, raw_response
+assert_jsonify_response_structure(response)  # Checks json_string, json_object, usage
+```
+
+## File Naming
+
+- `tests/test_{module}.py` — maps to source module
+- `tests/test_{feature}.py` — cross-cutting features
+
+## Test Structure
+
+```python
+import pytest
+from prompture import extract_with_model
+
+
+class TestFeatureName:
+    """Tests for {feature}."""
+
+    def test_basic_behavior(self):
+        """What this test verifies."""
+        result = some_function(...)
+        assert result["key"] == expected
+
+    def test_error_handling(self):
+        """Should raise ValueError on invalid input."""
+        with pytest.raises(ValueError, match="expected"):
+            some_function(bad_input)
+
+
+class TestFeatureIntegration:
+    """Integration tests requiring live LLM access."""
+
+    @pytest.mark.integration
+    def test_live_extraction(self, integration_driver, sample_json_schema):
+        result = extract_and_jsonify(
+            text="John is 30 years old",
+            json_schema=sample_json_schema,
+            model_name=DEFAULT_MODEL,
+        )
+        assert_jsonify_response_structure(result)
+        assert_valid_usage_metadata(result["usage"])
+```
+
+## Rules
+
+- **Unit tests** (no LLM): no marker, must always pass
+- **Integration tests** (live LLM): must have `@pytest.mark.integration`
+- Use conftest fixtures — don't redefine them
+- One test class per logical group with docstrings
+- Test both happy path and error cases
+- Mock HTTP layer for driver unit tests
+
+## Running
+
+```bash
+pytest tests/ -x -q                          # Unit only
+pytest tests/ --run-integration -x -q        # Include integration
+pytest tests/test_core.py::TestClass::test_method  # Single test
+```

prompture-0.0.42.dev1/.claude/skills/run-tests/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: run-tests
+description: Run Prompture's test suite with the correct pytest flags. Supports unit-only, integration, single file, single test, verbose, and credential-skip modes. Use when running or debugging tests.
+metadata:
+  author: prompture
+  version: "1.0"
+---
+
+# Run Tests
+
+## Commands
+
+| Intent | Command |
+|--------|---------|
+| All unit tests | `pytest tests/ -x -q` |
+| Include integration tests | `pytest tests/ --run-integration -x -q` |
+| Specific file | `pytest tests/{file}.py -x -q` |
+| Specific class | `pytest tests/{file}.py::{Class} -x -q` |
+| Specific test | `pytest tests/{file}.py::{Class}::{test} -x -q` |
+| Verbose output | Replace `-q` with `-v` |
+| Show print output | Add `-s` |
+| Pattern match | Add `-k "pattern"` |
+| Skip missing credentials | `TEST_SKIP_NO_CREDENTIALS=true pytest tests/ --run-integration -x -q` |
+| Legacy runner | `python test.py` |
+
+## Flags
+
+- `-x` stop on first failure
+- `-q` quiet (dots + summary)
+- `-v` verbose (each test name)
+- `-s` show stdout/stderr
+- `--run-integration` include `@pytest.mark.integration` tests
+
+## After Running
+
+- **Pass**: report count (e.g. "137 passed, 1 skipped")
+- **Fail**: read the failure output, identify root cause, fix it
+- Always run after modifying any file under `prompture/`

prompture-0.0.42.dev1/.claude/skills/scaffold-extraction/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: scaffold-extraction
+description: Scaffold a complete extraction pipeline for a new domain — Pydantic model, field definitions, example script, and tests. Use when building a new extraction use case like medical records, invoices, or reviews.
+metadata:
+  author: prompture
+  version: "1.0"
+---
+
+# Scaffold an Extraction Pipeline
+
+Builds the full pipeline for a new extraction domain: model, fields, example, and tests.
+
+## Before Starting
+
+Ask the user:
+- **Domain / use case** — what kind of data to extract
+- **Fields** — list with types, or infer from a sample text
+- **Provider/model** — default `ollama/gpt-oss:20b`
+- **Method** — one-shot or stepwise (see selection guide below)
+
+## Method Selection Guide
+
+| Scenario | Method |
+|----------|--------|
+| Simple model, < 8 fields | `extract_with_model` (1 LLM call) |
+| Complex model, 8+ fields | `stepwise_extract_with_model` (N calls, more accurate) |
+| No Pydantic model, raw schema | `extract_and_jsonify` |
+| Structured input (CSV, JSON) | `extract_from_data` (TOON, 45-60% token savings) |
+| DataFrame input | `extract_from_pandas` |
+| Non-JSON output | `render_output` |
+
+## Deliverables
+
+### 1. Pydantic Model
+
+```python
+from pydantic import BaseModel, Field
+
+class InvoiceData(BaseModel):
+    vendor_name: str = Field(description="Company that issued the invoice")
+    total_amount: float = Field(description="Total amount due")
+    currency: str = Field(default="USD", description="ISO 4217 currency code")
+```
+
+Rules:
+- `Field(description=...)` on every field — these become LLM instructions
+- Type-appropriate defaults: `""`, `0`, `0.0`, `[]`
+- `Optional[T] = None` only when a field genuinely might not exist
+
+### 2. Field Definitions (optional)
+
+Register in `prompture/field_definitions.py` only if fields are general-purpose. Use the `add-field` skill.
+
+### 3. Example Script
+
+Create `examples/{domain}_extraction_example.py`. Use the `add-example` skill.
+
+### 4. Tests
+
+Unit test for the Pydantic model + integration test for end-to-end extraction. Use the `add-test` skill.
+
+## Sample Call
+
+```python
+from prompture import extract_with_model
+
+result = extract_with_model(
+    model_cls=InvoiceData,
+    text=invoice_text,
+    model_name="ollama/gpt-oss:20b",
+    instruction_template="Extract all invoice details from the following document:",
+)
+
+invoice = result["model"]    # Pydantic instance
+usage = result["usage"]      # Token counts and cost
+```

prompture-0.0.42.dev1/.claude/skills/update-pricing/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: update-pricing
+description: Update LLM model pricing tables in Prompture driver files. Checks provider pricing pages, updates MODEL_PRICING dicts, adds new models, and removes discontinued ones. Use when model prices change or new models launch.
+metadata:
+  author: prompture
+  version: "1.0"
+---
+
+# Update Model Pricing
+
+## Where Pricing Lives
+
+Each driver has a `MODEL_PRICING` class variable:
+
+```python
+class OpenAIDriver(Driver):
+    MODEL_PRICING = {
+        "gpt-4o": {"prompt": 0.005, "completion": 0.015},
+        "default": {"prompt": 0.002, "completion": 0.002},
+    }
+```
+
+Files with pricing:
+- `prompture/drivers/openai_driver.py`
+- `prompture/drivers/claude_driver.py`
+- `prompture/drivers/google_driver.py`
+- `prompture/drivers/groq_driver.py`
+- `prompture/drivers/grok_driver.py`
+- `prompture/drivers/openrouter_driver.py`
+- `prompture/drivers/azure_driver.py`
+
+Local/free drivers (ollama, lmstudio, local_http, airllm) use `0.0`.
+
+## Steps
+
+1. **Search the web** for the provider's current pricing page
+2. **Read** the current `MODEL_PRICING` dict in the driver file
+3. **Update** prices, add new models, remove discontinued ones
+4. **Keep** the `"default"` fallback entry
+5. **Preserve** extra keys like `"tokens_param"` or `"supports_temperature"`
+6. **Run tests**: `pytest tests/ -x -q`
+
+## Format
+
+- Values: **cost per 1,000 tokens** in USD
+- Both `"prompt"` and `"completion"` keys required
+- Always include `"default"` as fallback
+
+## Side Effects
+
+`prompture/discovery.py` reads `MODEL_PRICING` keys to list available models. Adding or removing models from pricing automatically updates discovery results.

{prompture-0.0.32 → prompture-0.0.42.dev1}/.env.copy

@@ -23,6 +23,7 @@ OLLAMA_MODEL=gemma:latest
 # Required if AI_PROVIDER=lmstudio
 LMSTUDIO_ENDPOINT=http://127.0.0.1:1234/v1/chat/completions
 LMSTUDIO_MODEL=deepseek/deepseek-r1-0528-qwen3-8b
+LMSTUDIO_API_KEY=
 
 # Azure OpenAI Configuration
 AZURE_API_KEY=
@@ -52,9 +53,31 @@ GROQ_MODEL=llama2-70b-4096
 # OpenRouter Configuration
 # Required if AI_PROVIDER=openrouter
 OPENROUTER_API_KEY=your-api-key-here
-OPENROUTER_MODEL=openai/gpt-3.5-turbo
+OPENROUTER_MODEL=openai/gpt-4o-mini
 
 # Grok Configuration
 # Required if AI_PROVIDER=grok
 GROK_API_KEY=your-api-key-here
-GROK_MODEL=grok-4-fast-reasoning
+GROK_MODEL=grok-4-fast-reasoning
+
+# Moonshot AI (Kimi) Configuration
+# Required if AI_PROVIDER=moonshot
+MOONSHOT_API_KEY=
+MOONSHOT_MODEL=kimi-k2-0905-preview
+MOONSHOT_ENDPOINT=https://api.moonshot.ai/v1
+
+# Z.ai (Zhipu AI) Configuration
+# Required if AI_PROVIDER=zai
+ZHIPU_API_KEY=
+ZHIPU_MODEL=glm-4.7
+ZHIPU_ENDPOINT=https://api.z.ai/api/paas/v4
+
+# ModelScope (Alibaba Cloud) Configuration
+# Required if AI_PROVIDER=modelscope
+MODELSCOPE_API_KEY=
+MODELSCOPE_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507
+MODELSCOPE_ENDPOINT=https://api-inference.modelscope.cn/v1
+
+# AirLLM Configuration
+AIRLLM_MODEL=meta-llama/Llama-2-7b-hf
+AIRLLM_COMPRESSION=