prompture 0.0.33.dev1__tar.gz → 0.0.33.dev2__tar.gz

prompture-0.0.33.dev2/.claude/skills/add-driver.md

@@ -0,0 +1,121 @@
+# Skill: Add a New LLM Driver
+
+When the user asks to add a new driver (provider), follow this checklist exactly. Ask the user for any values marked **[ASK]** before writing code.
+
+## Information to Gather
+
+- **Provider name** (lowercase, used as registry key and `provider/model` prefix): [ASK]
+- **SDK package name** on PyPI (e.g. `openai`, `anthropic`): [ASK]
+- **Minimum SDK version**: [ASK]
+- **Default model ID**: [ASK]
+- **Authentication**: API key env var name, or endpoint URL, or both: [ASK]
+- **Model pricing**: dict of model names to `{"prompt": cost_per_1k, "completion": cost_per_1k}`, or `0.0` for free/local: [ASK]
+- **Lazy or eager import**: Use lazy import (try/except inside methods) if the SDK is an optional dependency. Use eager import if the SDK is in `install_requires`.
+
+## Files to Touch (in order)
+
+### 1. `prompture/drivers/{provider}_driver.py` (NEW)
+
+Follow this exact skeleton — match the style of existing drivers:
+
+```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": 0.00, "completion": 0.00},
+        "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 call here ---
+
+        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}
+```
+
+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`.
+- If the SDK is optional, wrap its import inside `generate()` or `__init__` in try/except and raise a clear `ImportError` pointing to `pip install prompture[{provider}]`.
+
+### 2. `prompture/drivers/__init__.py`
+
+- Add import at top: `from .{provider}_driver import {Provider}Driver`
+- Add entry 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 import line from `.drivers`.
+- Add `"{Provider}Driver"` to `__all__` in the `# Drivers` section.
+
+### 4. `prompture/settings.py`
+
+Add settings fields inside the `Settings` class, following the existing pattern:
+
+```python
+# {Provider}
+{provider}_api_key: Optional[str] = None
+{provider}_model: str = "default-model"
+```
+
+Add endpoint fields too if the provider uses a configurable URL.
+
+### 5. `setup.py`
+
+If the SDK is an optional dependency, add to `extras_require`:
+```python
+"{provider}": ["{sdk-package}>={min-version}"],
+```
+
+If the SDK should always be installed, add to `install_requires` instead.
+
+### 6. `.env.copy`
+
+Add a section at the end:
+```
+# {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 for `prompture/drivers/`.
+
+## Verification
+
+After all files are written:
+1. Run `python -c "from prompture import {Provider}Driver; print('OK')"` to confirm clean import.
+2. Run `python -c "from prompture.drivers import get_driver_for_model; d = get_driver_for_model('{provider}/test'); print(d.model)"` to confirm registry resolution.
+3. Run `pytest tests/ -x -q` to confirm no regressions.

prompture-0.0.33.dev2/.claude/skills/add-example.md

@@ -0,0 +1,76 @@
+# Skill: Add an Example File
+
+When the user asks to create a new usage example, follow this template and conventions.
+
+## Information to Gather
+
+- **Topic / use case** (e.g. "medical record extraction", "product review analysis"): [ASK]
+- **Which extraction method** to demonstrate: `extract_with_model`, `stepwise_extract_with_model`, `extract_and_jsonify`, `extract_from_data`, or `render_output`: [ASK if unclear]
+- **Which provider/model** to target (default: `ollama/gpt-oss:20b`): [ASK or use default]
+
+## File Conventions
+
+- Location: `examples/{descriptive_name}_example.py`
+- Filename: lowercase, underscores, ends with `_example.py`
+- Must be a standalone runnable script (no test framework dependency)
+
+## Template
+
+```python
+"""
+Example: {Title}
+
+This example demonstrates:
+1. {Feature 1}
+2. {Feature 2}
+3. {Feature 3}
+
+Requirements:
+    pip install prompture
+    # Set up your provider credentials in .env
+"""
+
+import json
+from pydantic import BaseModel, Field
+from prompture import extract_with_model  # or whichever function
+
+# ── 1. Define the output model ──────────────────────────
+
+class MyModel(BaseModel):
+    field1: str = Field(description="...")
+    field2: int = Field(description="...")
+
+# ── 2. Input text ───────────────────────────────────────
+
+text = """
+Paste 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
+
+- Use section comments with the `# ── N. Title ──` format to divide the script
+- Always print both the extracted result and the usage metadata
+- Use realistic sample text, not placeholder lorem ipsum
+- Import only from `prompture` public API (never internal modules)
+- Include a docstring header listing what the example demonstrates and any setup requirements
+- If the example needs a specific provider, mention the env var in the docstring
+- Keep it under 80 lines if possible — examples should be concise

prompture-0.0.33.dev2/.claude/skills/add-field.md

@@ -0,0 +1,72 @@
+# Skill: Add Field Definitions
+
+When the user asks to add new field definitions to the registry, follow this process.
+
+## Information to Gather
+
+Ask the user:
+- **Field name(s)** — lowercase, underscore-separated (e.g. `linkedin_url`, `blood_type`)
+- **Category** — which logical group (Person, Contact, Professional, Financial, etc.) or a new category
+- **For each field**: type, description, instructions, default value, nullable, and optionally enum values
+
+## Where Fields Live
+
+All predefined fields are in `prompture/field_definitions.py` inside the `BASE_FIELD_DEFINITIONS` dict, organized by category comments.
+
+## Field Definition Structure
+
+Every field follows this exact shape:
+
+```python
+"field_name": {
+    "type": str,           # Python type: str, int, float, bool, list, dict
+    "description": "What this field represents.",
+    "instructions": "How the LLM should extract or compute this value.",
+    "default": "",         # Type-appropriate default (0 for int, "" for str, [] for list, False for bool)
+    "nullable": False,     # True if the field can be None/null
+},
+```
+
+### Optional keys
+
+- `"enum"`: list of allowed string values (e.g. `["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 the new field(s) to `BASE_FIELD_DEFINITIONS` under the appropriate category comment block. If the category is new, add a clear comment header like:
+
+```python
+    # ── Medical Fields ──────────────────────────────────
+```
+
+Place the entries in alphabetical order within their category.
+
+### 2. Verify
+
+Run:
+```bash
+python -c "from prompture.field_definitions import get_field_definition; print(get_field_definition('field_name'))"
+```
+
+Then run the field definitions tests:
+```bash
+pytest tests/test_field_definitions.py -x -q
+```
+
+## Example
+
+Adding a `blood_type` field:
+
+```python
+"blood_type": {
+    "type": str,
+    "description": "Blood type classification (ABO system with Rh factor).",
+    "instructions": "Extract the blood type. Use standard notation: A+, A-, B+, B-, AB+, AB-, O+, O-.",
+    "default": "",
+    "nullable": True,
+    "enum": ["A+", "A-", "B+", "B-", "AB+", "AB-", "O+", "O-"],
+},
+```

prompture-0.0.33.dev2/.claude/skills/add-test.md

@@ -0,0 +1,87 @@
+# Skill: Add Tests
+
+When the user asks to add tests for new or existing functionality, follow these conventions.
+
+## Test Infrastructure
+
+- Framework: `pytest`
+- Test directory: `tests/`
+- Shared fixtures and helpers: `tests/conftest.py`
+- Default test model: `DEFAULT_MODEL` from `conftest.py` (currently `"ollama/gpt-oss:20b"`)
+- Integration marker: `@pytest.mark.integration` (skipped by default, run with `--run-integration`)
+
+## Key Fixtures and Helpers (from conftest.py)
+
+```python
+# Fixtures
+sample_json_schema      # Standard {"name": str, "age": int, "interests": list} schema
+integration_driver      # Driver instance from DEFAULT_MODEL (skips if unavailable)
+
+# Assertion helpers
+assert_valid_usage_metadata(meta)          # Validates prompt_tokens, completion_tokens, total_tokens, cost, raw_response
+assert_jsonify_response_structure(response) # Validates json_string, json_object, usage keys
+```
+
+## Test File Naming
+
+- `tests/test_{module}.py` — maps to source module (e.g. `test_core.py`, `test_field_definitions.py`)
+- `tests/test_{feature}.py` — for cross-cutting features (e.g. `test_toon_input.py`, `test_enhanced_extraction.py`)
+
+## Test Class and Function Conventions
+
+```python
+import pytest
+from prompture import extract_with_model, get_driver_for_model
+from tests.conftest import DEFAULT_MODEL  # if needed
+
+
+class TestFeatureName:
+    """Tests for {feature description}."""
+
+    def test_basic_behavior(self):
+        """What the test verifies in plain English."""
+        result = some_function(...)
+        assert result["key"] == expected
+
+    def test_edge_case(self):
+        """Edge case: empty input."""
+        ...
+
+    def test_error_handling(self):
+        """Should raise ValueError on invalid input."""
+        with pytest.raises(ValueError, match="expected message"):
+            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):
+        """End-to-end extraction with live model."""
+        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 call): No marker needed, should always pass
+- **Integration tests** (live LLM call): Must have `@pytest.mark.integration`
+- Use `conftest.py` fixtures and helpers — don't redefine them
+- One test class per logical group, clear docstrings
+- Test both happy path and error cases
+- For driver tests, mock the HTTP layer (use `unittest.mock.patch` or `responses` library) for unit tests
+
+## Running
+
+```bash
+pytest tests/                           # Unit tests only
+pytest tests/ --run-integration         # Include integration tests
+pytest tests/test_core.py -x -q         # Single file, stop on first failure
+pytest tests/test_core.py::TestClass::test_method  # Single test
+```

prompture-0.0.33.dev2/.claude/skills/run-tests.md

@@ -0,0 +1,32 @@
+# Skill: Run Tests
+
+When the user asks to run tests, use the appropriate command based on what they want.
+
+## Commands
+
+| Intent | Command |
+|--------|---------|
+| All unit tests (default) | `pytest tests/ -x -q` |
+| All tests including integration | `pytest tests/ --run-integration -x -q` |
+| Specific test file | `pytest tests/{file}.py -x -q` |
+| Specific test class | `pytest tests/{file}.py::{ClassName} -x -q` |
+| Specific test function | `pytest tests/{file}.py::{ClassName}::{test_name} -x -q` |
+| With verbose output | Add `-v` instead of `-q` |
+| Show print output | Add `-s` |
+| Skip integration if no creds | `TEST_SKIP_NO_CREDENTIALS=true pytest tests/ --run-integration -x -q` |
+| Using test.py runner | `python test.py` |
+
+## Flags Reference
+
+- `-x` — Stop on first failure
+- `-q` — Quiet output (just dots and summary)
+- `-v` — Verbose (show each test name)
+- `-s` — Show stdout/stderr (print statements)
+- `--run-integration` — Include `@pytest.mark.integration` tests
+- `-k "pattern"` — Run tests matching name pattern
+
+## After Running
+
+- If tests pass: Report the count (e.g. "137 passed, 1 skipped")
+- If tests fail: Read the failure output, identify the root cause, and fix it
+- Always run tests after making changes to any source file under `prompture/`

prompture-0.0.33.dev2/.claude/skills/scaffold-extraction.md

@@ -0,0 +1,71 @@
+# Skill: Scaffold an Extraction Pipeline
+
+When the user wants to build a new extraction use case (e.g. "extract medical records", "parse invoices", "analyze reviews"), scaffold the full pipeline: Pydantic model, field definitions, extraction call, and test.
+
+## Information to Gather
+
+- **Domain / use case**: What kind of data are we extracting? [ASK]
+- **Fields**: List of fields with types, or let me infer from a sample text [ASK]
+- **Provider/model**: Which model to target (default: `ollama/gpt-oss:20b`) [ASK or use default]
+- **Extraction method**: One-shot (`extract_with_model`) or stepwise (`stepwise_extract_with_model`) [ASK or recommend based on complexity]
+
+## Output Files
+
+### 1. Pydantic Model (add to existing or new module)
+
+```python
+from pydantic import BaseModel, Field
+
+class InvoiceData(BaseModel):
+    vendor_name: str = Field(description="Company or person that issued the invoice")
+    invoice_number: str = Field(description="Unique invoice identifier")
+    total_amount: float = Field(description="Total amount due in the invoice currency")
+    currency: str = Field(default="USD", description="ISO 4217 currency code")
+    line_items: list = Field(default_factory=list, description="List of individual items")
+```
+
+Rules for the model:
+- Use `Field(description=...)` on every field — these become LLM instructions
+- Use type-appropriate defaults: `""` for str, `0` for int, `0.0` for float, `[]` for list
+- Use `Optional[T] = None` only when a field genuinely might not exist in the source
+
+### 2. Field Definitions (optional, if reuse is desired)
+
+Register fields in `prompture/field_definitions.py` using the add-field skill pattern. Only do this if the fields are general-purpose enough to reuse across projects.
+
+### 3. Example Script
+
+Create `examples/{domain}_extraction_example.py` following the add-example skill template.
+
+### 4. Tests
+
+Create tests following the add-test skill pattern:
+- Unit test: Validate the Pydantic model accepts expected data shapes
+- Integration test: End-to-end extraction from sample text
+
+## Extraction Method Selection Guide
+
+| Scenario | Recommended Method |
+|----------|-------------------|
+| Simple model, < 8 fields | `extract_with_model` (one-shot, 1 LLM call) |
+| Complex model, 8+ fields | `stepwise_extract_with_model` (per-field, N calls but more accurate) |
+| No Pydantic model, raw schema | `extract_and_jsonify` |
+| Structured input data (CSV, JSON) | `extract_from_data` (TOON input, saves 45-60% tokens) |
+| DataFrame input | `extract_from_pandas` |
+| Non-JSON output (text, HTML, markdown) | `render_output` |
+
+## Sample Extraction 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 model instance
+usage = result["usage"]         # Token counts and cost
+```

prompture-0.0.33.dev2/.claude/skills/update-pricing.md

@@ -0,0 +1,46 @@
+# Skill: Update Model Pricing
+
+When the user asks to update pricing for a provider's models, follow this process.
+
+## Where Pricing Lives
+
+Each driver has a `MODEL_PRICING` class variable — a dict mapping model names to cost-per-1K-token values:
+
+```python
+class OpenAIDriver(Driver):
+    MODEL_PRICING = {
+        "gpt-4o": {"prompt": 0.005, "completion": 0.015},
+        "gpt-4o-mini": {"prompt": 0.00015, "completion": 0.0006},
+        "default": {"prompt": 0.002, "completion": 0.002},
+    }
+```
+
+Files to check:
+- `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) all use `0.0`.
+
+## Steps
+
+1. **Search the web** for the latest pricing page for the provider (e.g. "OpenAI API pricing 2026")
+2. **Read** the current `MODEL_PRICING` dict in the driver file
+3. **Update** prices, add new models, remove discontinued models
+4. **Verify** the `"default"` entry still makes sense as a fallback
+5. **Run tests**: `pytest tests/ -x -q`
+
+## Pricing Format
+
+- Values are **cost per 1,000 tokens** in USD
+- Always include both `"prompt"` and `"completion"` keys
+- Always keep a `"default"` entry as fallback
+- Some drivers have extra keys like `"tokens_param"` or `"supports_temperature"` — preserve those
+
+## Also check `prompture/discovery.py`
+
+The discovery module reads `MODEL_PRICING` keys to list available models. Adding/removing models from pricing automatically updates discovery.

prompture-0.0.33.dev2/.mcp.json

@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "fetch": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    },
+    "sequential-thinking": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequentialthinking"]
+    }
+  }
+}

{prompture-0.0.33.dev1 → prompture-0.0.33.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 0.0.33.dev1
+Version: 0.0.33.dev2
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Home-page: https://github.com/jhd3197/prompture
 Author: Juan Denis